Rimu Tips

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.

HTML is valid Rimu

You are free to mix any valid HTML into a Rimu document — no special syntax is required (in this sense Rimu can be thought of as an HTML superset). Just remember that included HTML is only processed if safeMode is zero.

Converting Rimu to PDF

First convert Rimu markup to HTML using the rimuc tool and then convert the HTML to PDF. Here are a few options for converting HTML to PDF:

  1. Use Libre Office Writer or Microsoft Word to open the HTML document then export it to a PDF file.
  2. Use a command-line application such as wkhtmltopdf to convert HTML to PDF.
  3. Google's Chrome web browser has an option to print HTML to a PDF file.

Using Rimu Macros

Macros provide a simple, consistent mechanism for extending the Rimu markup vocabulary.

Examples

Rimu Markup
// Define some macros.
{info} = '<span style="color:white;
                       background-color:#006699;
                       padding:2px 4px;
                       border-radius:3px;
                       font-weight:bold;">$1</span>'
{heads-up} = '{info|Heads up!}'
{note} = '{info|Note} <mark>$1</mark>'
{rimu-playground} = '[Rimu Playground](https://srackham.github.io/rimu/rimuplayground.html)'
{sidebar} = '#### $1
."padding-left: 10px; border-left: 4px solid silver; margin-bottom: 1em;"'

// Use the macros.
{sidebar|Fun with Macros}
..
{heads-up} See the {rimu-playground} for documentation and hands-on
experimentation.

{note|This document is not yet finished.}
..
HTML Preview

Fun with Macros

Heads up! See the Rimu Playground for documentation and hands-on experimentation.

Note This document is not yet finished.

See also:

To link to another place within a document:

  1. Create an ID for the element you want to link to using the Rimu Block Attribute element.
  2. Link to it using a fragment identifier URL.

Examples

Rimu Markup HTML Preview

Source code syntax highlighting

The rimuc command can highlight code in Rimu Code Blocks and Indented Paragraphs using the Highlight.js syntax highlighter. To include Highlight.js support use the rimuc command --highlightjs option with the --layout option.

Set the language you want to highlight by injecting the language CSS class name into the code block. Here are two examples, the first uses GitHub Flavored Markdown style syntax, the second uses Rimu's Block Attributes element:

Examples

Rimu Markup HTML Preview
Some JavaScript code:

``` javascript
if (message) {
  console.error('Error: ' + message);
}
```

Some Python code:

.python
``
x = 1
if x == 1:
    print "x is 1."
``

Some JavaScript code:

if (message) {
  console.error('Error: ' + message);
}

Some Python code:

x = 1
if x == 1:
    print "x is 1."

Rimu compatible Markdown

The following subset of Rimu elements is compatible with Markdown:

Headers
Headers using # character header prefixes.
Code blocks
  • Indented paragraphs indented with at least four spaces render like Markdown code blocks.
  • Rimu code blocks fenced with three or more backticks behave like GitHub Flavored Markdown Fenced code blocks.
Multi-line blockquotes
GitLab Flavored Markdown Multi-line blockquotes fenced by >>> are rendered as Quote blocks.
Quote paragraphs
Paragraphs starting with a > character are rendered like Markdown Blockquotes.
Text formatting
  • _emphasis_, *emphasis*, __bold__, **bold**, `code` , ``code`` quoting.
  • ~~strikethrough~~ quotes (GitHub Flavored Markdown behaviour).
  • Underscores within words rendered verbatim and are not treated as underscore emphasis quotes (GitHub Flavored Markdown behaviour).
Lists
  • Bullet lists with -, + and * list item prefixes.
  • Numbered lists with explicit numbering.
URLs and Email addresses
[caption](url), <url> and <email> syntaxes plus GitHub Flavored Markdown URL autolinking.
Images
![alt](url) syntax.
Regular paragraphs
Rimu regular paragraphs must be terminated by a blank line. This is not always enforced by Markdown but is considered good style nonetheless.

The Rimu README uses this subset for compatibility with GitHub and npmjs.org README formats.

Processing HTML and Markdown with the rimuc command

In addition to processing Rimu markup and Rimu compatible Markdown, the rimuc command can style raw HTML to produce nicely styled HTML documents (like this one) using rimuc's built-in themes and document layouts.

rimuc passes files with an .html extension directly to the output, similarly the standard input is passed directly to the output if the --pass option is specified.

When it comes to processing Markdown with rimuc there are two options:

  1. If your Markdown file is compatible with the Rimu Markdown subset then you don't have to do anything, rimuc will process it just like any other Rimu source file.
  2. Otherwise convert the Markdown (or any other text-to-HTML markup) to HTML before processing it with rimuc. For example:
    cat README.md | marked | rimuc --styled --pass --output README.html
    
    marked README.md > README.html && rimuc --styled README.html

    The first example works because the rimuc --pass option passes the standard input verbatim to the output. The second example works because rimuc passes the contents of input files with a .html extension directly to the output. Both examples use the marked CLI application to convert Markdown to HTML.

Converting Rimu to Markdown

Arbitrary Rimu source can be converted to pure Markdown by first converting it to HTML and then converting the HTML to Markdown.

Using a CLI converter

Use a CLI HTML to Markdown converter such as html2md e.g.

rimuc mydoc.rmu | html2md > mydoc.md

Using an online converter

Use an online HTML to Markdown converter such as turndown:

  1. First convert Rimu to raw HTML using the rimuc command e.g.
    rimuc mydoc.rmu > mydoc.html
  2. Then then copy and paste the contents of the HTML file into turndown.

Escaping Rimu syntax

If you have text that you don't want interpreted as a Rimu element then you can render it literally (escape it) by prefixing the element with a backslash character.

Examples

Rimu Markup HTML Preview
\_escaped quote_

**escaped closing\** quote**

``backticks in `code quote```

\# Escaped header.

_escaped quote_

escaped closing** quote

backticks in `code quote`

# Escaped header.

The text inside code quotes is always rendered verbatim — to include backtick characters in code quotes use double-backtick quotes.

Passing macro values into Rimu documents

You can do this by prepending text containing macro definitions to Rimu source before rendering the source. The rimuc command has a --prepend option that can be used to do this.

Alternatively you could also put macro definitions in a separate file and specify it as the first Rimu source file in the rimuc command.

The following example sets the rimuc --title macro value, this sets the HTML title in the kotlin-notes.html output document:

rimuc --layout sequel --prepend "{--title}='Kotlin Notes'" kotlin-notes.rmu

rimuc has a --title shortcut command-line option for this common use-case:

rimuc --layout sequel --title "Kotlin Notes" kotlin-notes.rmu

Other macro shortcut options can be found in the rimuc documentation.

Source file inclusion

To avoid duplication it is useful to be able to include common blocks of text in multiple source files. Direct file inclusion is not possible because Rimu markup has no mechanisms for file-system access (a design feature to ensure Rimu source is operating system independent). An idomatic solution is to use Rimu macros. For example, the following file, containing shared Rimu macro definitions can be compiled into each document:

// Block macro definition containing multi-line text.
{common-text} = 'Lectus cursus porttitor sed lectus nisi est ac vel scelerisque natoque
scelerisque lorem porttitor est scelerisque natoque vel.

Hac scelerisque parturient a sed natoque pulvinar tincidunt integer
parturient ac porttitor pulvinar.
'

Include the common source when you run the rimuc command e.g.

rimuc common.rmu mydocument.rmu

The Rimu markup looks correct but the generated HTML is wrong

Using an editor with Rimu syntax highlighting support (see previous topic) makes it much easier to spot syntax errors. Rimu includes a Vim editor syntax highlighter, see the Vim syntax file section in the Rimu Reference for details.

Extending the Vim syntax highlighter

If you've added custom replacements and quotes you can highlight them in Vim by creating a custom ~/.vim/after/syntax/rimu.vim syntax file (Vim loads files from the after directory after loading normal syntax files). The distributed example ~/.vim/after/syntax/rimu.vim syntax file highlights custom syntax definitions from the example .rimurc file.

Entering non-keyboard characters

Characters that are unavailable on your keyboard can be entered as HTML character entities e.g. enter &micro; to display µ. The example .rimurc file includes replacements for common use-cases such as em dash, ellipsis and quotation characters.

Use Replacement and Quote definitions sparingly

Adding new Replacement and Quote definitions changes the Rimu syntax which can produce unexpected results. It can also make your Rimu source non-portable and less readable.

Example .rimurc file

The Rimu distribution includes an example .rimurc file containing useful macros, quotes and replacement definitions.

It is important to note that these niceties have been defined in Rimu Markup — Rimu has been extended using Rimu. No plugins or special configuration file syntax were necessary.

Examples

Rimu Markup HTML Preview
Turn <- left then right ->

Copyright (C) 2015 -- trademarked(TM).

"Left and right double-quotes". `Non-breaking code quotes`.

~~Strikethrough~~ and __underlining__.

The 3{sup|rd} H{sub|2}O molecule...

**************************

Markdown horizontal rules.

**************************

TODO 10 examples +-2

Turn ← left then right →

Copyright © 2015 — trademarked™.

“Left and right double-quotes”. Non-breaking code quotes.

Strikethrough and underlining.

The 3rd H2O molecule…


Markdown horizontal rules.


TODO 10 examples ±2

Including CSS in Rimu documents

You can include custom CSS styles in the body of a Rimu document using an HTML style element. Here are three use-cases:

  1. Change existing styling. The following example changes the color of all headers to red:
    <style>
      h1, h2, h3, h4, h5, h6 {
        color: red;
      }
    </style>
  2. Add a new block style. The following example puts a green border around blocks with the green-border class:
    <style>
      .green-border {
        border: 5px solid green;
      }
    </style>
    
    .green-border
    Green is the color of envy.
  3. Create new themes and tweak existing themes.

The style element must not contain any blank lines because Rimu HTML block elements are terminated with a blank line

Themes

A theme is a layout styling variation. The --layouts option supports a number of built-in themes. You can create your own themes by including custom CSS style elements.

Here is an example theme named redheads:

{--theme!.*\bredheads\b.*}.+skip
<style>
  h1, h2, h3, h4, h5, h6 {
    color: red;
  }
</style>

The HTML style element will be included in the output when the --theme macro value includes the word redheads, for example:

rimuc --layout sequel --theme redheads document.rmu

You can combine themes by specifying more than one theme, for example:

rimuc --layout sequel --theme "graystone redheads" document.rmu

If you specify multiple themes their CSS styles will cascade in the order they are processed in the Rimu source documents.

Admonition, sidebar and verse styles

The rimuc command --layout option includes CSS classes for styling paragraphs and Division blocks whose content sits outside the main narrative flow.

The CSS class names are injected using the Block Attibutes element or by appending them to the opening block delimiter.

important, note, tip and warning styles

The important, note, tip and warning styles render messages and admonitions. The optional notitle style class can be used to hide the admonition's title.

Examples

Rimu Markup HTML Preview
.note
Admonition styled paragraph.

.tip notitle
Admonition styled paragraph without a title.

..warning
Admonition styled Division Block.

Neque a massa.
Nunc mauris tempor.
Pede mauris sed.
Scelerisque feugiat massa alias.
..

..important notitle
Admonition styled Division Block without a title.

Neque a massa.
Nunc mauris tempor.
Pede mauris sed.
Scelerisque feugiat massa alias.
..

Admonition styled paragraph.

Admonition styled paragraph without a title.

Admonition styled Division Block.

Neque a massa. Nunc mauris tempor. Pede mauris sed. Scelerisque feugiat massa alias.

Admonition styled Division Block without a title.

Neque a massa. Nunc mauris tempor. Pede mauris sed. Scelerisque feugiat massa alias.

The sidebar style renders text boxes containing digressions and observations related to the main narrative flow.

Examples

Rimu Markup HTML Preview

verse style

The verse style renders passages of text that retain line breaks. See also Citing quotes and verses and Controlling text alignment.

Examples

Rimu Markup HTML Preview
.verse
Verse styled paragraph.
Neque a massa.
Porttitor consectetuer commodo.

..verse align-center
#### Centered verse styled Division Block
Neque a massa.
Porttitor consectetuer commodo.

Nunc mauris tempor.
Pede mauris sed.
Scelerisque feugiat massa alias.
..

Verse styled paragraph. Neque a massa. Porttitor consectetuer commodo.

Centered verse styled Division Block

Neque a massa. Porttitor consectetuer commodo.

Nunc mauris tempor. Pede mauris sed. Scelerisque feugiat massa alias.

Using Macro, Replacement and Quote definitions in Safe Mode

Macro, Replacement and Quote definitions are not processed in Safe Mode. To apply Macro, Replacement or Quote definitions to Rimu markup that is processed in Safe Mode you need to load the definitions with a separate API call, for example:

Rimu.render(trusted_rimu_definitions, {safeMode: 0});
var html = Rimu.render(untrusted_rimu_markup, {safeMode: 5});

Mathematical formulae

The rimuc command supports MathJax LaTeX and MathML mathematical formulas. To include MathJax support use the rimuc command --mathjax option with the --layout option.

Examples

Rimu Markup
.-macros
A LaTeX inline formula: \(\sum_{i=0}^n i^2 = \frac{n^2+n}m{2}\)

A LaTeX block formula:

.-macros
\[\sum_{i=0}^n i^2 = \frac{n^2+n}m{2}\]

A MathML inline formula:
<math>
  <mi>E</mi><mo>=</mo><mrow><mi>m</mi><msup><mi>c</mi><mn>2</mn></msup></mrow>
</math>

A MathML block formula:

<math display="block">
  <mi>E</mi><mo>=</mo><mrow><mi>m</mi><msup><mi>c</mi><mn>2</mn></msup></mrow>
</math>
HTML Preview

A LaTeX inline formula: \(\sum_{i=0}^n i^2 = \frac{n^2+n}m{2}\)

A LaTeX block formula:

\[\sum_{i=0}^n i^2 = \frac{n^2+n}m{2}\]

A MathML inline formula: E=mc2

A MathML block formula:

E=mc2

See the latest MathJax documentation to learn how to use MathJax.

Conditional Inclusion

Macro invocations can be used to conditionally include and exclude Rimu source text. Here are some examples:

// Include script if `foo` value is non-blank.
{foo!}<script src="bar-min.js"></script>

// Skip paragraph if `foo` is blank.
{foo=}.+skip
Display this paragraph if macro `foo` is non-blank.

// Conditional inclusion of arbitrary blocks of Rimu source.
// Include some CSS if both `foo` and `bar` are non-blank.
// Works because a Division Block does not emit div tags if they
// have no HTML attributes.
{foo=}.+skip
{bar=}.+skip
..
<style>
  * { margin: 0; padding: 0; }
</style>
..

// Inline examples.
This line is included {foo=} if the value of foo is blank.
This line is included {foo!} if the value of foo is not blank.
This line is included {foo=one} if the value of foo is 'one'.
This line is included {foo=two} if the value of foo is 'two'.
This line is included {foo!\d+} if the value of foo is not a number.

Use Comments to unconditionally exclude text.

Be careful when mixing conditional and simple macros on the same line, for example:

{foo!}{multi-line-macro}

Because the simple macro is expanded before the conditional macro only the first line of the expanded {multi-line-macro} will be subject to {foo!} exclusion. Use the +skip block option attribute to exclude the entire {multi-line-macro}, for example:

{foo=}.+skip
{multi-line-macro}

Tables

Create tables using Block HTML elements (Rimu has no dedicated syntax for tables but you can use macros to simplify table creation).

HTML blocks must start at the left margin and end with a blank line.

The rimuc --layout option includes the bordered CSS class for styling bordered tables.

Examples

Rimu Markup
<table class="bordered"><tr>
<td style="width: 50%; padding: 6px;">

**Lorem ipsum dolor**. Sit amet venenatis. Erat nulla arcu. Lorem luctus
sem. Mauris vitae ipsum. Donec dui ac ridiculus quisque proin.
Lobortis lacus vestibulum sem.

##### Normal paragraph
Lorem ipsum dolor. Sit `amet venenatis`. Erat nulla arcu. Lorem luctus
sem. _Mauris vitae_ ipsum. Donec dui ac ridiculus quisque proin.
Lobortis lacus vestibulum sem.

##### Indented paragraph
  Neque a massa. Porttitor consectetuer commodo. Nunc nulla tempor
  tempor enim ornare. Mi nam id. Ornare mauris tempor. Pede mauris
  sed.  Scelerisque feugiat massa alias.

</td>
<td style="width: 50%; padding: 6px;">

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

- Augue et dui malesuada purus.

  If a list item is followed
  by an indented paragraph the
  indented paragraph is
  included in the list item.

</td>
</tr></table>
HTML Preview

Lorem ipsum dolor. Sit amet venenatis. Erat nulla arcu. Lorem luctus sem. Mauris vitae ipsum. Donec dui ac ridiculus quisque proin. Lobortis lacus vestibulum sem.

Normal paragraph

Lorem ipsum dolor. Sit amet venenatis. Erat nulla arcu. Lorem luctus sem. Mauris vitae ipsum. Donec dui ac ridiculus quisque proin. Lobortis lacus vestibulum sem.

Indented paragraph
Neque a massa. Porttitor consectetuer commodo. Nunc nulla tempor
tempor enim ornare. Mi nam id. Ornare mauris tempor. Pede mauris
sed.  Scelerisque feugiat massa alias.
  • 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.
  • Augue et dui malesuada purus.
    If a list item is followed
    by an indented paragraph the
    indented paragraph is
    included in the list item.

The use of inline HTML for tables instead of a Rimu-specific table syntax was a deliberate design decision:

See also Use macros to create tables.

Use macros to create tables

Creating tables with raw HTML is repetitive, time consuming and difficult to read.

Parametrized macros can be used to generate row oriented tables:

Table macro example 1

Rimu Markup
<table style="border-spacing:0.6em; border-collapse:separate">

{row} = '<tr>
<td style="width:25%">$$1</td>
<td style="width:20%">$$2</td>
<td style="width:20%">$$3</td>
<td style="width:35%">$$4</td>
</tr>
'

."font-weight:bold"
{row|Command |Should be named |Applied to |Description}

{row|Discard Snapshot (_Ctrl+Shift+D_) |Merge with Parent |Snapshot |Merges the snapshot file into the parent snapshot or disk image file and then deletes the now redundant snapshot file.}

{row|Revert to Current Snapshot (_Ctrl+Shift+R_) | |Current State |Deletes the current state returning the VM state to the most recent snapshot.}

{row|Discard Current Snapshot and State (_Ctrl+Shift+B_) |Delete Current Snapshot and State |Current State |Deletes the current state and the most recent snapshot returning the VM state to that of the penultimate snapshot. Use this command to delete snapshots.}

</table>
HTML Preview
Command Should be named Applied to Description
Discard Snapshot (Ctrl+Shift+D) Merge with Parent Snapshot Merges the snapshot file into the parent snapshot or disk image file and then deletes the now redundant snapshot file.
Revert to Current Snapshot (Ctrl+Shift+R) Current State Deletes the current state returning the VM state to the most recent snapshot.
Discard Current Snapshot and State (Ctrl+Shift+B) Delete Current Snapshot and State Current State Deletes the current state and the most recent snapshot returning the VM state to that of the penultimate snapshot. Use this command to delete snapshots.

Table macro example 2

Rimu Markup
{person} = '<table style="margin-bottom:0.3em"><tr>
<td style="width:40%">$$1</td>
<td style="width:20%">$$2</td>
<td>$$3</td></tr></table>
'

.bordered "font-weight:bold; color:#527bbd"
{person| Name        | Age    | Gender}
{person| Joe Bloggs  | 25     | Male}
{person| _Jim Smith_ | 31     | Male}
."color:red"
{person| Peg Legge   | **30** | Female}
HTML Preview
Name Age Gender
Joe Bloggs 25 Male
Jim Smith 31 Male
Peg Legge 30 Female

Macros can also be used to simplify columnar text layouts:

Columnar text layouts

Rimu Markup
// Each macro generates an HTML block which together generate a single table.
{column1} = '<table><tr><td style="width:33%;padding:0.5em;">
'
{column2} = '</td><td style="width:33%;padding:0.5em;">
'
{column3} = '</td><td style="width:33%;padding:0.5em;">
'
{end}     = '</td></tr></table>
'

## Two column table
{column1}
#### Column One
Rutrum imperdiet vitae vitae a suscipit semper potenti magna.

Proin id justo vestibulum rutrum neque consequat in nam morbi orci at.

  Feugiat habitant donec. Sem tincidunt arcu pellentesque suscipit
  accumsan.

{column2}
#### Column Two
Proin id Ante praesent scelerisque ligula vivamus in.

Amet neque ut enim molestiae est. Dictumst magna orci magnis donec
lectus lectus at sapien.

> Vivamus et metus. In a ut. Enim in lorem.

{end}

## Three column table
{column1}
#### Column One
Rutrum imperdiet vitae vitae a suscipit semper potenti magna.

Proin id justo vestibulum rutrum neque consequat in nam morbi orci at.

  Feugiat habitant donec. Sem tincidunt arcu pellentesque suscipit
  accumsan.

{column2}
#### Column Two
Proin id Ante praesent scelerisque ligula vivamus in.

Amet neque ut enim molestiae est. Dictumst magna orci magnis donec
lectus lectus at sapien.

> Vivamus et metus. In a ut. Enim in lorem.

{column3}
#### Column Three
Quibusdam suspendisse volutpat.

Pellentesque nunc lectus tellus cursus fusce.

.sidebar
Tincidunt proin lorem. Mi vel ut. Duis ipsum nam eget vitae ut
consequat quisque duis mollis magna arcu.

{end}
HTML Preview

Two column table

Column One

Rutrum imperdiet vitae vitae a suscipit semper potenti magna.

Proin id justo vestibulum rutrum neque consequat in nam morbi orci at.

Feugiat habitant donec. Sem tincidunt arcu pellentesque suscipit
accumsan.

Column Two

Proin id Ante praesent scelerisque ligula vivamus in.

Amet neque ut enim molestiae est. Dictumst magna orci magnis donec lectus lectus at sapien.

Vivamus et metus. In a ut. Enim in lorem.

Three column table

Column One

Rutrum imperdiet vitae vitae a suscipit semper potenti magna.

Proin id justo vestibulum rutrum neque consequat in nam morbi orci at.

Feugiat habitant donec. Sem tincidunt arcu pellentesque suscipit
accumsan.

Column Two

Proin id Ante praesent scelerisque ligula vivamus in.

Amet neque ut enim molestiae est. Dictumst magna orci magnis donec lectus lectus at sapien.

Vivamus et metus. In a ut. Enim in lorem.

Column Three

Quibusdam suspendisse volutpat.

Pellentesque nunc lectus tellus cursus fusce.

Use raw HTML or a macro:

Rimu Markup
HTML Preview

Inline citations

The following example shows how macros can be used to generate inline citations.

Inline citations

Rimu Markup
{LFB} = '<sup>
<abbr title="Latin for Beginners (D'Ooge) §$1">[LFB$1]</abbr>
</sup>'

Purus aliquam mauris a aliquam orci {LFB|42}.
Massa sit sit. Penatibus.

Maecenas at tellus {LFB|28}. Sapien quam mauris.
Non a pede in.
HTML Preview

Purus aliquam mauris a aliquam orci [LFB42] . Massa sit sit. Penatibus.

Maecenas at tellus [LFB28] . Sapien quam mauris. Non a pede in.

The {LBF} parameterised macro cites numbered sections from a publication using the HTML abbr element to create tooltips.

Meta Macros

You can define macros which, when invoked, generate other macros.

The Footnotes macros example generates footnote links and footnotes. The Table of contents macros example generates document section headers, links and table of contents entries from a section identifier and title.

Footnotes macros

Rimu Markup
// footnote generates two macros: a superscript link and the footnote.
{footnote} = '{$1} = '<sup><a href="#footnote-$1">$1</a></sup>' \
{footnote-$1} = '<span id="footnote-$1">$2</span>' \
'
{footnote|1|Ac _lacinia mi_.}
{footnote|2|[Egestas](https://example.com) congue.}

#### Lorum Ipsum
Purus aliquam mauris a aliquam orci{1}.
Massa sit sit. Penatibus.

Maecenas at tellus. Sapien quam mauris{2}.
Non a pede in.

."margin-top: 1.5em"
<hr>

. {footnote-1}
. {footnote-2}
HTML Preview

Lorum Ipsum

Purus aliquam mauris a aliquam orci1. Massa sit sit. Penatibus.

Maecenas at tellus. Sapien quam mauris2. Non a pede in.


  1. Ac lacinia mi.
  2. Egestas congue.

Table of contents macros

Rimu Markup
// toc macro generates section TOC entry, link macro and header macro.
// $1 = section ID, $2 = section title.
{toc} = '{$1} = '<#$1|$2>' \
{$1-header} = '.#$1
## $2' \
{$1}
'

#### Table of Contents
{toc|section1|Section One}
{toc|section2|Section Two}

{section1-header}
Link to {section2}.

{section2-header}
Link to {section1}.
HTML Preview

Table of Contents

Section One

Section Two

Section One

Link to Section Two.

Section Two

Link to Section One.

The backslash character is used to continue macro definition lines that end with a single-quote.

Macro tips

List item counters

In addition to the verse and sidebar CSS styles the rimuc tool --layout option also includes:

Examples

Rimu Markup HTML Preview
#### Numbered labeled list
.dl-numbered
One:: Item one.
Two:: Item two.
Three:: Item three.

.dl-counter
labeled list items.

#### Counted unordered list
- Item one.
- Item two.
- Item three.
- Item four.

There are {--ul-counter} unordered list items.

#### Counted ordered list
. Item one.
. Item two.

There are {--ol-counter} ordered list items.

Numbered labeled list

One
Item one.
Two
Item two.
Three
Item three.

labeled list items.

Counted unordered list

  • Item one.
  • Item two.
  • Item three.
  • Item four.

There are unordered list items.

Counted ordered list

  1. Item one.
  2. Item two.

There are ordered list items.

Append arbitrary elements to list items

An attached Division Block can be used to group and append arbitrary block elements to a list item.

Examples

Rimu Markup HTML Preview
- First list item.
..
Include a paragraph in the list item.

> And a Quoted paragraph.
..
- Second list item.
  • First list item.

    Include a paragraph in the list item.

    And a Quoted paragraph.

  • Second list item.

This works because if a Fenced Block immediately follows a list item without any intervening blank lines it will be rendered with the list item.

Applying Block Attributes to list item elements

Block Attribute elements within a list are applied to the next list item or attached list item element. This facilitates styling and linking within lists.

Examples

Rimu Markup HTML Preview
1. List item with attached green
   sidebar styled Division block.
.sidebar "color:green"
..
Urna aliquam pid, pulvinar augue ut
aenean enim cum lectus sed.
..

."color:orange"
2. List item with nested labled list.

.#labeled-list
    One:: Item one.
."color:red"
    Two:: Item two.

.#third-list-item "color:blue"
3. List item with attached bold Indented
   paragraph.

."font-weight:bold"
   Duis in tincidunt rhoncus nascetur
   lacus!

[Link to third list item](#third-list-item).

[Link to labeled list](#labeled-list).
  1. List item with attached green sidebar styled Division block.
  2. List item with nested labled list.
    One
    Item one.
    Two
    Item two.
  3. List item with attached bold Indented paragraph.
    Duis in tincidunt rhoncus nascetur
    lacus!

Link to third list item.

Link to labeled list.

Section numbering

Use the rimuc --section-numbers option with the --layout option to number top level h2 and h3 sub-sections. For example:

rimuc --layout sequel --section-numbers mydoc.rmu

The rimuc --section-numbers option is a shortcut for --prepend "{--section-numbers} = 'yes'".

Nested Fenced Blocks

Fenced blocks of the same type can be nested by using differing numbers of delimiter characters to distinguish between them.

Examples

Rimu Markup HTML Preview
""
Urna aliquam pid, pulvinar augue ut
aenean enim cum lectus sed, duis odio
lectus, augue non egestas amet? Magna
lectus?

"""
Enim ultricies odio rhoncus ultrices,
adipiscing in dictumst in, enim integer
vel mauris placerat in phasellus magna.
"""

Duis in tincidunt rhoncus nascetur
lacus!
""

Urna aliquam pid, pulvinar augue ut aenean enim cum lectus sed, duis odio lectus, augue non egestas amet? Magna lectus?

Enim ultricies odio rhoncus ultrices, adipiscing in dictumst in, enim integer vel mauris placerat in phasellus magna.

Duis in tincidunt rhoncus nascetur lacus!

List termination

List termination can be forced by following the list by two or more blank lines. This comes in handy if you want to follow one list immediately by another or if you want to separate an Indented paragraph from a preceding list.

Syntax surprises

Here are some situations that generate unexpected results.

Nested list item ambiguity

For readability Rimu list items can be optionally indented. If an Indented paragraph looks like a list item it will be rendered as a list item (because Lists take precedence over Indented paragraphs). To render an indented list item as an Indented paragraph change it to a fenced code block.

Examples

Rimu Markup HTML Preview
- List item.

  * Rendered as nested list item.

- List item.
``
* Rendered as code block.
``
  • List item.
    • Rendered as nested list item.
  • List item.
    * Rendered as code block.

Labelled list and delimited block ambiguity

If the first line of a delimited block ends with two colons it will be mistaken for a labelled list. For example, enclosing a labelled list in an HTML block comment. The problem arises because lists take precedence over delimited blocks. The work-around is to put the opening block delimiter on a separate line.

Examples

Rimu Markup HTML Preview
<!-- foobar::
Rendered as labelled list. -->

<!--
foobar::
Rendered as HTML block comment. -->
<!— foobar
Rendered as labelled list. —>

This issue only applies to HTML Block, Macro Definition and Normal Paragraph delimited blocks.

URLs

Braces in macro patterns

You need to escape closing brace characters in Inclusion and Exclusion macro patterns. For example:

{foo=x{2\}}

Escaping the brace serves two purposes: It excludes {2} from being seen as a Simple macro invocation and it stops the brace character from being seen as the Inclusion macro's closing brace

Escaped macro definitions

Macro definitions can be escaped by prefixing &#8203;\ (zero-width space character followed by backslash character). Simply prefixing a backslash is insufficent because the unescaped definition will be mismatched downstream.

Examples

Rimu Markup HTML Preview
&#8203;\{macro} = 'escaped definition'

​{macro} = 'escaped definition'

Preserving line breaks

There are three ways to preserve line breaks:

  1. Terminate lines with a Rimu line break (a space followed by a backslash character).
  2. Terminate lines with an HTML break element (<br>).
  3. Apply the preserve-breaks class to a Rimu block element and compile with the rimuc command --layout option.

Examples

Rimu Markup HTML Preview
Urna aliquam pid \
Aenean enim cum sed <br>
Augue non egestas amet?

.preserve-breaks
Urna aliquam pid
Aenean enim cum sed
Augue non egestas amet?

Urna aliquam pid
Aenean enim cum sed
Augue non egestas amet?

Urna aliquam pid Aenean enim cum sed Augue non egestas amet?

Controlling printer page breaks

The rimuc tool --layout option includes page-break and no-page-break CSS classes which apply page-break-before:always and page-break-inside:avoid properties respectively:

.sidebar no-page-break
..
Page breaks are avoided inside
this sidebar.
..

.page-break
### A header that starts on a new page

Controlling text alignment

The rimuc tool --layout option includes align-left, align-center and align-right CSS classes to apply the CSS text-align property. Use them to control the horizontal alignment of flowed inline elements (e.g. text, inline images):

Examples

Rimu Markup HTML Preview
.align-left
Enim odio ultrices

.align-center
Enim odio ultrices

.align-right
Enim odio ultrices

Enim odio ultrices

Enim odio ultrices

Enim odio ultrices

Citing quotes and verses

The rimuc command --layout option includes the CSS cite class for attributing quotes and verses. For example:

Examples

Rimu Markup HTML Preview
Quotation:

""
Enim ultricies odio rhoncus ultrices,
porttitor augue a amet, pulvinar
adipiscing in dictumst in, enim integer
vel mauris placerat in phasellus magna.
Nisi! Amet.

.cite
Anonymous
""

Verse:

.verse
..
Urna aliquam pid
Aenean enim cum sed
Augue non egestas amet?

.cite
A. N. Mouse
..

Quotation:

Enim ultricies odio rhoncus ultrices, porttitor augue a amet, pulvinar adipiscing in dictumst in, enim integer vel mauris placerat in phasellus magna. Nisi! Amet.

Anonymous

Verse:

Urna aliquam pid Aenean enim cum sed Augue non egestas amet?

A. N. Mouse

An example letter

Here's an example of a personal letter:

Examples

Rimu Markup
."font-family:serif; font-size:12pt;"
..

."margin-left:75%"
...
24 Milky Way \
Skyhome 1234 \

17th June 2016
...

."margin-bottom:1.5em"
Mr. A. N. Mouse \
P.O. Box 42     \
Riverbank 3120

."margin-bottom:1.2em"
Dear Andrew

Mattis pellentesque in lundium lectus penatibus turpis enim enim in,
mid velit. Eu lundium. Lundium! Porttitor! Porttitor purus lacus et
odio nisi amet in magna penatibus odio amet?

In urna rhoncus! Nec scelerisque enim in turpis pid, phasellus cras,
rhoncus, egestas aliquet lundium! Lundium auctor vel natoque enim.

."margin-top:2em"
Yours sincerely \
Joe Jetson
..
HTML Preview

24 Milky Way
Skyhome 1234

17th June 2016

Mr. A. N. Mouse
P.O. Box 42
Riverbank 3120

Dear Andrew

Mattis pellentesque in lundium lectus penatibus turpis enim enim in, mid velit. Eu lundium. Lundium! Porttitor! Porttitor purus lacus et odio nisi amet in magna penatibus odio amet?

In urna rhoncus! Nec scelerisque enim in turpis pid, phasellus cras, rhoncus, egestas aliquet lundium! Lundium auctor vel natoque enim.

Yours sincerely
Joe Jetson

General purpose macro processor

You can use Rimu as a general purpose macro text processor. This is achieved by enveloping the text to be processed in a Division Block. For example:

// Macro definitions.
{sans-font} = 'Arial, Helvetica, sans-serif'
{primary-color} = '#527bbd'
{primary-background} = 'white'
{text-color} = '#333333'

// Only expand macros.
.+macros -specials -spans -container
..
body {
  font-family: {sans-font};
  font-size: 14px;
  line-height: 20px;
  color: {text-color};
  background-color: {primary-background};
  margin: 1em;
  max-width: 50em;
}

h1, h2, h3, h4, h5, h6 {
  margin: 10px 0;
  color: {primary-color};
}
..

Passing arbitrary text to the output

To pass arbitrary blocks of text directly to the output disable all processing options. For example:

// Disable all processing inside Division Block.
.-macros -spans -specials -container
..
function toggleToc() {
    document.getElementById("toc").classList.toggle('toc-visible');
}

window.onclick = toggleToc
..

To enable only macro expansion drop the -macros option (c.f. General purpose macro processor).

Building websites with Rimu

Take a look at hindsite if you want to build websites from Rimu source.

hindsite is a fast, lightweight static website generator. It builds static websites from Rimu or Markdown source documents.

Keyword comments

It's often useful to categorise comments by a keword e.g. todo, fixme. The following Rimu replacement definition implements keyword comments (it's in the example .rimurc file).

/\\?@(deprecated|fixme|important|note|todo|warning)\b.*/ = ''

Examples

Rimu Markup HTML Preview
Tincidunt proin lorem @todo Mi vel ut.

@note magna arcu.
Duis ipsum nam eget vitae ut
consequat quisque duis mollis
magna arcu.

Tincidunt proin lorem

Duis ipsum nam eget vitae ut consequat quisque duis mollis magna arcu.