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):

• Markup generation can be customized and extended.
• Rimu includes a simple, flexible macro language.
• A subset of Rimu syntax is Markdown compatible.
• The generated HTML is compatible with all modern browsers.
• Rimu implementations are available for various languages and runtime environments.

Resources

Installation

See Rimu README for installation instructions.

Learning

• Experiment with Rimu in the Rimu Playground.
• Click the Edit icon ✎ in the examples below to enable live editing of the Rimu source; click the Preview icon ⬄ to toogle output between HTML and Preview.
• Read Rimu Tips.

Example applications

See the API documentation.

• Rimu includes the rimuc command-line tool and the Rimu Playground — examples of using Rimu in Node.js and in the browser respectively.
• A toy Chrome browser extension for rendering Rimu Markup files directly in the browser.

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.

• A Multi-line comment starts with a line containing only /* and ends with a line containing only */.
• A Single-line comment is a line of text starting with //.
• Comments are not included in the HTML output.
• Comments are block elements and cannot be used inline, for example mid-paragraph (use Inline comments instead).
• Comment delimiters must start at the left margin.
• Comments can be escaped by prefixing the opening delimiter with a backslash character.
• Use an HTML comment if you want the comment to be included in the HTML output.

Examples:

Examples

/*
  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. -->

Inline comments

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

• Exclude individual lines using an Exclusion macro invocation.
• Place comments anywhere in an inline context using a Parametrized macro invocation. This works because the Blank macro has no formal parameters).

Examples

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.

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.

• Header prefixes and postfixes must be separated from the title text by whitespace.
• Inline elements are allowed in the header title.

Examples

# 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.

• The number of characters in the closing delimiter must exactly match the number in the he opening delimiter — this allows fenced blocks of the same type to be nested.
• The behaviour of individual Fenced Blocks can be customized with a preceding Block Attributes element.
• CSS class names appended to the opening delimiter line of Code, Division and Quote fenced blocks will be injected into the block's opening HTML tag (this is an alternative to using a Block Attributes element).
• Fenced Blocks can be escaped by prefixing the opening delimiter with a backslash character.
• You can customize the generated HTML with Delimited Block definitions.

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

``
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

""
Nunc mauris tempor.
Scelerisque feugiat massa alias.

.cite
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.

• The Division Block delimiter character is a period.
• If the Division Block has HTML attributes then the output is enclosed in an HTML div element. If the Division Block has no HTML attributes then the HTML div tags are omitted.

Examples

."font-style:italic"
..
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.

• Macro invocations in HTML elements are expanded.
• HTML tags can be escaped with a backslash character prefix.
• HTML elements can be excluded from the output using the API safeMode option.

Inline HTML elements

• Any well formed HTML tag is allowed in an inline context.

Examples

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

Block HTML elements

• The opening tag of an HTML block element must start at the left margin.
• An HTML block element is terminated with a blank line.

Examples

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>

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

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

  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

> 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
___________________________________________

• Bullet and Numbered list items begin with the list ID. The list ID must be separated by one or more spaces from the list item text.

  Bullet and numbered lists

  ✎ Rimu Markup	HTML ⬄ Preview
  - First item. . Nested numbered item. - Second item of first list.	First item. Nested numbered item. Second item of first list.

• Labeled list items begin with the term text followed immediately by the list ID, then one or more spaces or a line break, then the definition text.

  Labeled list

  ✎ Rimu Markup	HTML ⬄ Preview
  First term:: Definition one. Second term:: Definition for second term.	First term Definition one. Second term Definition for second term.

• A list item consists of a first line followed by zero or more additional lines, followed by an optional attached element, followed by an optional child list.

  List item

  ✎ Rimu Markup	HTML ⬄ Preview
  - First line. Second line. "" Optional attached Quote block. "" * Optional child list.	First line. Second line. Optional attached Quote block. Optional child list.

• List items and attached elements can be preceded by Block Attribute elements. This facilitates styling and linking within lists.
• List items can be indented but this has no semantic significance (indents are fussy to write and are prone to editor tab expansion and copy-and-paste corruption).
• Numbered list IDs can be prefixed with numbers but the number has no semantic significance.
• A child list is created when a list item is followed by an item with a list ID that does not belong to the current list or any of its ancestors.
• List items can be escaped with a backslash at the beginning of the line.
• Indented paragraphs, Quote paragraphs, Fenced blocks, HTML blocks and Multi-line comments can be attached to list items:
  • If an Indented paragraph or Quote paragraph is separated from a preceding list item by a single blank line then it is attached to the list item.
  • If a Fenced block, HTML block or Multi-line comment immediately follows a list item without any intervening blank lines then it is attached to the list item.
• Lists are terminated:
  • When the element following the list item is not a list item.
  • When the element following the list item is an ancestor list item.
  • By two or more blank lines.
• There are no explicit numbering or bullet styles — this is best left to CSS which can apply a consistent set of list styles.

Examples

- 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.

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
___________________________________________________________

• Quoted text must begin and end with non-whitespace characters.
• Quotes and inline elements can be nested within a quote with the exception of the Code quote.
• Single underscore quote characters within words are ignored if they are flanked on both sides by alphanumeric characters (use single asterisk quotes to emphasize text within words).
• Quotes can be escaped by prefixing the opening quote with with a backslash character. If the text contains multiple quotes of the same type then, to resolve ambiguity, additional quotes may have to be escaped.
• The Code quote renders quoted text verbatim with one exception: Macro Invocations are expanded.

Examples

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>'

• quote-delimiter can be one or two characters.
• open-tags and close-tags are the HTML tags that envelope the generated HTML.
• Use a two-bar || separator to render the quoted text verbatim (like the built-in code quote).
• A Quote definition must start at the left margin and must not extend beyond the end of the line.
• Quote definitions are not processed if the SafeMode API option is non-zero.
• Macro invocations are expanded inside the open-tags and 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'

• The regular expression pattern syntax and available flags are platform dependent (see Regular Expressions).
• $1, $2… and $$1, $$2… in replacement are replaced by the corresponding regular expression match groups. $0 and $$0 are replaced by the entire match.
  • Special characters are escaped in $1, $2…
  • Quotes are expanded and special characters escaped in $$0, $$1, $$2…
• Replacements are only expanded in inline contexts.
• Replacements are not expanded inside Code quotes, Code blocks or Indented paragraphs.
• If the first matched character is a backslash then replacement will be escaped i.e. starting the regular expression with \\? will ensure it can be escaped.
• A replacement definition must start at the left margin and must not extend beyond the end of the line.
• The replacement text can invoke previously defined macros.
• Replacement definitions are not processed if the SafeMode API option is non-zero.
• If the replacement definition pattern matches that of an existing definition it will replace the existing definition, otherwise it is appended to the end of the replacement definitions list (where it assumes the lowest precedence).

Example replacement definitions:

/\.{3}/ = '…'
/\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

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  Or rendered  inline.	An image can be rendered as a block element: Centered using the rimuc align-center CSS class: Or rendered inline.

Character entities

HTML character entities can be included in Rimu source.

Examples

© ® α ω

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

• block-options is used to control the processing of the succeeding Delimited Block element contents.
• Macro invocations in Block Attributes are expanded.
• The leading period character must start at the left margin and the attributes must not extend beyond the end of the line.
• All items are optional but their order is not.
• Successive Block Attributes elements accumulate until they are consumed by the first succeeding Delimited Block element.
• class-names is one or more HTML class attribute names (separated by spaces).
• id is a unique HTML id attribute value.
• css-properties is one or more CSS property name/value pairs: it injects a style="css-properties" attribute into the target opening tag.
• html-attributes is one or more HTML attribute name/value pairs: they are injected into the target opening tag.
• The [html-attributes] section is ignored if the safeMode API option is not zero.
• The -specials block option is ignored if the safeMode API option is not zero.
• The entire Block Attributes element is ignored if bit 2 of the safeMode API option is set.

Examples

.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.

Delimited Block Definition

You can change Delimited Block behaviour with Delimited Block definitions.

Definition syntax:

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

• block-name is is one of the following Delimited Block names:

  code,
  comment,
  division,
  html,
  indented,
  quote,
  quote-paragraph,
  paragraph.

• open-tags and close-tags define the HTML tags that envelope the output block. <open-tags>|<close-tags> is optional.
• block-options is used to control the processing of Delimited block elements. block-options is optional and consists of one or more of the following space separated options:

  +macros (enable macro expansion),
  -macros (disable macro expansion),
  +spans (enable Quote and Replacement element processing),
  -spans (disable Quote and Replacement element processing),
  +specials (enable special character entities),
  -specials (disable special character entities),
  +container (the block is a container for Rimu block elements),
  -container (turn off the container option),
  +skip (skip the block),
  -skip (turn off the skip option).

• A Delimited Block definition must start at the left margin and must not extend beyond the end of the line.
• Delimited Block definitions are not processed if the safeMode API option is non-zero.
• Macro invocations in the definition are expanded.
• macros, spans and specials block options are not applied to Division or Quote blocks or Lists.

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

• A macro definition must start at the left margin.
• A macro name consists of one or more alphanumeric, underscore or dash characters.
• Simple macro definitions are processed unconditionally; Existential macro definitions are only processed if the macro has not been defined.
• Macro values are enclosed by single-quote characters and can extend over multiple lines.
• Single-quotes at the end of a line can be escaped by appending a backslash character to the end of the line.
• Macro values can contain macro invocations:
  • The macro invocations are expanded when the definition is processed (not when it is invoked).
  • Escaped macro invocations will be unescaped when the definition is processed, consequently they need to double-escaped if you want them to be escaped when the macro definition is invoked.
• Macro expansion can be disabled in multi-line macro definitions using a Block Attributes -macros option.
• $1, $2… and $$1, $$2… are parameter names, they are replaced with parameter values in Parametrized macro invocations.

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

• A Simple macro invocation is replaced by the macro value.
• $1, $2… and $$1, $$2… parameter names are replaced with the corresponding parameter values (param1, param2…) in Parametrized macro invocations.
  • If a macro parameter value is not specified then the corresponding parameter name is replaced by a blank string.
  • Parameter names in macro definitions can be escaped with a backslash character prefix e.g. \$1.
  • Macro parameter values can contain inline Rimu elements; inline parameter values can span multiple lines.
  • Quotes and Replacements are expanded and special characters escaped inside double-dollar parameters ($$1, $$2…). Double-dollar parameters are normally only necessary inside Block HTML elements.
  • Default parameter values can be specified by appending :default-value$ to the parameter name e.g. $2:Ford$ will assign Ford to the $2 parameter if it is blank or not specified in the macro invocation.
  • Dollar characters can be included in default parameter values by escaping them with a backslash character e.g. $2:Ten dollars (\$10)$.
  • The default value can span multiple lines.
  • The default value can be escaped by prefixing the colon with a backslash character e.g. $2\:One dollar$.
  • The {macro-name|} invocation syntax uses only default parameter values. This is not the same as the {macro-name} simple macro invocation which performs no parameter substitution.
• The {macro-name=pattern} Inclusion invocation is replaced by a blank string if the macro value entirely matches the pattern (where pattern is a regular expression. If the macro value does not match the pattern the containing line is skipped.
• The {macro-name!pattern} Exclusion invocation syntax is the inverse of the {macro-name=pattern} syntax i.e. the macro invocation is replaced by a blank string if the macro value does not match the pattern, if it does match the containing line is skipped.
• The regular expression pattern syntax in inclusion and exclusion invocations is platform dependent (see Regular Expressions).
• By default macro invocations are expanded everywhere except inside Code blocks and Indented paragraphs. Use the Block Attributes +macros and -macros options to enable and disable expansion inside Delimited blocks.
• Undefined macro invocations are not processed and are passed verbatim to the output.
• Macro invocations can be escaped in block elements that have macro expansion enable using a leading backslash character prefix. Escaped macro invocations are rendered verbatim minus the backslash. Escaping is unnecessary in blocks that do not perform macro expansion (Code blocks and Indented paragraphs).
• Simple macro invocations are allowed in macro parameters and patterns (non-Simple invocations are not).
• Macro invocations can contain } characters but they must be escaped with a backslash character (otherwise they will be mistaken for the macro's closing brace).
• Macro definitions are not processed if the safeMode API option is non-zero and bit 3 of safeMode API option is not set.

Macro expansion

• Macro invocations are expanded before other elements are processed.
• Macro invocations are processed as Inline elements with one exception: If a block element begins with a Macro Invocation that is wholly contained on the first line then macro invocations in the first line are expanded prior to all other processing, this behaviour enables the following use-cases:
  1. Conditional inclusion of Line Block elements by prefixing them with Inclusion or Exclusion macros.
  2. Macros can be used to generate Rimu Block elements. For example, take a look at the {sidebar} macro in these examples, it generates a Header block element followed by a Block Attributes block element.

Macro examples

• Using Rimu Macros.
• Use macros to create tables.
• Meta macros.
• Macro tips.
• General purpose macro processor.

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.
_______________________________________________________________

• See Header id generation.

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'

• option-name is safeMode, htmlReplacement or reset.
• The option-value is a valid option value.
• Macro invocations in option-value are expanded.
• An API Option element must start at the left margin and must not extend beyond the end of the line.
• The option is applied to Rimu markup that follows the option element.
• API Option elements are not processed if the safeMode is non-zero.

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:

• Create a stand-alone HTML5 document.
• Optionally generate a table of contents.
• Include CSS styles for verses, sidebars, text alignment, page break control and section numbering (see rimuc --help command and examples in Rimu Tips).
• Generate unique header id attributes.
• If the --highlightjs macro is non-blank Highlightjs is included.
• If the --mathjax macro is non-blank MathJax is included.
• Support named themes.

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.

• The table of contents is synthesised from top level h1, h2 and h3 HTML header elements.
• You can suppress the table of contents generation using the --no-toc option.
• The --custom-toc option allows the user to include a custom TOC.
• Use the no-auto-toc CSS class attribute to exclude a section header from the table of contents, for example:

  .no-auto-toc
  ## This header does not appear in the TOC

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:

• The TOC container must be an HTML element with id="toc".
• If the document contains an element with id="auto-toc" then it will be loaded with the auto-generated TOC entries, if this element is omitted TOC entries will be skipped.

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:

• JavaScript, TypeScript and Dart use ECMA-262 regular expressions.
• Java and Kotlin regular expressions.
• Go regular expressions.
• Python regular expressions.

Guidelines:

• No named groups.
• No look-ahead or look-behind groups.
• No backreferences (\1, \2, ...).
• Use only the i flag in replacement definitions.
• No embedded flags.

Rimu implementations

Here is a list of Rimu implementations:

• The canonical TypeScript version for Deno, Node.js and browser runtime environments.
• A Kotlin port for the JVM platform.
• A Go language port.
• A Dart port.
• A Python port.
• A V language port.

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

• All implementations use semantic version numbers.
• Implementations with the same major and minor version numbers are functionally identical.
• The patch version numbers are port specific.
• Changes to one implementation will normally be propagated to the next release of other Rimu implementations but there is no implied equivalence of the patch version numbers across the various ports.

Other

• By convention Rimu markup text files have a .rmu file name extension but if your markup is confined to Rimu's Markdown compatible subset then use .md to signal your intent.