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

HR§

HR§

HR§

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:

Let me not to the marriage of true minds
Admit impediments; love is not love
Which alters when it alteration finds,
Or bends with the remover to remove.
William Shakespeare
Sonnet 116

New Format Codes§

Plugins also can be used to create new format code, in addition to the specified ones.

The difference between a Pod-block and a FormatCode is that a block is line oriented, where as format codes are word/character oriented and can appear inside a line.

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 . This means a character/glyph more appropriate in another language can be used in place of, for example B for bold.

Here are two examples of new format codes:

• leveraging the format code F<> to generate FontAwesome icons.

• creating a deprecation code to show how information about changes to documentation can be signalled to the reader.

Fontawesome v5.15.4§

The code only uses the free icons. See font search page. Make sure to filter for the free icons.

Some FontAwesome icons
 
F<fas fa-ambulance> Example of ambulance
 
F<fas fa-car> Example of automobile
 
F<fas fa-bicycle> Example of bicycle
 
F<fas fa-bus> Example of bus
 
F<fas fa-truck> Example of truck
 
F<fas fa-wheelchair> Example of wheelchair
 
F<fas fab-accessible-icon> Example of accessible-icon (was wheelchair-alt in fontawesom v4)

Generates Some FontAwesome icons

Example of ambulance

Example of automobile

Example of bicycle

Example of bus

Example of truck

Example of wheelchair

Example of accessible-icon (was wheelchair-alt in fontawesome v4)

FontAwesome has some other options.

Train normal size F<fas fa-train> Triple size train F<fas fa-train|fa-3x>
 
An animated spinner F<fas fa-sync|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.

Deprecation code§

Suppose some functionality has been deprecated, or added, to documentation. Rather than deleting the documentation, and so hiding information from developers trying to maintain code, meta text is added to the code which can be viewed by hovering a mouse over it (when rendered into HTML, but another strategy can be adopted for other formats).

For example, the following Rakudoc markup

    This is some text about D<function this-might-be-useful(Str:D $indeed) | Replaced with function much-more-useful(Str:D $indeed)>.
    Try hovering over the outlined text

renders as:

This is some text about function this-might-be-useful(Str:D $indeed). Try hovering over the outlined text

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

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<fas 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<fas 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*}