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 document can be found online.
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
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.
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
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.
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.
The debug options described in Render can be invoked using , eg.,
RAKURENDEROPTS='Templates BlockType' RAKUDO_RAKUAST=1 raku -I. -MRakuDoc::Render --rakudoc=HTML new-doc.rakudoc > new-doc.html