Based on RakuAST-RakuDoc-Render engine, HTML with plugins and Bulma CSS
In a clean directory containing only a RakuDoc source, eg wp.rakudoc use the terminal command
RAKUDO_RAKUAST=1 raku -MRakuDoc::Render -MRakuDoc::To::HTML --rakudoc=HTML-Extra wp.rakudoc > wp.html
Easier (once the distribution has been installed, see README)
RenderDocs --html --extra --src='.' --to='.' wp
Both will cause the file wp.html to be generated in the current working directory from wp.rakudoc in CWD.
To view this file (adapt according to browser), open file://<home-path-to>/wp.html. All the JS and CSS are packaged in the HTML file, or downloaded from a CDN.
This renderer allows for more customisability than the minimal HTML renderer in this distribution.
By default, the following plugins are provided, and more can be added by the user (see Plugins).
| Plugin | Source | Use | License |
|---|---|---|---|
| Bulma | Use the Bulma CSS for the page, which is styled into panels, is responsive, has themes | MIT | |
| LeafletMaps | Home page and Github repo | Puts a map in a web page, with tiles from multiple providers | 2-clause BSD |
| Latex | Uses CodeCogs online equation editor to render formulae | see website | |
| Graphviz | Allows for figures/diagrams to be described in the dot language | see website | |
| FontAwesome | Include FontAwesome icons using ℱ<> markup, where ℱ is U+2131 | see website | |
| ListFiles | Provides =ListFiles custom block | Artistic-2.0 |
Customisation is provided by plugins. These are essentially classes of the form RakuDoc::Plugins::XXX, where XXX is the name of a plugin.
An illustrative example of the plugin class is for the Bulma CSS:
use experimental :rakuast;
use RakuDoc::Templates;
use RakuDoc::PromiseStrings;
use RakuDoc::Render;
unit class RakuDoc::Plugin::Bulma;
has %.config = %(
:name-space<bulma>,
:license<Artistic-2.0>,
:credit<https://https://bulma.io , MIT License>,
:author<Richard Hainsworth, aka finanalyst>,
:version<0.1.0>,
:css-link(['href="https://cdn.jsdelivr.net/npm/bulma@1.0.1/css/bulma.min.css"',1],),
:js-link(['src="https://rawgit.com/farzher/fuzzysort/master/fuzzysort.js"',1],),
:js(['',2],), # 1st element is replaced in TWEAK
:css([]),
);
submethod TWEAK {
%!config<js>[0][0] = self.js-text;
%!config<css>.append: [self.chyron-css,1], [ self.toc-css, 1];
}
method enable( RakuDoc::Processor:D $rdp ) {
$rdp.add-templates( $.templates );
$rdp.add-data( %!config<name-space>, %!config );
}
method templates {
%(
final => -> %prm, $tmpl {
qq:to/PAGE/
<!DOCTYPE html>
... <!- the rest of the template is omitted ->
PAGE
},
)
}
Each RP class must have a %.config attribute containing the information needed for the plugin. These are divided into mandatory keys and plugin-specific.
The mandatory key-value Pairs are:
license, typically Artistic-2.0 (same as Raku), but may need to change if the plugin relies on software that has another license.
credits, a source for the software, and the license its developers use.
version, a version number for the plugin.
authors, the author(s) of the plugin.
name-space, the name of the plugin's name-space within the RakuDoc-Processor instance.
Some typical config fields are
js-link, a list of Str, Int $order arrays. The string is placed in script tag in the head container of the web-page, the order is to ensure that when one js library must appear before another, that relation is created. Libraries with the same order appear in alphabetic order.
css-link, a list of Str, Int $order arrays. As above, but for CSS. Typically, CSS files must appear before the JS files they are associated with. All CSS files appear in head before JS files.
All the elements of %.config are transferred to the RakuDoc::Processor object, and can be accessed in a template or callable, as $tmpl.globals.data<plugin-name-space> (assuming that the plugin's config has namespace = plugin-name-space>).
The enable method is mandatory. It is used to add data and templates to the RakuDoc::Processor object created by the RakuDoc::To::HTML-Extra renderer.
A user can create a custom plugin class (eg. RakuDoc::Plugin::MyFunc), which should then be installed in the environment.
The plugin can be enabled, for example by running the following in the repo root directory
zef install -/precompile-install .
Note the option -/precompile-install turning off the precompilation. This is because currently this distribution has some modules that depend on the RakuAST compiler, and some that use the standard Rakudo compiler. Precompilation does not handle the situation robustly. However, when a use or require is encountered, the relevant module is correctly compiled and loaded.
In order to enable RakuDoc::Plugin::MyFunc, create a file called rakudoc-config.raku in the current working directory. The file should be a raku program that yields a sequence or array, eg.
use RakuDoc::To::HTML-Extra;
my @plugs = @HTML-Extra-plugins;
@plugs.append: 'MyFunc';
@HTML-Extra-plugins contains the default plugins called by RakuDoc::To::HTML-Extra.
So the code above adds MyFunc to the list, and the plugin RakuDoc::Plugin::MyFunc will now be enabled after all of the default plugins called by RakuDoc::To::HTML-Extra.
It is also possible to disable a default plugin by passing an array that does not contain the plugin to be disabled. Suppose it is desired to disable the SCSS plugin, then create (include) the following code in rakudoc-config.raku:
use RakuDoc::To::HTML-Extra;
my @plugs = @HTML-Extra-plugins;
@plugs.grep({ $_ ne 'FontAwesome' });