Links

Table of Contents

Rimu Tips

TIP: Click the Edit icon in the examples below to enable live example editing of the Rimu source.

HTML is valid Rimu

You are free to mix any valid HTML into a Rimu document — no special syntax or relearning 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. Google's Chrome web browser has an option to print HTML to a PDF file, other browsers have PDF add-ons that perform the same function, this does a good job especially if you use the rimuc --styled option.
  2. Use an HTML to PDF conversion program such as HTMLDOC.

Extend Rimu with Macros

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

Examples

Rimu source
// 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>'
{playground} = '[Rimu Playground](http://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 {playground} for documentation and hands-on
experimentation.

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

Fun with Macros

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

Note This document is not yet finished.

Intra-document Links

To link to another place within a document: Create an ID for the element you want to link to (using the Rimu Block Attribute element) then create a link to it using a fragment identifier URL.

Examples

Rimu source Rendered HTML

NOTE: The rimuc --styled option automatically synthesises id attributes for top level #, ## and ### header elements that do not already have an id.

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 --styled 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 source Rendered HTML
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."

Set the no-highlight class to disable syntax highlighting for a code block. Adding the no-highlight class to all code blocks using Delimited Block Definitions turns off highlighting unless the language class is explicitly set. The example .rimurc file does this with these custom definitions:

|code| = '<pre class="no-highlight"><code>|</code></pre>'
|indented| = '<pre class="no-highlight"><code>|</code></pre>'

Syntax shared with Markdown

The following subset of Rimu elements is compatible with Markdown:

Headers
Headers using # character header prefixes.
Code blocks
  • Indented paragraphs (at least four spaces) render like Markdown code blocks.
  • Rimu Fenced Code blocks with three or more backticks are compatible with GitHub Flavored Markdown Fenced 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 * 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.

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

Processing HTML and Markdown with the rimuc command

rimuc passes the contents of input files with a .html extension directly to the output. This allows you to generate styled HTML5 documents from raw HTML files (HTML with no <html>, <head> or <body> tags), or from non Rimu compatible Markdown files, using the rimuc --styled option. Examples:

Raw HTML file
Convert mydoc.html to styled HTML5 document with table of contents:
rimuc --styled --dropdown-toc mydoc.html
Arbitrary Markdown file
Convert mydoc.md to styled HTML5 document after first converting it to raw HTML with markdown:
markdown mydoc.md > mydoc.html
rimuc --styled mydoc.html
Rimu compatible Markdown file
Convert mydoc.md to styled HTML5 document:
rimuc --styled mydoc.md

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 source Rendered HTML
\_escaped quote_

**escaped closing\** quote**

``backticks in `code quote```

\# Escaped header.

_escaped quote_

escaped closing** quote

backticks in `code quote`

# Escaped header.

NOTE: 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 --styled --prepend "{--title}='Kotlin Notes'" kotlin-notes.rmu

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

rimuc --styled --title "Kotlin Notes" kotlin-notes.rmu

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

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.

Render contiguous Indented paragraphs with a single element

When you have multiple Indented paragraphs separated by blank lines the usual expectation is that they will be contained in a single listing — to achieve this separate the paragraphs with lines containing one or more space characters.

Examples

Rimu source Rendered HTML
#### Separator line is blank

  Neque a massa. Porttitor
  consectetuer commodo.

  Neque a massa. Porttitor
  consectetuer commodo.


#### Separator line with spaces

  Neque a massa. Porttitor
  consectetuer commodo.
  
  Neque a massa. Porttitor
  consectetuer commodo.


#### Use a code block instead

```
Neque a massa. Porttitor
consectetuer commodo.

Neque a massa. Porttitor
consectetuer commodo.
```

Separator line is blank

Neque a massa. Porttitor
consectetuer commodo.
Neque a massa. Porttitor
consectetuer commodo.

Separator line with spaces

Neque a massa. Porttitor
consectetuer commodo.
 
Neque a massa. Porttitor
consectetuer commodo.

Use a code block instead

Neque a massa. Porttitor
consectetuer commodo.

Neque a massa. Porttitor
consectetuer commodo.

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 source Rendered HTML
Turn <- left then right ->

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

"Left and right double-quotes".

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

IMPORTANT: Admonition.

TODO 10 examples +-2

Turn ← left then right →

Copyright © 2015 — trademarked™.

“Left and right double-quotes”.

The 3rd H2O molecule…

IMPORTANT: Admonition.

TODO 10 examples ±2

Custom styling

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.

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

Themes

A theme is the overall typographical style of the rendered HTML document. You can tailor the theme using custom CSS style elements.

The rimuc command supports named themes with the --theme option, all this does is set the --theme macro value which is then used to conditionally include HTML style elements.

The following example styles the output using the built-in graystone theme:

rimuc --styled --theme graystone document.rmu

You can create your own themes or tweak existing themes by conditionally including HTML 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 when the --theme macro value includes the word redheads, for example:

rimuc --styled --theme redheads document.rmu

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

rimuc --styled --theme "graystone redheads" document.rmu

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

Verse and sidebar styles

The rimuc command --styled option includes verse and sidebar CSS styles for poetry and highlighted passages of text.

Examples

Rimu source Rendered HTML
Verse styled paragraph:

.verse
Neque a massa.
Porttitor consectetuer commodo.

Verse styled Division Block:

.verse
..
#### Lorum Ipsum
Neque a massa.
Porttitor consectetuer commodo.

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

Sidebar styled paragraph:

.sidebar
Neque a massa.
Porttitor consectetuer commodo.

Sidebar styled Division Block:

.sidebar
..
#### Lorum Ipsum
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.

Verse styled Division Block:

Lorum Ipsum

Neque a massa. Porttitor consectetuer commodo.

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

Sidebar styled paragraph:

Sidebar styled Division Block:

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

Examples

Rimu source
.-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>
Rendered HTML

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 Rimu source text:

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

// Include paragraph if `foo` is blank.
{foo=}.+skip
Macro `foo`
must be blank.

// Conditional inclusion of arbitrary blocks of Rimu source.
// Assign `x` and `y` macro values and include some CSS if `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
..
{x} = '42'
{y} = '24'
<style>
  * { margin: 0; padding: 0; }
</style>
..

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

// Use parametrized macros to exclude arbitrary inline text.
{foo} = ''
Mauris vitae {foo|This text is excluded}

{foo} = '$1'
Mauris vitae {foo|This text is included}

Tables

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

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

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

Examples

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

.text-info
**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 {mark|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>
Rendered HTML

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:

Row oriented tables

Rimu source
{person} = '<table><tr><td style="width:15em">$$1</td>
<td style="width:5em">$$2</td>
<td>$$3</td></tr></table>
'

.bordered "color:#527bbd;"
{person| **Name**    | **Age**| **Gender**}
{person| Joe Bloggs  | 25     | Male}
{person| _Jim Smith_ | 31     | Male}
."color:red;"
{person| Peg Legge   | **30** | Female}
Rendered HTML
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 source
// 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>
'

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

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.

Macro meta-programming

You can define macros which, when invoked, generate other macros. A good example of this is the generation of document section headers, links and table of contents entries from a section identifier and title.

Examples

Rimu source
// toc macro generates section TOC entry, link macro, 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}.
Rendered HTML

Table of Contents

Section One

Section Two

Section One

Link to Section Two.

Section Two

Link to Section One.

NOTE: 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 --styled option also includes CSS classes for counting list items and for numbering labeled list items.

Examples

Rimu source Rendered HTML
#### 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.

.ul-counter
unordered list items.

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

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

unordered list items.

Counted ordered list

  1. Item one.
  2. Item two.

ordered list items.

Include arbitrary elements in list items

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

Examples

Rimu source Rendered HTML
- 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.

Block Attributes within lists

To apply Block Attributes elements to a nested list or an attached element, envelope the Block Attributes and the attached element in a Division Block (this is a specific application of the previous tip).

Note the use of a nested Division block in the first list item in the example below.

Examples

Rimu source Rendered HTML
- List item with green sidebar
  styled Division block.
..
.sidebar "color:green"
...
Urna aliquam pid, pulvinar augue ut
aenean enim cum lectus sed.

Duis odio lectus, augue non egestas
amet? Magna lectus?
...
..

- List item with verse styled
  paragraph.
..
.verse
Urna aliquam pid,
pulvinar augue ut,
aenean enim cum.
..

- List item with nested numbered
  [labeled list](#example-list).
..
.dl-numbered #example-list
One:: Item one.
Two:: Item two.
Three:: Item three.
..

- List item with bold Indented
  paragraph.
..
."font-weight:bold"
  Duis in tincidunt rhoncus nascetur
  lacus!
..
  • List item with green sidebar styled Division block.
  • List item with verse styled paragraph.

    Urna aliquam pid, pulvinar augue ut, aenean enim cum.

  • List item with nested numbered labeled list.
    One
    Item one.
    Two
    Item two.
    Three
    Item three.
  • List item with bold Indented paragraph.
    Duis in tincidunt rhoncus nascetur
    lacus!

Section numbering

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

rimuc --styled --section-numbers mydoc.rmu

The rimuc --section-numbers option is a shortcut for ` = '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 source Rendered HTML
""
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 source Rendered HTML
- 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.

URL captions

Controlling line breaks

There are three ways to inhibit text wrapping and 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. Inject the line-breaks CSS class into a Rimu block element and compile with the rimuc command --styled option.

Examples

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

.line-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 page breaks

You can control printer page breaks by using Rimu Attribute Blocks to inject CSS page-break-inside, page-break-before and page-break-after properties into HTML output elements.

Examples:

.sidebar "page-break-inside:avoid"
..
Page breaks are avoided inside
this sidebar.
..

."page-break-before:always"
### A header that starts on a new page

The rimuc tool --styled option includes page-break and no-page-break CSS classes which apply page-break-before:always and page-break-inside:avoid properties respectively. Here is the previous example using the rimuc page break classes:

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

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

Controlling text alignment

You can control the horizontal alignment of flowed inline elements (e.g. text, inline images) by injecting the CSS text-align property into the container block element using the Rimu Attribute Blocks element. For example:

Examples

Rimu source Rendered HTML
."text-align:center"
Enim odio ultrices

Enim odio ultrices

The rimuc tool --styled option includes align-left, align-center and align-right CSS classes. Here is the previous example using the align-center text alignment class:

Examples

Rimu source Rendered HTML
.align-center
Enim odio ultrices

Enim odio ultrices

Citing quotes and verses

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

Examples

Rimu source Rendered HTML
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 source
."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
.....................................
Rendered HTML

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

Automatically recompile and display Rimu source

To automatically recompile Rimu source to HTML and refresh the webpage in the Chrome browser use entr(1) to recompile, for example:

ls README.md | entr rimuc -s README.md

Then use the Chrome LivePage extension to auto-refresh the file after it is recompiled.

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 in Division Block.
.-spans -specials -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](#general purpose macro processor)).