The RakuDoc to HTML-Extra renderer
=begin rakudoc :type<renderer>
AUTHOR
Richard Hainsworth, aka finanalyst
VERSION
v0.1.0
SYNOPSIS
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.
Overview
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 | see website |
FontAwesome | Include FontAwesome icons using ā±<> markup, where ā± is U+2131 | see website |
ListFiles | Provides | Artistic-2.0 |
SCSS | Creates CSS files from SCSS declared in other plugins configuration | MIT |
Hilite | Syntax highlights code blocks | Artistic-2.0 |
RakuDoc::Render plugins
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/[email protected]/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
block-name, the custom block that activates the plugin (a plugin may need only replace existing templates)
js-link, a list of
Str, Int $orderarrays. 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 $orderarrays. 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.
Customisability
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' });
=place semantic:AUTHOR :caption<Credits>
=place semantic:VERSION :!toc =end rakudoc