Rimu Reference

Rimu is a readable-text to HTML markup language inspired by AsciiDoc and Markdown.

At its core Rimu is a simple readable-text markup similar in scope to Markdown, but with two additional areas of functionality (both built into the Rimu markup syntax):

Resources

Installation

See Rimu README for installation instructions.

Learning

Example applications

See the API documentation.

Documents

A Rimu document consists of a sequence of zero or more Block elements.

Block elements

Block elements consist of one or more lines of text and may contain Inline elements and, in some cases, Block elements. Block elements are classified as either Delimited Blocks or Line Blocks.

Delimited Blocks

A Delimited Block consists of an opening delimiter line followed by zero or more content lines and terminated with a closing delimiter line. Delimited Block behaviour is user customizable.

Line Blocks

A Line Block consists of a single line. Headers, Block Attributes, single-line comments and Element Definitions are all Line Block elements.

Inline elements

Inline elements are contained within the textual content of block elements. There are three types of Inline elements: Macro Invocations, Quotes and Replacements.

Taxonomy

Rimu markup elements are categorized as follows:

Document processing

Rimu scans the input text for block elements. When a block element is matched it is converted to HTML on the output.

Block elements in the source markup are matched in the following order of precedence (first to last):

  1. Line Blocks
  2. Lists
  3. Delimited Blocks

Inline elements are processed in the following order (first to last):

  1. Macro invocations
  2. Replacements
  3. Quotes

Special character substitution takes place last. Inline substitutions in Delimited Block elements can be controlled using block-options in the Block Attributes element.

Comments

Use comments to exclude text in Rimu markup from the outputted HTML.

Single and Multi-line comments

Rimu has both single line and multi-line comment elements.

Examples:

Examples

Rimu Markup
/*
  This comment does not appear in the
  rendered HTML.
*/

// This comment does not appear in the rendered HTML.

<!-- This comment appears in the rendered HTML. -->
HTML Preview

Inline comments

The predefined Blank macro (--) can be used for inline comments:

Examples

Rimu Markup
Lorem ipsum dolor sit amet sapien.
{--!} THIS LINE IS EXCLUDED.
Imperdiet pellentesque minim.

Lorem ipsum {--|THIS TEXT IS EXCLUDED} dolor sit amet sapien.
Imperdiet pellentesque minim. {--|THIS TEXT IS EXCLUDED}

Lorem ipsum dolor sit {--|THIS TECHNIQUE CAN BE USED
TO EXCLUDE TEXT THAT SPANS MULTIPLE LINES
STARTING AND ENDING ANYWHERE} amet sapien.
Imperdiet pellentesque minim.
HTML Preview

Lorem ipsum dolor sit amet sapien. Imperdiet pellentesque minim.

Lorem ipsum dolor sit amet sapien. Imperdiet pellentesque minim.

Lorem ipsum dolor sit amet sapien. Imperdiet pellentesque minim.

See also Conditional inclusion.

Headers

A Header is a Line Block element containing a title which is prefixed by one to six # or = characters. A matching postfix is optional.

Examples

Rimu Markup HTML Preview
# h1 header
## h2 header ##
### h3 header
#### h4 _header_ ####
===== h5 header
====== h6 header

h1 header

h2 header

h3 header

h4 header

h5 header
h6 header

Fenced Blocks

Fenced blocks are Delimited Blocks bounded by opening and closing delimiter lines consisting of two or more delimiter characters starting at the left margin.

Code Block

By default the all text in a Code Block is rendered verbatim. The generated HTML is enveloped with <pre><code>...</code></pre> tags. The Code Block delimiter character is a backtick.

Examples

Rimu Markup HTML Preview
``
Nunc mauris tempor.
Scelerisque feugiat massa alias.
``
Nunc mauris tempor.
Scelerisque feugiat massa alias.

Quote Block

A Quote Block renders the enclosed block elements inside an HTML <blockquote> element. The Quote Block delimiter character can be either a double-quote or a greater-than symbol.

Examples

Rimu Markup HTML Preview
""
Nunc mauris tempor.
Scelerisque feugiat massa alias.

.cite
Anonymous
""

>>>
Nunc mauris tempor.
Scelerisque feugiat massa alias.
>>>

Nunc mauris tempor. Scelerisque feugiat massa alias.

Anonymous

Nunc mauris tempor. Scelerisque feugiat massa alias.

The above example uses the rimuc command --layout option's CSS cite class to style the Anonymous attribution.

Division Block

A Division Block is a container for block elements.

Examples

Rimu Markup HTML Preview
."font-style:italic"
..
Nunc mauris tempor.
Scelerisque feugiat massa alias.
..

Nunc mauris tempor. Scelerisque feugiat massa alias.

Division Blocks are useful for appending arbitrary block elements to list items. They can also be used to conditionally include Rimu source text.

HTML elements

Block and inline HTML elements can be mixed with Rimu markup.

Inline HTML elements

Examples

Rimu Markup
An inline <span style="color:red;">HTML span</span>.
HTML Preview

An inline HTML span.

Block HTML elements

Examples

Rimu Markup
An HTML table block element:

<table class="bordered">
  <tr>
    <td>Montes adipiscing sodales.</td>
    <td>Magna placerat posuere.</td>
  </tr>
  <tr>
    <td>Nulla suspendisse egestas nulla libero sed.</td>
    <td>Wisi ullamcorper eget.</td>
  </tr>
</table>
HTML Preview

An HTML table block element:

Montes adipiscing sodales. Magna placerat posuere.
Nulla suspendisse egestas nulla libero sed. Wisi ullamcorper eget.

Paragraphs

Paragraph block elements are terminated by a blank line (lines containing only space characters do not terminate a paragraph).

Individual paragraph behavior can be modified with a preceding Block Attributes element. The behavior of all paragraphs can be modified with a Delimited Block Definition (block name paragraph for Normal Paragraph; indented for Indented Paragraph; quote-paragraph for Quote Paragraph).

There are three paragraph types:

Normal paragraph

Normal paragraphs can contain inline elements, the first line must start at the left margin.

You can force line breaks in normal paragraphs by putting a space followed by a backslash character at the end of a line.

Line breaks can be escaped by prefixing the trailing backslash with another backslash character.

Examples

Rimu Markup HTML Preview
Nunc mauris tempor.
Scelerisque feugiat massa alias.

Nunc mauris tempor. Scelerisque feugiat massa alias.

Indented paragraph

Indented paragraphs begin with one or more space characters. By default the all text in an Indented Paragraph is rendered verbatim. This behavior can be changed using a preceding Block Attributes element. By default the generated HTML is enveloped with <pre><code>...</code></pre> tags.

Examples

Rimu Markup HTML Preview
  Nunc mauris tempor.
  Scelerisque feugiat massa alias.
Nunc mauris tempor.
Scelerisque feugiat massa alias.

Quote paragraph

Quote paragraphs begin with a > character and are rendered inside an HTML <blockquote> element. Leading > characters are optional for all lines except the first line. Leading > characters can be escaped with a backslash character. In all other respects Quote paragraphs behave the same as Normal paragraphs.

Examples

Rimu Markup HTML Preview
> Nunc mauris tempor.
  Scelerisque feugiat massa alias.

Nunc mauris tempor. Scelerisque feugiat massa alias.

Lists

Each list item includes an identifier (ID) that groups items into lists. There are three types of list: Bullet, Numbered and Labeled, each with its own unique set of list IDs.

List item ID                  List type
___________________________________________
-, +, *, **, ***, ****        Bullet list
., .., ..., ....              Numbered list
::, :::, ::::                 Labeled list
___________________________________________

Examples

Rimu Markup
- Lorem ipsum dolor sit amet dis quisque maecenas in tristique arcu
\- lorem dolor fusce nec.
  * Sit pretium quisque in wisi lobortis.
  * Ac curabitur elementum.
    ** Platea ad diam arcu vitae fermentum.
       1. Eu lorem nulla.
       2. In suspendisse at dapibus nostra est.
          .. Montes adipiscing sodales.
    ** Pellentesque nibh sit.
- Viverra pede turpis.
  Esse et dui:: Nonummy modi.
  Wisi ad diam:: Sapien porttitor.
    Condimentum::: Lacus maecenas neque dolor habitant tellus.
- Augue et dui malesuada purus.

  Purus aliquam mauris a aliquam orci. Massa sit sit.
  penatibus. Maecenas at tellus. Sapien quam mauris.
  Non a pede in.

  * Ac lacinia mi.
  * Egestas congue quam.

- Facilisi vestibulum montes quam eget donec.
..
Cras proin molestie quam sem conubia. Ligula vel elit. Elit a earum.
Arcu eget magna. Class vivamus morbi.

Ac lacinia mi. Mi in enim. Dui sed ut. Egestas congue quam. Facilisis
non magnis facilisi scelerisque luctus. Quis praesent pulvinar.
..
- Integer quisque hendrerit. Arcu nunc lorem posuere.

> Egestas congue quam.
HTML Preview
  • Lorem ipsum dolor sit amet dis quisque maecenas in tristique arcu - lorem dolor fusce nec.
    • Sit pretium quisque in wisi lobortis.
    • Ac curabitur elementum.
      • Platea ad diam arcu vitae fermentum.
        1. Eu lorem nulla.
        2. In suspendisse at dapibus nostra est.
          1. Montes adipiscing sodales.
      • Pellentesque nibh sit.
  • Viverra pede turpis.
    Esse et dui
    Nonummy modi.
    Wisi ad diam
    Sapien porttitor.
    Condimentum
    Lacus maecenas neque dolor habitant tellus.
  • Augue et dui malesuada purus.
    Purus aliquam mauris a aliquam orci. Massa sit sit.
    penatibus. Maecenas at tellus. Sapien quam mauris.
    Non a pede in.
    • Ac lacinia mi.
    • Egestas congue quam.
  • Facilisi vestibulum montes quam eget donec.

    Cras proin molestie quam sem conubia. Ligula vel elit. Elit a earum. Arcu eget magna. Class vivamus morbi.

    Ac lacinia mi. Mi in enim. Dui sed ut. Egestas congue quam. Facilisis non magnis facilisi scelerisque luctus. Quis praesent pulvinar.

  • Integer quisque hendrerit. Arcu nunc lorem posuere.

    Egestas congue quam.

Quotes

Text can be formatted by enclosing it in one or two quote characters. The built-in quotes are:

Rimu            Rendered HTML             Font style
___________________________________________________________
_emphasis_      <em>emphasis</em>         Italic
*emphasis*      <em>emphasis</em>         Italic
__strong__      <strong>strong</strong>   Bold
**strong**      <strong>strong</strong>   Bold
`code`          <code>code</code>         Monospaced
``code``        <code>code</code>         Monospaced
~~deleted~~     <del>deleted</del>        Strikethrough
___________________________________________________________

Examples

Rimu Markup HTML Preview
Some **bold text**,
some _emphasized text_,
some `monospaced text` and
some ~~deleted text~~.

Some bold text, some emphasized text, some monospaced text and some deleted text.

Quote Definition

You can modify existing quote behavior or add new quotes using Quote definitions.

Definition syntax:

quote-delimiter = '<open-tags>|<close-tags>'

The following quote definition envelopes quoted text with an HTML superscript tag:

^ = '<sup>|</sup>'

Replacements

A Replacement replaces matched source text with some other text (usually HTML markup). A replacement is defined by a regular expression (to find the matched text) and the text to be replaced.

With the exception of Quotes all Rimu Inline elements are implemented as replacements e.g. character entities, URLs, inline images, inline HTML tags.

Replacement Definition

Definition syntax:

/pattern/flags = 'replacement'

Example replacement definitions:

/\.{3}/ = '&hellip;'
/\bTODO\b/ = '<b style="color: red; background-color: yellow;">TODO</b>'

URLs

URLs and email address elements are implemented with built-in Replacements.

Syntax:

Rimu                Rendered HTML
______________________________________________________________________
url                 <a href="url">url</a>                       Note 1
<url>               <a href="url">url</a>
<url|caption>       <a href="url">caption</a>
[caption](url)      <a href="url">caption</a>                   Note 2
^[caption](url)     <a href="url" target="_blank">caption</a>   Note 3
<email>             <a href="mailto:email">email</a>
<email|caption>     <a href="mailto:email">caption</a>
______________________________________________________________________

Notes:

  1. Only HTTP and HTTPS raw URLs are auto-encoded.
  2. The [caption](url) syntax is Markdown compatible.
  3. Opens the link in a new browser tab.

Examples

Rimu Markup HTML Preview
1. http://example.com
2. <http://example.com>
3. <http://example.com|Example>
4. [Example](http://example.com)
5. ^[Example](http://example.com)
6. <example.html>
7. <example.html#basics|The basics>
8. <#api-options|API Options>
9. <file:///example/user-guide.pdf|User Guide>
10. <file:///downloads/>
11. <ftp://example.com/rfc959.txt|rfc959.txt>
12. <joe@example.com>
13. <joe@example.org|Joe Bloggs>

Images

Syntax:

Rimu                Rendered HTML
_______________________________________________________
<image:url|alt>     <img href="url" alt="alt">
<image:url>         <img href="url" alt="url">
![alt](url)         <img href="url" alt="alt">   Note 1
_______________________________________________________

Notes:

  1. The ![alt](url) syntax is Markdown compatible. To maintain Markdown compatibility it is always processed as an inline element i.e. a standalone image will be enclosed within an HTML paragraph element. Use a standalone HTML img element if you want an image to be rendered as a block element (without enclosing paragraph tags).

Examples

Rimu Markup HTML Preview
An image can be rendered as a block element:

<image:image-2.jpg|Red hot pokers>

Centered using the [rimuc](#rimuc-command) `align-center` CSS class:

.align-center
![Red hot pokers](image-2.jpg)

Or rendered ![Red hot pokers](image-2.jpg) inline.

An image can be rendered as a block element:

Red hot pokers

Centered using the rimuc align-center CSS class:

Red hot pokers

Or rendered Red hot pokers inline.

Character entities

HTML character entities can be included in Rimu source.

Examples

Rimu Markup HTML Preview
&copy; &reg; &alpha; &omega;

© ® α ω

Character entities can be escaped with a backslash character prefix.

Block Attributes

The Block Attributes Line Block element injects HTML attributes into the opening tag of the next block element. You can specify class names, an element ID, CSS styles and any other HTML attributes. The Block Attributes element can also include block-options which control the processing of Delimited Block elements.

Syntax:

.class-names #id "css-properties" [html-attributes] block-options

Examples

Rimu Markup
.error "color:red"
Lorum ipsum.

.#ref2 "color:green" [title="Reference two"]
Ac curabitur elementum.

{quote-style} = '."padding-left: 10px; border-left: 4px solid silver;"'

{quote-style}
""
Lorem ipsum dolor sit amet sapien. Nascetur et mattis maecenas morbi
porttitor. Vitae vestibulum voluptate. Quam elit id. In eu wisi.
Imperdiet pellentesque minim. Metus mauris tortor. Torquent leo vel.
""

.-macros
Macro {invocations} are not expanded when the `-macros` block option
is set.
HTML Preview

Lorum ipsum.

Ac curabitur elementum.

Lorem ipsum dolor sit amet sapien. Nascetur et mattis maecenas morbi porttitor. Vitae vestibulum voluptate. Quam elit id. In eu wisi. Imperdiet pellentesque minim. Metus mauris tortor. Torquent leo vel.

Macro {invocations} are not expanded when the -macros block option is set.

Delimited Block Definition

You can change Delimited Block behaviour with Delimited Block definitions.

Definition syntax:

|block-name| = '<open-tags>|<close-tags> block-options'

The following example generates Code blocks with a code-block class attribute:

|code| = '<pre><code class="code-block">|</code></pre>'

The following example disables Macro Invocation, Quote and Replacement processing in Paragraphs:

|paragraph| = '-macros -spans'

Macros

Macros are a simple yet powerful mechanism for creating shortcuts for repeatedly used markup. They can be used to parametrize documents, promote clarity and eliminate repetition (see Macro Examples).

Rimu provides elements for defining and invoking macros and includes features like macro parametrization, conditional processing and meta macros.

Macro definitions

A macro definition assigns one or more lines of Rimu markup to a macro name.

Definition syntax:

{macro-name} = 'macro-value'         Simple macro definition
{macro-name?} = 'macro-value'        Existential macro definition

Macro invocations

Invocation syntax:

{macro-name}                      Simple macro invocation
{macro-name|[param1|param2...]}   Parametrized macro invocation
{macro-name=pattern}              Inclusion macro invocation
{macro-name!pattern}              Exclusion macro invocation

Macro expansion

Macro examples

Reserved macro names

Macros with names starting with two hyphen characters are reserved for use by Rimu. Reserved macros are used by the Rimu library and by the rimuc command.

Predefined macros

The following macros are available for use in Rimu markup:

Macro name         Description
_______________________________________________________________
--                 Blank macro (empty string).
                   The Blank macro cannot be redefined.
--header-ids       Set to a non-blank value to generate h1, h2
                   and h3 header id attributes.
_______________________________________________________________

Header id generation

If the predefined macro --header-ids is non-blank Rimu generates unique HTML id attributes for h1, h2 and h3 section headers that do not have an explicit id.

HTML id attributes are generated from Rimu header text as follows:

  1. Replace characters that are not alphanumeric or underscores with dash characters.
  2. Replace multiple contiguous dashes with single dash.
  3. Trim leading and trailing dashes.
  4. Convert the text to lowercase.
  5. If no characters remain the id is set to x.
  6. If an existing element has a matching id then the id is successively postfixed with -2, -3… until a unique id is found.

For example a header with the title The End! will be assigned an id attribute value the-end

API Option element

API options can be set in the Rimu source using a Line Block element with the following syntax:

.option-name = 'option-value'

For example, the following API Option element ensures all subsequent raw HTML is not passed to the output:

.safeMode = '1'

CLI command

Rimu includes a command-line tool that converts Rimu markup to HTML. There are four functionally identical implementations: rimuc (JavaScript implementation), rimukt (Kotlin implementation), rimugo (Go implementation), rimuc (Dart implementation) and rimupy (Python implementation), rimuv (V implementation).

In the documentation the name rimuc refers to all four implementations (unless stated otherwise).

rimuc has options to generate stand-alone styled HTML documents, either from Rimu Markup or from Markdown or any text-to-HTML markup.

Run rimuc --help to view the rimuc manpage:

NAME
  rimuc - convert Rimu source to HTML

SYNOPSIS
  rimuc [OPTIONS...] [FILES...]

DESCRIPTION
  Reads Rimu source markup from stdin, converts them to HTML
  then writes the HTML to stdout. If FILES are specified
  the Rimu source is read from FILES. The contents of files
  with an .html extension are passed directly to the output.
  An input file named '-' is read from stdin.

  If a file named .rimurc exists in the user's home directory
  then its contents is processed (with --safe-mode 0).
  This behavior can be disabled with the --no-rimurc option.

  Inputs are processed in the following order: .rimurc file then
  --prepend-file option files then --prepend option source and
  finally FILES...

OPTIONS
  -h, --help
    Display help message.

  --html-replacement TEXT
    Embedded HTML is replaced by TEXT when --safe-mode is set to 2.
    Defaults to '<mark>replaced HTML</mark>'.

  --layout LAYOUT
    Generate a styled HTML document. rimuc includes the
    following built-in document layouts:

    'classic': Desktop-centric layout.
    'flex':    Flexbox mobile layout (experimental).
    'plain':   Unstyled HTML layout.
    'sequel':  Responsive cross-device layout.

    If only one source file is specified and the --output
    option is not specified then the output is written to a
    same-named file with an .html extension.
    This option enables --header-ids.

  -s, --styled
    Style output using default layout.
    Shortcut for '--layout sequel --header-ids --no-toc'

  -o, --output OUTFILE
    Write output to file OUTFILE instead of stdout.
    If OUTFILE is a hyphen '-' write to stdout.

  --pass
    Pass the stdin input verbatim to the output.

  -p, --prepend SOURCE
    Process the Rimu SOURCE text (immediately after --prepend-file
    option files). Rendered with --safe-mode 0. This option can be
    specified multiple times.

  --prepend-file PREPEND_FILE
    Process the PREPEND_FILE contents (immediately after .rimurc file).
    Rendered with --safe-mode 0. This option can be specified
    multiple times.

  --no-rimurc
    Do not process .rimurc from the user's home directory.

  --safe-mode NUMBER
    Non-zero safe modes ignore: Definition elements; API option elements;
    HTML attributes in Block Attributes elements.
    Also specifies how to process HTML elements:

    --safe-mode 0 renders HTML (default).
    --safe-mode 1 ignores HTML.
    --safe-mode 2 replaces HTML with --html-replacement option value.
    --safe-mode 3 renders HTML as text.

    Add 4 to --safe-mode to ignore Block Attribute elements.
    Add 8 to --safe-mode to allow Macro Definitions.

  --theme THEME, --lang LANG, --title TITLE, --highlightjs, --mathjax,
  --no-toc, --custom-toc, --section-numbers, --header-ids, --header-links
    Shortcuts for the following prepended macro definitions:

    --prepend "{--custom-toc}='true'"
    --prepend "{--header-ids}='true'"
    --prepend "{--header-links}='true'"
    --prepend "{--highlightjs}='true'"
    --prepend "{--lang}='LANG'"
    --prepend "{--mathjax}='true'"
    --prepend "{--no-toc}='true'"
    --prepend "{--section-numbers}='true'"
    --prepend "{--theme}='THEME'"
    --prepend "{--title}='TITLE'"

  --version
    Print version number.

LAYOUT OPTIONS
  The following options are available when the --layout option
  is used:

  Option             Description
  _______________________________________________________________
  --custom-toc       Set to a non-blank value if a custom table
                     of contents is used.
  --header-links     Set to a non-blank value to generate h2 and
                     h3 header header links.
  --highlightjs      Set to non-blank value to enable syntax
                     highlighting with Highlight.js.
  --lang             HTML document language attribute value.
  --mathjax          Set to a non-blank value to enable MathJax.
  --no-toc           Set to a non-blank value to suppress table
                     of contents generation.
  --section-numbers  Apply h2 and h3 section numbering.
  --theme            Styling theme. Theme names:
                     'legend', 'graystone', 'vintage'.
  --title            HTML document title.
  _______________________________________________________________
  These options are translated by rimuc to corresponding layout
  macro definitions using the --prepend option.

LAYOUT CLASSES
  The following CSS classes can be used to style Rimu block
  elements in conjunction with the --layout option:

  CSS class        Description
  _______________________________________________________________
  align-center     Align element content center.
  align-left       Align element content left.
  align-right      Align element content right.
  bordered         Add borders to table element.
  cite             Quote and verse attribution.
  dl-horizontal    Format labeled lists horizontally.
  dl-numbered      Number labeled list items.
  dl-counter       Prepend dl item counter to element content.
  ol-counter       Prepend ol item counter to element content.
  ul-counter       Prepend ul item counter to element content.
  no-auto-toc      Exclude heading from table of contents.
  no-page-break    Avoid page break inside the element.
  no-print         Do not print element.
  page-break       Force a page break before the element.
  preserve-breaks  Honor line breaks in element content.
  sidebar          Paragraph and division block style.
  verse            Paragraph and division block style.
  important        Paragraph and division block style.
  note             Paragraph and division block style.
  tip              Paragraph and division block style.
  warning          Paragraph and division block style.
  _______________________________________________________________

PREDEFINED MACROS
  Macro name         Description
  _______________________________________________________________
  --                 Blank macro (empty string).
                     The Blank macro cannot be redefined.
  --header-ids       Set to a non-blank value to generate h1, h2
                     and h3 header id attributes.
  _______________________________________________________________

Example usage

  1. Use rimuc as a filter:
    echo 'Hello *Rimu*!' | rimuc
  2. Generate a styled HTML document with a table of contents and code syntax highlighting: options:
    rimuc --layout sequel --highlightjs reference.rmu
  3. Prefix a custom macro definition:
    rimuc --prepend "{annotations}='yes'" showcase.rmu
  4. Compile multiple source files to single output file:
    rimuc -o book.html frontmatter.rmu chapter*.rmu backmatter.rmu

--layout option

The --layout option is used to generate styled HTML documents. It does this by enveloping the compiled output in a layout specific HTML header and footer.

rimuc comes with built-in layouts.

All features enabled by the --layout option are implemented with Rimu markup in the header and footer files. The --layout option concatenates the input with built-in header and footer files. For example, the following two commands are functionally identical:

rimuc --layout sequel sites.rmu
rimuc --output sites.html sequel-header.rmu sites.rmu sequel-footer.rmu

Built-in Layouts

You can choose from the following built-in layouts:

sequel
Responsive cross-device layout designed to render nicely on desktops, laptops, tablets and phones. This website uses the sequel layout.
classic
Desktop-centric layout.
  • Not suitable for small screens (the TOC sidebar is hidden on small screens).
  • Set the --dropdown-toc macro to a non-blank value to place the table of contents in a popup.
flex
Flexbox layout. Works nicely with small screens.
  • The menu bar automatically positions along the top when the device orientation is portrait.
  • Set the --top-bar macro to a non-blank value to place the navigation bar along the top of the document.
plain
Unstyled HTML layout.
  • Does not support any layout classes or layout options.
v8
Deprecated Rimu version 8 layout.

Examples of the built-in layouts can be viewed in the Rimu Gallery.

The built-in layouts:

A number of built-in layout styles are set by header file macro values that can be overridden. For example:

rimuc --layout sequel --prepend "{--primary-color}='#0cc'" sites.rmu

You can view full list of layout macros in the corresponding built-in layout header file.

Themes

A theme is a layout styling variation. Named themes are specified using the --theme option. The built-in layouts implement legend, graystone and vintage themes.

Examples of the built-in layout themes can be viewed in the Rimu Gallery.

The --theme option value sets the --theme macro which the layout header then uses to conditionally include HTML style elements.

Table of contents generation

Built-in layouts automatically include a table of contents in the generated HTML document.

Custom table of contents

The --custom-toc option is used in conjunction with built-in layouts. The --custom-toc option inhibits the generation of an HTML TOC container and it is up to the user to include a custom HTML TOC container in the Rimu markup. This allows you to customise the location, style and content of the TOC:

If --custom-toc is not specified the following TOC container is inserted in the output document:

<div id="toc">
  <div id="auto-toc"></div>
</div>

API

Rimu has just one API for translating Rimu markup to HTML:

render(source [, options])

The source argument is a string containing Rimu markup. The return value is a string containing the resultant HTML. The optional options argument controls rendering behaviour.

The render() API is stateful: macros and custom element definitions are retained across API calls along with API options. Use the reset option to restore the default state.

Example usage

Node.js

var rimu = require('rimu');
var html= rimu.render('Hello *Rimu*!');

See Rimu README.

Deno

import * as rimu from "https://raw.github.com/srackham/rimu/master/mod.ts";

console.log(rimu.render("Hello *Rimu*!"));

See Rimu README.

Kotlin

import org.rimumarkup.RenderOptions
import org.rimumarkup.render

fun main(args: Array<String>) {
    println(render("Hello *Rimu*!", RenderOptions(reset = true))
}

See the Rimu Kotlin README.

Go

package main

import (
    "fmt"

    "github.com/srackham/go-rimu/v11/rimu"
)

func main() {
    fmt.Println(rimu.Render("*Hello Rimu*!", rimu.RenderOptions{Reset: true}))
}

See the Rimu Go README.

Dart

import 'package:rimu/rimu.dart';

main(List<String> arguments) {
  print(render('Hello *Rimu*!', RenderOptions(reset: true)));
}

See the Rimu Dart README.

Python

import rimu

print(rimu.render('*Hello World*!', rimu.RenderOptions(reset=True)))

See the Rimu Python README.

V

module main

import srackham.rimu

fn main() {
	println(rimu.render('*Hello Rimu*!', rimu.RenderOptions{}))
}

See the Rimu V README.

API options

The API options argument is an object with zero or more of the following properties:

safeMode

This option has a number value that controls how Rimu renders embedded HTML and how Rimu definition and option elements will be processed:

0 => Render HTML (default behavior).
1 => Ignore HTML.
2 => Replace HTML with the 'htmlReplacement' option string.
3 => Render HTML as text.

Add 4 to safeMode to ignore Block Attribute elements.
Add 8 to safeMode to allow Macro Definitions.
  • If safeMode is zero all Rimu elements will be processed.
  • If safeMode is non-zero the following Rimu elements are ignored:
    • Rimu definition elements (Delimited Block, Macro, Quote and Replacement definitions).
    • API Option elements.
    • HTML attributes in Block Attribute elements.
  • Add 4 to safeMode to ignore Block Attribute elements completely, this ensures HTML element IDs cannot be created and that CSS classes or properties cannot be used explicitly.
  • Add 8 to safeMode to allow Macro Definitions. Allowing Macro Definitions is not intrinsically unsafe because their safety or otherwise is solely determined by the safety of their constituent elements.
  • For example, a safeMode value of 13 (1+4+8) skips HTML elements, allows macro definitions but skips all other Rimu definition elements along with API option elements.
  • Once a non-zero safeMode has been set then it can only be reset by a render() API call with a safeMode:0 or a reset:true option.
htmlReplacement
A string that replaces embedded HTML when safeMode is set to 2. Defaults to <mark>replaced HTML</mark>.
callback

callback is a function that handles diagnostic events emitted by the render() API. The callback function is passed a single message argument. The message argument is an object with a type property ('error', 'warning' or 'info') and a text property (a string containing the diagnostic message). Callback examples:

// JavaScript and TypeScript.
function callback(message) {
    console.log(message.type + ': ' + message.text);
}

var html = Rimu.render('Hello *Rimu*!', {callback: callback});
# Python.
def callback(message):
    print(f'{message.type}: {message.text}')

html = rimu.render('Hello *Rimu*!', rimu.RenderOptions(callback=callback))
// Dart.
callback(CallbackMessage message) {
  print('${message.type}: ${message.text}');
}

var html = render('Hello *Rimu*!', RenderOptions(callback: callback));
// Kotlin.
fun callback(message: CallbackMessage) {
    println("${message.type}: ${message.text}")
}

var html = render("Hello *Rimu*!", RenderOptions(callback = callback))
// Go.
opts := rimu.RenderOptions{}
opts.Callback = func(message rimu.CallbackMessage) {
    fmt.Println(message.Kind + ": " + message.Text)
}
html := rimu.Render("Hello *Rimu*!", opts)
// V.
mut opts := rimu.RenderOptions{}
opts.callback = fn (message rimu.CallbackMessage) {
    println(message.kind + ': ' + message.text)
}
html := rimu.render('Hello *Rimu*!', opts)
reset
This boolean option causes the render API to be set to its default state (default option values; default Quotes, Replacements and Delimited Block definitions; predefined macro definitions only; no callback). The reset option is processed before other options.

Vim syntax file

The Rimu distribution includes a syntax highlighter for the Vim editor. Copy rimu.vim to your $HOME/.vim/syntax directory and then use the Vim :set syn=rimu command or put this line in your $HOME/.vimrc file to enable Rimu syntax highlighting:

autocmd BufRead,BufNewFile *.rmu setlocal filetype=rimu

The syntax file also sets Vim text formatting options, if they're not to your taste delete them from the end of the file.

Regular Expressions

Regular expressions can be embedded in replacements definitions and inclusion/exclusion macro invocations.

The language specific regular expression engine is used. This means that platform differences between regular expression syntax is a potential source of cross-platform incompatibility. To avoid cross-platform incompatibility use regular expression syntax that is common to all platforms:

Guidelines:

Rimu implementations

Here is a list of Rimu implementations:

Time taken to compile 3,719 lines of Rimu Markup:

TypeScript   455ms
Deno         257ms
Go           289ms
Kotlin       1032ms
Dart         114ms
Python       262ms
V            79ms

Version numbering

Other