Rendering RakuDoc v2 to HTML

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.

SYNOPSIS§

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

Credits§

「semantic_AUTHOR UNAVAILABLE」

VERSION§