Links
Table of Contents
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:
- Use Libre Office Writer or Microsoft Word to open the HTML document then export it to a PDF file.
- Use a command-line application such as wkhtmltopdf to convert HTML to PDF.
- 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 |
|
HTML | Preview
Fun with MacrosHeads 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:
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.
- 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:
Some Python code:
|
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.
- Bullet lists with
- 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:
- 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.
- 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:
- First convert Rimu to raw HTML using the
rimuc command e.g.
rimuc mydoc.rmu > mydoc.html
- 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
# 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
Rimu Markup | HTML Preview |
|
Turn ← left then right → Copyright © 2015 — trademarked™. “Left and right double-quotes”.
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:
- Change existing styling. The following example changes the color of
all headers to red:
<style> h1, h2, h3, h4, h5, h6 { color: red; } </style>
- 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.
- 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
|
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. |
sidebar
style
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 styled paragraph. Neque a massa. Porttitor consectetuer commodo. Centered verse styled Division BlockNeque 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 |
|
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: A MathML block formula: |
- 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
Rimu Markup |
|
||
HTML | Preview
|
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
Rimu Markup |
|
||||||||||||||||
HTML | Preview
|
Table macro example 2
Rimu Markup |
|
||||||||||||
HTML | Preview
|
- 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
Rimu Markup |
|
|||||
HTML | Preview
Two column table
Three column table
|
Image links
Use raw HTML or a macro:
Image links
Rimu Markup |
|
HTML | Preview
Inline citations
The following example shows how macros can be used to generate inline citations.
Inline citations
Rimu Markup |
|
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 |
|
HTML | Preview
Table of contents macros
Rimu Markup |
|
HTML | Preview
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
andul-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
Rimu Markup | HTML | Preview
|
Numbered labeled list
labeled list items. Counted unordered list
There are unordered list items. Counted ordered list
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 beMain] 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>>
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
Rimu Markup | HTML | Preview
|
{macro} = 'escaped definition' |
Preserving line breaks
There are three ways to preserve line breaks:
- Terminate lines with a Rimu line break (a space followed by a backslash character).
- Terminate lines with an HTML break element (
<br>
). - Apply the
preserve-breaks
class to a Rimu block element and compile with therimuc
command--layout
option.
Examples
Rimu Markup | HTML | Preview
|
Urna aliquam pid 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
|
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:
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 |
|
HTML | Preview
24 Milky Way 17th June 2016 Mr. A. N. Mouse 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 |
- 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
Rimu Markup | HTML Preview |
|
Tincidunt proin lorem Duis ipsum nam eget vitae ut consequat quisque duis mollis magna arcu. |