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

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

• The {sidebar} macro shows how you can inject CSS styles into a Division Block (you can also use use HTML <style> elements to style the output).
• Note how macro definitions can span multiple lines and can contain any valid Rimu markup (including HTML and blank lines).

See also:

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

Intra-document Links

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

.#link-target
This paragraph has ID `link-target`.

[This link](#link-target) takes you to
the above paragraph.

<#link-target|Same link> using alternative
Rimu URL syntax.

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

Some JavaScript code:

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

Some Python code:

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

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

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

\_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 common text is included in mydocument.rmu by invoking the {common-text} macro.
• You can disable macro expansion inside the text by preceeding the block macro definition with the line:

  .-macros

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

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

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

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

sidebar style

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

Examples

.sidebar
Sidebar styled paragraph.
Nunc mauris tempor.
Pede mauris sed.

..sidebar
#### Sidebar styled Division Block
Neque a massa.
Porttitor consectetuer commodo.

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

verse style

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

Examples

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

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

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

• Macro expansion has been disabled in LaTeX formulas to stop {i=0} and {2} in the LaTeX formualae from being mistaken for Rimu macro invocations.

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

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

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.

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

• A large number of formatting options (e.g. for headers and footers; cell widths, heights, alignment and spans) are required to accommodate all but the simplest of tables. This makes for a complex and noisy syntax — precisely what we're trying to avoid.
• Coming up with a syntax that is both recognizably tabular and easily written is difficult — imagine trying to write the above example in a way that maintains the side-by-side cell layout.
• Editing tabular layouts is unwieldy — text editors are designed to edit line-oriented text.
• At first blush tables come across as a hugely useful feature, but most documentation makes surprising little use of tables.

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

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

Table macro example 2

{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}

• Block HTML elements must be followed by a blank line.
• The macro invocations emit HTML (block) elements and must be contained on a single line otherwise they will be processed as paragraphs.
• Double-dollar macro parameters are necessary because text formatting is not expanded and special characters are not escaped inside Block HTML elements.

Macros can also be used to simplify columnar text layouts:

Columnar text layouts

// 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}

Feugiat habitant donec. Sem tincidunt arcu pellentesque suscipit
accumsan.

Feugiat habitant donec. Sem tincidunt arcu pellentesque suscipit
accumsan.

Image links

Use raw HTML or a macro:

Image links

// Raw HTML.
<a href="https://example.com"><img src="image-1.jpg"></a>

// Size image and open the link in a new browser tab.
{linked-image}='<a href="$3" target="_blank"><img src="$1" width="$2"></a>'

{linked-image|image-1.jpg|150|image-1.jpg}

{linked-image|image-1.jpg|300|https://example.com}

Inline citations

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

Inline citations

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

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

// 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}

Table of contents macros

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

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

Macro tips

• Use the | character entity to display a | character inside a macro parameter value.
• Closing block delimiters must be explicit and cannot be sourced from a macro invocation (because Rimu elements are recognized before macro expansion).
• A macro invocation can be rendered verbatim in a code block by disabling macro expansion. For example:

  .-macros
  ``
  {example-42}
  ``

• Macro definition elements cannot be prefixed with an Inclusion/Exclusion macro (see Conditional Inclusion).
• Macro invocations in macro definition values are expanded when the macro is declared, not when it is invoked. You can defer evaluation until the macro is invoked by escaping macro invocations or (in the case of multi-line definitions) by using the -macros Block Attributes option. For example this Rimu markup:

  {m1} = 'foo'
  {m2} = '{m1} \{m1}'
  {m2}
  
  {m1} = 'bar'
  {m2}

  Generates:

  <p>foo foo</p>
  <p>foo bar</p>

List item counters

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

• dl-counter, ol-counter and ul-counter CSS classes for counting labeled, numbered and bullet list items.
• {--dl-counter}, {--ol-counter} and {--ul-counter} counter macros.
• The dl-numbered CSS class for numbering labeled list items.

Examples

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

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

- 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

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

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

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

- 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

<!-- foobar::
Rendered as labelled list. -->

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

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

URLs

• To include a [ character in a Markdown URL or image captions, use a [ entity instead of the [ character.

  The caption in the following example displays as the [Main] section (if the [ character were used the caption would be Main] section):

  [the [Main] section](#main)

• To include a ) character in a Markdown URL , use a ) entity instead of the ) character. For example:

  [wolves](#the_wolf_(lupus))

• To include a > character in a Rimu URL or image captions, use a > entity instead of the > character.

  The caption in the following example displays as <Header> (if the > character were used the caption would be <Header):

  <#header|<Header&gt;>

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 ​\ (zero-width space character followed by backslash character). Simply prefixing a backslash is insufficent because the unescaped definition will be mismatched downstream.

Examples

​\{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

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?

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

.align-left
Enim odio ultrices

.align-center
Enim odio ultrices

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

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

An example letter

Here's an example of a personal letter:

Examples

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

• The font parameters are set by enclosing the entire contents in a Division Block.
• If you want to control the print margins put something like this at the start of the document:

  <style>
  @page
  { margin: 25mm 25mm 25mm 25mm; }
  </style>

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

• Use rimuc to expand the macros, for example:

  rimuc --output main.css main.rmu

• This technique can be combined with conditional macro expansion and all the other Rimu macro features.

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

• A keyword comment comprises a keyword plus any text following it on the same line.
• Keyword comments are ommitted from the Rimu HTML output.
• Prefixing the keyword with an @ character is simply a convention to minimise ambiguity.

Examples

Tincidunt proin lorem @todo Mi vel ut.

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