These are the cool possibilities using the Collection and Raku::Pod::Render distributions.

(The repeated headings in the Table of Contents are deliberate, as will become clear in this text.)

Assigning new classes to standard HTML templates.

For example, <hr> .

=for HR :class<yellowish-dots>

=for HR :class<bluish-dots>

=for HR :class<greenish-dots>

renders as

Plugins to keep customisation together

Raku::Pod::Render introduces the idea of 'plugins' to keep block names and the templates associated with them together. Collection takes the concept further by having plugins that can run Raku programs at each stage of the Collection process, after the Mode has been configured.

Plugins keep the CSS, templates and new custom block names in the same sub-directory.

This mechanism also means that Mode specific output, such as scripts and CSS for HTML output can be managed by Mode plugins. The Website mode for Collection-Raku-Documentation contains plugins to gather CSS, jQuery scripts, js libraries, and Images from other plugins, and collate them so that they are served with each page.

Since the entire page is in a template, it is also possible to create separate page templates, with different CSS assets.

The following are Custom user-facing Pod::Blocks that come with Collection-Raku-Documentation

Camelia icon headers with images

For Raku files, a special block was created for the various types of Camelia image. They normally float on the right-hand side. In order to contain them before the next set of texts, they are included in an HTML5 flex-box, which is created using a template for para.

The following code

=begin para :template<flex-container>
=Camelia
=CameliaShadow
=CameliaFaded
=end para

yields

Adding new templates for existing Pod::Blocks

Suppose you want a different template to act on an existing block, like Para, which is coded as HTML <p>. For example,

I like this sonnet:
=for para :template<quotation> :author<William Shakespeare> :citation<Sonnet 116>
Let me not to the marriage of true minds\n
Admit impediments; love is not love\n
Which alters when it alteration finds,\n
Or bends with the remover to remove.

I like this sonnet:

New Format Codes

Here is an example where the format code F has been leveraged to generate FontAwesome icons. The plugin here utilises v4.7. The API for v5 / 6 is different, so another plugin may be needed.

Since Raku treats all Unicode characters the same, Chinese/Arabic/Cyrillic glyphs can now be specified to repeat or alias the predefined codes of B C I K T U E Z X N L P V .

Some FontAwesome icons

F<fa-ambulance> Example of ambulance

F<fa-automobile> Example of automobile (alias)

F<fa-bicycle> Example of bicycle

F<fa-bus> Example of bus

F<fa-truck> Example of truck

F<fa-wheelchair> Example of wheelchair

F<fa-wheelchair-alt> Example of wheelchair-alt

Generates Some FontAwesome icons

Example of ambulance

Example of automobile (alias)

Example of bicycle

Example of bus

Example of truck

Example of wheelchair

Example of wheelchair-alt

FontAwesome has some other options.

Train normal size F<fa-train> Triple size train F<fa-train|fa-3x>

An animated spinner F<fa-refresh|fa-spin fa-3x fa-fw>

Generates

Train normal size Triple size train

An animated spinner

Notice how these examples leverage off the idea of meta data together with a Format Code. This is not standard Rakudoc (aka POD6), as this metadata is only specified for X<> and L<> . Raku::Pod::Render allows for metadata to be added to any non-standard letter used as a Format Code, and any Unicode thingy that Raku treats as a "character" to be made into a Format Code.

Compilation blocks

When many Rakudoc files are included in a collection, there is a need to collect data from each. So for example, the Raku Documentation files all have metadata associated with the first pod definition. We need to collect files according to the metadata. The keys kind, subkind, and category are allocated to all Raku Documents.

=for ListFiles :select<kind=Programs>
Programs that support Raku development

renders as

=for ListFiles :select<kind=Programs> :headlevel(0)
Programs that support Raku development, title is not included in the TOC.

Other examples of ListFiles can be seen in the TOC and Itemised index pages.

Images

Content files today, especially for the Web, rely on images.

=for Image :src<images/octopus_build.gif> :class<justify-center>
New searching functionality is being developed

Generates an image with the text in the Table of Contents. The TOC entry can be eliminated with a :headlevel(0).

JQuery Plugins

All websites need JQuery plugins or JS scripts. Collection creates the infrastructure for these plugins to be written and added to a site.

For example, the filterlines plugin uses a small JQuery script, adds some html around existing Rakudoc content and handles everything else. (Try typing 'R' then 'e' in the search box).

=begin filterlines
=for ListFiles :select<kind=Programs>
Programs that support Raku development
=end filterlines

renders as

=begin filterlines

LeafletMap

The leafletmap plugin inserts a map in place of the =LeafletMap Pod::Block using the fabulous Leaflet JS library. The map MUST have a fixed height, so this is specified in the config file. However, height and width should be set by CSS, but it is not clear what the best way is to signal that a CSS value is available from CSS in the config file.

By default, the map will point at Cardiff Castle in Cardiff, Wales with a 200px height and 16 unit magnification, using OpenStreetMap as the tile provider. So

=Leafletmap

produces:

The simplest customisation is to centre the map by specifying the lattitude and longitude, and to change the starting zoom level (smaller numbers are larger views). It is also possible to change the height of the map. Each map on a page must have its own id. Additionally, when developing a page, not setting a width is tiresome. Note another very underutilised feature of Rakudoc, the ability to spread meta-data accross lines. The first virtual column must start in a = and there must be at least one horizontal whitespace character. Thus

=for Leafletmap
=  :lat(55.948595) :long(-3.199913)
=  :zoom(13) :height<300px>
=  :id<new-map>
=  :headlevel(2)
=  :width<50vw>
Edinburgh Castle

will produce

Maps are generated from tiles and the information can be rendered in many ways. There are multiple tile providers, collected in a github resource leaflet-extras. "Leaflet-providers provides tile layers from different providers, including OpenStreetMap, Stamen, Esri and OpenWeatherMap. The full listing of free to use layers can be previewed." (from README of leaflet-providers)

Some providers have map types that do not need registration, most types need registration. Here are all the providers and variants.

For example, is a map with the Esri.WorldImagery provider[.variant] string.

=for LeafletMap :provider<Esri.WorldImagery> :id<third-map> :width<50vw>

Registration offers more variety and more complex maps, but goes beyond the generic Collection plugin.

However, the extra customisation is possible by changing the config file and the template for the =Leafletmap block.

For example, suppose you have registered with Thunderforest and obtained an api-key, eg. xxxx. Then in config.raku uncomment 'api-key' and insert your key in place of ????. The template already allows for an apikey field, but some providers require other variable names, or two variables. More information can be found in leaflet-extras.

Another common need is to put markers on a map. This can be done using =LeafMarker blocks. The map-id of the map the markers are to be associated with has to be supplied if there are more than one maps on a page, otherwise the default map id is used.

:popup<text> associated the text with the marker but the user needs to click in it to see.

:title<text> allows for the text to be visible with a mouseover.

:fa-icon will work if the FontAwesome plugin has been configured for rendering (see above for detail on extra commands).

:headlevel(0) is set so that the Table of Contents is not affected.

=for LeafletMap :id<map-four> :height<600px> :zoom(12) :width<50vw>

=for LeafMarker
=    :map-id<map-four> :name<mk1>
=    :lat(51.48160) :long(-3.18070)
=    :headlevel(0)
=    :title<Cardiff Castle>

=for LeafMarker
=    :map-id<map-four>
=    :lat(51.529269) :long(-3.188109)
=    :fa-icon<fa-cutlery fa-spin fa-3x fa-fw>
=    :headlevel(0)
=    :title<Fintans Fish & Chip Co>

=for LeafMarker
=    :map-id<map-four>
=    :lat(51.502576) :long(-3.190222)
=    :fa-icon<fa-cutlery>
=    :headlevel(0)
=    :popup<Yan’s Fish Bar>

Thus for two chippies judged the best in Cardiff at the time of writing:

Graphviz

This block introduces a directed graph in the dot language. It is rendered into HTML as an svg using the dot program. Since a graph data is require, only the delimited form of the block (starting with =begin/=end) will be used.

The following diagraph comes from the dot documentation. The following Rakudoc

=begin Graphviz :headlevel(0)
    digraph G {
        main -> parse -> execute;
        main -> init;
        main -> cleanup;
        execute -> make_string;
        execute -> printf
        init -> make_string;
        main -> printf;
        execute -> compare;
    }
=end Graphviz

produces

Latex

This plugin block sends the Latex markup to the CodeCogs online equation editor. For example,

=for Latex :headlevel(0)
\begin{align*}
\sum_{i=1}^{k+1} i^{3}
&= \biggl(\sum_{i=1}^{n} i^{3}\biggr) +  i^3\\
&= \frac{k^{2}(k+1)^{2}}{4} + (k+1)^3 \\
&= \frac{k^{2}(k+1)^{2} + 4(k+1)^3}{4}\\
&= \frac{(k+1)^{2}(k^{2} + 4k + 4)}{4}\\
&= \frac{(k+1)^{2}(k+2)^{2}}{4}
\end{align*}