=begin rakudoc :type<renderer>

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.

Vanilla HTML and CSS

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.

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.

Debug options

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

=place semantic:AUTHOR :caption<Credits>

=place semantic:VERSION :!toc =end rakudoc