<span id="506b2f3ea9c2ce5b60471bdf0b07f2316343fc79"></span>RakuDoc v2 is rendered to minimal HTML. `RakuAST::RakuDoc::Render` on which this module is based uses the RakuAST parser. A rendering of the [compliance](Compliance_testing) document can be [found online](https://htmlpreview.github.io/?https://github.com/finanalyst/rakuast-rakudoc-render/blob/main/resources/compliance-rendering/rakudociem-ipsum.html).
SYNOPSIS
Vanilla HTML and CSS
Credits
Currently, the module is difficult to install using zef, so the instructions below are relative to local repo of RakuDoc::Render repo.
Use the utility force-recompile with the current working directory being the root of the RakuDoc::Render repo bin/force-recompile
Assuming (the assumptions are for clarity and can be changed):
• there is a RakuDoc source new-doc.rakudoc in the current working directory,
• the current working directory is the root directory of the repo, /home/me/rakuast-rakudoc-render
• the distribution has been tested on Ubuntu 6.5.0-35-generic #35~22.04.1-Ubuntu
▹ [feedback of testing on other OS, and tweaks to improve, would be appreciated !]
• a recent Rakudo build is needed; v2024.05-34-g5dd0ad6f5 works.
Then: RAKUDO_RAKUAST=1 raku -I. -MRakuDoc::Render --rakudoc=HTML new-doc.rakudoc > new-doc.html
generates new-doc.html in the current working directory.
The aim of RakuDoc::To::HTML is to produce a minimal HTML output with minimal styling, and that the file can be directly viewed in a modern browser with the URL file:///home/me/rakuast-rakudoc-render/new-doc.html.
Unfortunately some systems for opening HTML files in a browser will HTML-escape Unicode characters used for delimiting texts. So, just open the file in a browser.
The styling is generated from resources/scss/vanilla.scss to produce resources/css/vanilla.css, which is slurped into the HTML output file (eg. new-doc.html).
By the design of the RakuDoc::Render module, all output is generated using templates. The module RakuDoc::To::HTML attaches a minimum set of templates. It is possible to override any or all of the templates by adding the MORE_HTML environment variable. Assuming the file my_new_html.raku exists in the current working directory, and the file follows the Template specification, then MORE_HTML=my_new_html.raku RAKUDO_RAKUAST=1 raku -I. -MRakuDoc::Render --rakudoc=HTML new-doc.rakudoc > new-doc.html
will utilise the new templates. An example can be seen in xt/600-R-2-HTML.rakutest. The intention of each template can be found in the comments within lib.RakuDoc/To/HTML.rakumod.
To tweak the styling:
• install sass is available
• copy the file /home/me/rakuast-rakudoc-render/resources/scss/vanilla.scss to a new file, eg. ~/tweaks/strawberry.scss
• tweak the styling (many classes used in the HTML output have zero styling)
• run sass ~/tweaks/strawberry.scss to generate ~/tweaks/strawberry.css
▹ the sass command is usefully run as --update -s compressed ~/tweaks/strawberry.scss
• use the ALT_CSS environment variable to load the new CSS.
<span id="8618e26f94484888a049bd6f7bc57b5aeca6e2d2"></span>ALT_CSS=~/tweaks/strawberry.sss RAKUDO_RAKUAST=1 raku -I. -MRakuDoc::Render --rakudoc=HTML new-doc.rakudoc > new-doc.html
Both ALT_CSS and MORE_HTML can be used, adding new HTML tags, or changing class names, then including CSS definitions in the file accessed by ALT_CSS.
Note that there is a difference between how the CSS and Template files are used.
• By design, new Raku closure templates, eg, those defined in files given to MORE_HTML, are placed at the head of a chain of templates, and so are in addition to those previously defined.
• The alternate CSS file (eg ~/tweaks/strawberry.css) is used instead of the default vanilla.css.
v0.1.0
Rendered from docs/docs/RakuDoc-To-HTML.rakudoc at 11:20 UTC on 2024-06-23
Source last modified at 10:55 UTC on 2024-06-23
1: Still waiting for ｢semantic-schema_AUTHOR｣ to be expanded.