Coder Legion - Recent posts tagged rakulang

Using in-line markup in RakuDoc. Article 2

Wed, 21 Jan 2026 16:42:11 +0000

This continues the series starting with RakuDoc more than ... The images here will be generated using the Docker container described in the first article.

In this article I will be discussing some of the markup codes which can be used in a RakuDoc source.

The next few articles planned will cover

Block types, such header, formulas, paragraphs, indented paragraphs
How to include images, and how to customise their placing.
Some custom block types that are included with the Rakuast::RakuDoc::Renderer, but which are not specified in standard RakuDoc.
Enumerations of blocks, that is creating numbered headings, items, code etc.

Update of browser editor

The browser editor container has been updated since the last article, and contains a new button. We will give an example of this below. However, it does require that your computer has an internet connection.

As a reminder, the browser can be started (assuming podman is installed) as follows for Ubuntu type distributions:

podman pull docker.io/finanalyst/browser-editor:latest
podman run -d -v .:/browser/publication --rm docker.io/finanalyst/browser-editor:latest

And on Mac silicon

podman pull docker.io/finanalyst/browser-editor:latest
podman run -d -v.:/browser/publication --platform linux/amd64 --rm docker.io/finanalyst/browser-editor:latest

To stop the container

run podman ps and note the name of the container, eg good_person
run podman stop good_person

Comparison of styling using other systems

It is very useful for a reader when the author lays out text in a pleasant manner, including spaces between paragraphs, and styling words within paragraphs to draw attention to them.

Practices that at first are considered considerate, become mandatory over time. For example, the very first styling of text came in Roman times, when good practice was to separate the letters making up words with spaces, and then to use punctuation marks. Now it is impossible to eliminate spaces and poor punctuation is a sign of a poor education. Here is an interesting article on punctuation.

Let's consider the ways in which we can highlight a word by making it bolder.

In an MS Word document, an author will highlight the words to be emboldened and then use Ctrl-B or the equivalent on a Mac. This is a quick and easy way of styling, unless the author decides too many bold words exist and wants to restyle to Italic. Then it becomes a hassle to change.

Using MarkDown, it is much easier in that the words to be styled are 'bracketed' using special characters, so ** ... ** are used to embolden, while * ... * are used for italicising. There are a few other characters such as `` for code. But as soon as you need more sophisticated styling, such as pushing the characters up as in exponentiation, or down, it's necessary to use HTML tags. However, the upside is that unlike an WYSIWYG editor, like Word, changing the styling is easy: change the styling character. And yet ... each different type of style, or rather its style character, has to be learnt.

RakuDoc approaches styling in a different way: a number of markup codes are defined in a declarative manner, and all use the same syntax, Upper case letter openercontentcloser e.g., B<a basic term>.

The simplest RakuDoc markup codes enclose text and provide a rendering, and they are:

The aim of the naming system is to provide a hint about the rendering, while leaving it to the renderer to implement the final output format.

The same syntax is used for other types of inline content. Almost all the Latin uppercase letters, and a Greek uppercase letter have been defined for standard RakuDoc. Rather than describing each of the codes, it is probably best just to look at the RakuDoc v2 specification.

However, the Markup syntax is not limited to the specified letters, and any Unicode character with the Uppercase property can be used for customised content. For example, the Rakuast::RakuDoc::Renderer comes with a custom markup for inserting Font Awesome icons into the text. Some examples are given in the documentation for the module.

The aim of these initial articles is to provide an introduction, rather than give an extensive tutorial. The best way to see how the Markup codes work is to try them in the browser.

Try copying the following RakuDoc source into the updated browser:

=begin rakudoc
=TITLE Sample
=head Introduction

This is some B<basic> highlighting showing C<my $new code> with 
SomeJ<B<junior>>andH<I<higher>> text.

Here are some FontAwesome icons (ℱ = U+2131):

Train normal size ℱ<fas fa-train> Triple size train ℱ<fas fa-train fa-3x>

An animated spinner ℱ<fas fa-sync fa-spin fa-3x fa-fw>

Click on the C<On line>/C<Off line> switch to see.

Here is an inline image P<https://cdn.esahubble.org/archives/images/screen/potw2552a.jpg>

=end rakudoc

You will get something like

If you scroll the pane to the bottom on the rendered side, you will find some warnings about errors found during the rendering. The simple HTML renderer is designed to be used offline and all the CSS and Javascript are contained inside the file.

However, we now expect online connections with CSS, images and JS libraries delivered using CDNs. So the HTML-Extra renderer uses the Bulma CSS framework and has plugins to pull in FontAwesome and the LeafletMaps library (we will cover this in a future article).

Now click on the Go on line button. It may take some moments to render and pull the image in from the Hubble telescope site.

You should get something like

Attribution: cover image from
Hubble telescope image from

RakuDoc - More than just a documentation markup

Thu, 15 Jan 2026 21:50:27 +0000

Introduction to series

This is the first article in a series about the markup language RakuDoc. In subsequent articles I will explore some of the interesting aspects of RakuDoc and how to add customisations.

In this first article, I want to discuss how RakuDoc came about, why its design allows for a wide use, and how a reader can easily (for some definitions of 'easily'?) experiment with RakuDoc in a browser using a docker image.

Raku and RakuDoc

The Raku language belongs to the family of Perl variations (and was originally known as Perl 6). The culture surrounding Raku includes as highly recommended several good coding practices, such as extensive unit testing, and documentation.

To facilitate documentation, Raku comes with its own markup language, called RakuDoc. The intention is that documentation can be included inside a program, in a similar way to inline comments, but it can also be used in standalone files to document how to use the software. RakuDoc has also taken into account Donald Knuth's literate coding ideas, although RakuDoc does not develop the fundamental ideas in the same way as others have.

Furthermore, software development has dramatically changed since Knuth: virtually all projects have many dependencies, and libraries are written that are not ever intended to be the final customer-facing product. Consequently, documentation has two distinct faces:

maintainer or code-oriented, meaning that information is given about the algorithm or the purpose of variables. This information is never intended to be available to a user of the software;
developer or text-oriented, meaning that information is given about how to use the software, and the purpose of the external interfaces.

Consequently, the documentation language for Raku needed to be usable inside the code, and also to create manual pages for developers using the software.

The result - RakuDoc - is extensively used inside code modules, but it is also used in stand-alone files. The entire documentation for the Raku language (Raku documents) is written in some 700 RakuDoc files.

Beyond documentation

It is almost certain that readers of this article have used both Markdown and MS Word (or its FOSS equivalent LibreOffice). There are other editor/format systems, but I'll use these two for simplicity.

Markdown dominates the web (and is used for CoderLegion) because it is simple, and converts naturally into HTML.

Word (LibreOffice) dominates the corporate space because (in part) it makes it easy for non-specialists to create documents that have different styles, automatic Tables of Contents, footnotes, and so on.

Expert users, however, find that Markdown is too simple - it does not allow for Tables of Content linked to headings, or footnotes that link back to the source, and custom content blocks. These limitations have been redressed in several ways, but only by creating different flavours of Markdown. A consequence of the ad hoc additions is that each type of functionality has a different syntax.

Word (LibreOffice) by contrast is too complex. It is quite easy to create a glitch, say a bold style that extends too far, or bullets points that have different styling because the line end has been deleted. The only practical way to solve these issues is to delete enough text to eliminate the underlying style marker, and start again.

It is a difficult task to create a Word file programmatically, not least because the underlying format is considered proprietary. LibreOffice files can be created programmatically, and then converted to Word.

RakuDoc is located between these extremes: it was not designed to be rendered as a document is written. The RakuDoc source can be read and easily understood by a human author, and then the source is rendered into a format, such as HTML, pdf or epub format, which is read by the end user.

To handle different styled text, such as bold, underline, RakuDoc text has markers which declaratively indicate how the text should be treated by a renderer. Markdown also uses markers that map closely to an HTML rendering, eg #, *, _. The declarative nature of RakuDoc's markup means that its B<> stands for Basic not bold, and it is left to the renderer as to what that means in say HTML or epub. Furthermore, RakuDoc has a single syntax for the markers, and the possibility to add markers.

In addition to text markers, RakuDoc has blocks that operate on chunks of text. These blocks can be associated with meta data, allowing for different styling, and customisation.

How to experiment with RakuDoc?

To make things easier for experimentation, I have created a docker image docker.io/finanalyst/browser-editor which can be run in a container, and accessed using a browser.

However, for the interested reader, the more generic way is to install Raku and then install the Rakuast::RakuDoc::Render module.

The intention of the browser editor container is for the RakuDoc source to be created and edited in a browser, which also renders the source to HTML on the fly. The edited RakuDoc source can be saved to the container's browser/publication directory, and if the container's directory is bound to a host directory, then the RakuDoc source will be saved on the local host as well.

The following is written assuming a Linux OS and so it should work with, eg., Ubuntu and Apple. I have not tested this with a MS system, and I would be happy to have comments to adapt the following.

Let's start.

We need to have podman installed.
We need an empty directory, say rakudoc-test, eg. mkdir rakudoc-test.

Inside this directory (eg., cd rakudoc-test), we run

podman run -d -v .:/browser/publication --network=host --rm docker.io/finanalyst/browser-editor:latest

Update: I have removed an underdocumented constraint. So, this should now be

podman pull docker.io/finanalyst/browser-editor:latest
podman run -d -v .:/browser/publication --rm docker.io/finanalyst/browser-editor:latest

For Mac users, try

podman pull docker.io/finanalyst/browser-editor:latest
podman run -d -v .:/browser/publication --platform linux/amd64 --rm docker.io/finanalyst/browser-editor:latest

Point a browser at localhost:3000 and the window should look like this
Edit the rakudoc file, then click on the Save button.
End the container
- run podman ps and note the name of the container, eg good_person
- run podman stop good_person

Some comments about the `podman` command.

It should pull in the latest version of the browser-editor image, bind the current directory (we are running this inside rakudoc-test) to the container's browser/publication directory, and then return a SHA identity string (don't worry, it can be forgotten). The --network=host is the simplest way to arrange for the container to serve the browser. However, podman developers consider this a possible vulnerability and there is a way to set up a network stack to run the image more safely. For those concerned about safety, the container source can be seen at github browser-editor

About the browser editor

The left-hand panel uses an instance of the Ace editor with a RakuDoc source, and the right-hand panel contains the HTML rendering of that source. The Ace editor allows for the normal editor functions, while the HTML rendering is generated as soon as the editor contents changes. Consequently, when typing it is likely that an invalid RakuDoc source will be created. Once the RakuDoc source is correct, it will be rendered into the right-hand panel. In addition, there are various RakuDoc expressions that are ambiguous, in which case, a warning will be generated that is shown at the bottom of the rendered file.

A small sample RakuDoc file is included to start off. The name of the file can be changed by editing the filename text widget, eg to web-sample.rakudoc. By pressing the Save button, the RakuDoc source is saved to the container's browser\publication\web-sample.rakudoc and if the directories are linked properly, then web-sample.rakudoc will be saved on the local system. Another file rakudociem-ipsum.rakudoc can also be selected. It contains examples of nearly all RakuDoc's features, but it can take a while to render.

Test the system

Just to test the system and to give a flavour of RakuDoc, try adding the following text after the First item line:

=for item :bullet<<\c[turkey]>>
Second item

This should produce a browser window a bit like this

Some commentary on this new text:

the line =item First item would create a bullet point similar to - First item in Markdown.
However, it is possible to change the bullet item by item by adding meta data to the item block. However, to distinguish between a block without meta data =item First and one with meta data, we use the =for directive.
Item blocks will accept a :bullet option. The contents of the bullet option are then interpreted as the bullet. Raku has several bracketing syntaxes, and the <</>> brackets (or the Unicode equivalents « ») take the contents and treat them as an interpolated string. \c[ ] takes the content as a Unicode symbol name and its interpolated value is the Unicode character. Consequently \c[turkey] is the Unicode icon (U+1F983).

So now add below the last item

=for item2 :bullet<<\c[tulip]>>
sub second item

and now there is a second level item with a new bullet, producing a window like:

Finally, lets show a bit of customisation. Try adding the following lines before the last line (=end rakudoc)

=config item :bullet<<\c[rose]>>
=item a new item
=item a second item
=item and a third one

The browser window should look something like
Here the meta option :bullet<<\c[rose]>> in the =config statement is distributed to all the =item blocks implicitly. Consequently, all the following item blocks will have that bullet option automatically.

Future articles will look at the different block types, and some custom blocks that include maps and formula, and different markup formats, such as B<> and C<>.