Links

Table of Contents

Rimu Reference

Rimu is a readable-text to HTML markup language inspired by AsciiDoc and Markdown.

At its core Rimu is a simple readable-text markup similar in scope to Markdown, but with two additional areas of functionality (both built into the Rimu markup syntax):

Plus:

Installing Rimu

Install Rimu as a Node.js module (includes the rimu library and the rimuc command-line tool):

sudo npm install -g rimu

Resources

Learning

Example applications

See the API documentation.

rimuc command

rimuc is a Node.js command-line tool that converts Rimu source (or Rimu compatible Markdown) to HTML.

The --styled option outputs an HTML5 conformant document containing the generated HTML, themed styling, an optional table of contents and optional code syntax highlighting.

Run rimuc --help to view the rimuc manpage:

NAME
  rimuc - convert Rimu source to HTML

SYNOPSIS
  rimuc [OPTIONS...] [FILES...]

DESCRIPTION
  Reads Rimu source markup from stdin, converts them to HTML
  then writes the HTML to stdout. If FILES are specified
  the Rimu source is read from FILES. The contents of files
  with an .html extension are passed directly to the output.

  If a file named .rimurc exists in the user's home directory
  then its contents is processed (with --safe-mode 0) after
  --prepend sources but before any other inputs.
  This behavior can be disabled with the --no-rimurc option.

OPTIONS
  -h, --help
    Display help message.

  -l, --lint
    Check the Rimu source for inconsistencies and errors.

  -o, --output OUTFILE
    Write output to file OUTFILE instead of stdout.
    If OUTFILE is a hyphen '-' write to stdout.

  -p, --prepend SOURCE
    Process the SOURCE text before other inputs.
    Rendered with --safe-mode 0.

  --no-rimurc
    Do not process .rimurc from the user's home directory.

  -s, --styled
    Include an HTML header and footer for styling the HTML output
    document. If only one source file is specified and the --output
    option is not specified then the output is written to a
    same-named file with an .html extension.

  --safe-mode NUMBER
    Non-zero safe modes ignore: Definition elements; API option elements;
    HTML attributes in Block Attributes elements.
    Also specifies how to process HTML elements:
    --safe-mode 0 renders HTML (default).
    --safe-mode 1 ignores HTML.
    --safe-mode 2 replaces HTML with --html-replacement option value.
    --safe-mode 3 renders HTML as text.
    Add 4 to --safe-mode to ignore Block Attribute elements.
    Add 8 to --safe-mode to allow Macro Definitions.

  --html-replacement TEXT
    Embedded HTML is replaced by TEXT when --safe-mode is set to 2.
    Defaults to '<mark>replaced HTML</mark>'.

  --theme THEME, --lang LANG, --title TITLE, --highlightjs, --mathjax,
  --sidebar-toc, --dropdown-toc, --custom-toc, --section-numbers
    Shortcuts for the following prepended macro definitions:
    --prepend "{--theme}='THEME'"
    --prepend "{--lang}='LANG'"
    --prepend "{--title}='TITLE'"
    --prepend "{--highlightjs}='true'"
    --prepend "{--mathjax}='true'"
    --prepend "{--sidebar-toc}='true'"
    --prepend "{--dropdown-toc}='true'"
    --prepend "{--custom-toc}='true'"
    --prepend "{--section-numbers}='true'"

  --styled-name NAME
    Specify the --styled option header and footer files:
    'classic': Legacy styling (default).
    'flex':    Flexbox "mobile first" styling (experimental).
    'v8':      Rimu version 8 styling.

STYLING MACROS AND CLASSES
  The following macros and CSS classes are available when the
  --styled option is used:

  Macro name         Description
  _______________________________________________________________
  --                 Blank macro (empty string).
  --theme            Set styling themes.
                     Theme names: default, graystone.
  --lang             HTML document language attribute value.
  --title            HTML document title.
  --highlightjs      Set to non-blank value to enable syntax
                     highlighting with Highlight.js.
  --mathjax          Set to a non-blank value to enable MathJax.
  --sidebar-toc      Set to a non-blank value to generate a
                     table of contents sidebar.
  --dropdown-toc     Set to a non-blank value to generate a
                     table of contents dropdown menu.
  --custom-toc       Set to a non-blank value if a custom table
                     of contents is used.
  --section-numbers  Apply h2 and h3 section numbering.
  _______________________________________________________________
  These macros must be defined prior to processing (using rimuc
  options or in .rimurc).

  CSS class        Description
  ______________________________________________________________
  verse            Verse format (paragraphs, division blocks).
  sidebar          Sidebar format (paragraphs, division blocks).
  cite             Quote and verse attribution.
  bordered         Add borders to table.
  align-left       Text alignment left.
  align-center     Text alignment center.
  align-right      Text alignment right.
  no-print         Do not print.
  line-breaks      Honor line breaks in source text.
  page-break       Force page break before the element.
  no-page-break    Avoid page break inside the element.
  dl-numbered      Number labeled list items.
  dl-horizontal    Format labeled lists horizontally.
  dl-counter       Prepend dl item counter to element content.
  ol-counter       Prepend ol item counter to element content.
  ul-counter       Prepend ul item counter to element content.
  ______________________________________________________________

Example usage:

  1. Use rimuc as a filter:
    echo 'Hello *Rimu*!' | rimuc
  2. Generate a styled HTML Web page including a sidebar table of contents and code syntax highlighting styling macro shortcut options:
    rimuc --styled --sidebar-toc --highlightjs reference.rmu
  3. Prefix a custom macro definition:
    rimuc --prepend "{annotations}='yes'" showcase.rmu
  4. Compile multiple source files to single output file:
    rimuc -o book.html frontmatter.rmu chapter*.rmu backmatter.rmu

--styled option

The --styled option works by prepending a header file and appending a footer file to the list of source files. The actual header and footer files is determined by the --styled-name option.

The Rimu markup in the header and footer files performs the following functions:

All features enabled by the --styled option are implemented with Rimu source code in the header and footer files — they are not hard-wired into Rimu — and serve to illustrate the power and flexibility of the Rimu markup language.

Styled names

The --styled-name option is used to choose between the following header and footer files:

classic
Legacy (default) styling.
flex
Flexbox “mobile first” styling (experimental). Examples:
v8
Rimu version 8 styling.

Slug generation

The --styled option includes a JavaScript slug generator to synthesize header identifier slugs at load-time for top level h1, h2 and h3 HTML header elements that do not already have an explicit id attribute. Slugs are generated from header titles as follows:

  1. Convert the title to lowercase.
  2. Replace spaces with a dash.
  3. Remove characters that are not alphanumeric, dashes or underscores. If no characters remain the slug is set to x.
  4. If an existing element has a matching id then the slug is successively postfixed with -2, -3… until a unique id is found.

For example a header with the title The End! will be assigned an id attribute value the-end.

NOTE: Synthesised slugs are generated dynamically when the page is rendered and are not visible from other documents — if you want to link the location from another document you will need to create an explicit anchor using a Block Attribute id. For example:

.#section1
## This section header has attribute `id="section1"`

Table of contents generation

In conjunction with the rimuc --styled option, the --sidebar-toc and --dropdown-toc options will generate sidebar-styled and dropdown-styled table of contents (TOC) respectively. The --custom-toc option allows the user to include a custom TOC.

If the --sidebar-toc macro or the --dropdown-toc macro is non-blank then JavaScript and HTML is included in the output to generate (at load time) a TOC from the top level h1, h2 and h3 HTML header elements. This page was compiled using the --sidebar-toc option, the Rimu Playground page has been compiled using the --dropdown-toc option.

Use the no-auto-toc CSS class attribute to exclude a section header from the TOC, for example:

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

Custom Table of contents

The --custom-toc option can be used in conjunction with the --sidebar-toc and --dropdown-toc options. The --custom-toc option inhibits the generation of an HTML TOC container. It is up to the user to include a custom HTML TOC (Rimu documentation has a custom TOC).

Here is the default TOC container, use it as a template to build your own custom TOC:

<div id="toc">
  <div id="auto-toc"></div>
</div>

API

Rimu has just one API to convert Rimu markup to HTML:

render(source [, options])

The source argument is a string containing Rimu markup. The return value is a string containing the resultant HTML. The optional options argument controls rendering behaviour.

The render() API is stateful: Macros and custom element definitions are retained across API calls along with API options. Use the reset option to set the default state.

Example usage

Node.js example (Rimu has been previously installed from npm):

var Rimu = require('rimu');
var html= Rimu.render('Hello *Rimu*!', {safeMode:1});

HTML script tag example (the compiled and minified rimu.min.js library can be found in the Rimu npm package ./rimu/bin folder):

<script src="rimu.min.js"></script>
<script>
  console.log(Rimu.render('Hello *Rimu*!', {reset:true, safeMode:2}));
</script>

API options

The options argument is an object with zero or more of the following properties:

safeMode
This option has a number value that controls how Rimu renders embedded HTML and how Rimu definition and option elements will be processed:
0 => Render HTML (default behavior).
1 => Ignore HTML.
2 => Replace HTML with the 'htmlReplacement' option string.
3 => Render HTML as text.
Add 4 to safeMode to ignore Block Attribute elements.
Add 8 to safeMode to allow Macro Definitions.
  • If safeMode is zero all Rimu elements will be processed.
  • If safeMode is non-zero the following Rimu elements are ignored:
    • Rimu definition elements (Delimited Block, Macro, Quote and Replacement definitions).
    • API Option elements.
    • HTML attributes in Block Attribute elements.
  • Add 4 to safeMode to ignore Block Attribute elements completely, this ensures HTML element IDs cannot be created and that CSS classes or properties cannot be used explicitly.
  • Add 8 to safeMode to allow Macro Definitions. Allowing Macro Definitions is not intrinsically unsafe because their safety or otherwise is solely determined by the safety of their constituent elements.
  • For example, a safeMode value of 13 (1+4+8) skips HTML elements, allows macro definitions but skips all other Rimu definition elements along with API option elements.
  • Once a non-zero safeMode has been set then it can only be reset by a render() API call with a safeMode:0 or a reset:true option.
htmlReplacement
A string that replaces embedded HTML when safeMode is set to 2. Defaults to <mark>replaced HTML</mark>.
callback
callback is a function that handles diagnostic events emitted by the render() API. The callback function message argument is an object with a type property ('error', 'warning' or 'info') and a text property (a string containing the diagnostic message). Example usage:
var html = Rimu.render('Hello *Rimu*!', {
  callback: function(message) {
    console.log(message.type + ': ' + message.text);
  }
});
reset
This boolean option causes the render() API to be set to its default state (default option values; default Quotes, Replacements and Delimited Block definitions; no macro definitions; no callback). The reset option is processed before other options.

API Option elements

API options can be set in the Rimu source using a Line Block element with the following syntax:

.option-name = 'option-value'

For example, the following API Option element ensures all subsequent raw HTML is not passed to the output:

.safeMode = '1'

Documents

A Rimu document consists of a sequence of zero or more Block elements. Element types fall into three broad categories: Delimited Blocks, Line Blocks and Inline elements.

Delimited Blocks

A Delimited Block consists of an opening delimiter line followed by zero or more content lines and terminated with a closing delimiter line. Depending on the element type the delimiter lines may or may not contain textual content. Paragraphs and Fenced Blocks are Delimited Blocks. Delimited Block behaviour is user customizable.

Line Blocks

A Line Block consists of a single line. Headers, Block Attributes, single-line comments and Element Definitions are all Line Block elements.

Inline elements

Inline elements are contained within the textual content of some block elements. There are three types of Inline elements: Macro Invocations, Quotes and Replacements.

Taxonomy

Rimu markup elements are categorized as follows:

Block elements Delimited Blocks HTML Block Fenced Blocks Code Block Division Block Quote Block Macro Definition Multi-line Comment Paragraphs Indented Paragraph Normal Paragraph Quote Paragraph Line Blocks API Option Block Attributes Block Image Element Definitions Macro Definition Quote Definition Replacement Definition Delimited Block Definition Header Single-line Comment Lists Bullet List Numbered List Labeled List Inline elements Macro Invocations Exclusion Inclusion Parametrized Simple Quotes Bold Emphasis Monospaced Strikethrough Replacements Character entity HTML tag Image Line break URL

Document processing

Rimu scans the input text for block elements. When a block element is matched it is converted to HTML on the output.

Block elements in the source markup are matched in the following order (first to last):

  1. Line Blocks
  2. Lists
  3. Delimited Blocks

Inline elements are processed in the following order (first to last):

  1. Macro invocations
  2. Replacements
  3. Quotes

Special character substitution takes place last. Inline substitutions in multi-line block elements can be controlled using block-options in the Block Attributes element.

Comments

A Multi-line comment starts with a line containing only /* and ends with a line containing only */.

A Single-line comment is a line of text starting with //.

Examples

Rimu source
/*
  This comment does not appear in the
  rendered HTML.
*/

// This comment does not appear in the rendered HTML.

<!-- This comment appears in the rendered HTML. -->
Rendered HTML

Headers

A Header is a Line Block element containing a title which is prefixed by 1 to 6 # or = characters. A matching postfix is optional.

Examples

Rimu source Rendered HTML
# h1 header
## h2 header ##
### h3 header
#### h4 _header_ ####
===== h5 header
====== h6 header

h1 header

h2 header

h3 header

h4 header

h5 header
h6 header

Fenced Blocks

Fenced blocks are Delimited Blocks bounded by opening and closing delimiter lines consisting of two or more delimiter characters starting at the left margin.

Code Block

By default the all text in a Code Block is rendered verbatim. The generated HTML is enveloped with <pre><code>...</code></pre> tags. The Code Block delimiter character is a backtick.

Examples

Rimu source Rendered HTML
``
Nunc mauris tempor.
Scelerisque feugiat massa alias.
``
Nunc mauris tempor.
Scelerisque feugiat massa alias.

Quote Block

A Quote Block renders the enclosed block elements inside an HTML <blockquote> element. The Quote Block delimiter character is a double-quote.

Examples

Rimu source Rendered HTML
""
Nunc mauris tempor.
Scelerisque feugiat massa alias.

.cite
Anonymous
""

Nunc mauris tempor. Scelerisque feugiat massa alias.

Anonymous

This example uses the rimuc command --styled option's CSS cite class to style the Anonymous attribution.

Division Block

A Division Block is a container for block elements.

Examples

Rimu source Rendered HTML
."font-style:italic"
..
Nunc mauris tempor.
Scelerisque feugiat massa alias.
..

Nunc mauris tempor. Scelerisque feugiat massa alias.

Division Blocks are useful for appending arbitrary block elements to list items. They can also be used to conditionally include Rimu source text.

HTML elements

Block and inline HTML elements can be mixed with Rimu markup.

Inline HTML elements

Examples

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

An inline HTML span.

Block HTML elements

Examples

Rimu source
An HTML table block element:

<table class="bordered">
  <tr>
    <td>Montes adipiscing sodales.</td>
    <td>Magna placerat posuere.</td>
  </tr>
  <tr>
    <td>Nulla suspendisse egestas nulla libero sed.</td>
    <td>Wisi ullamcorper eget.</td>
  </tr>
</table>
Rendered HTML

An HTML table block element:

Montes adipiscing sodales. Magna placerat posuere.
Nulla suspendisse egestas nulla libero sed. Wisi ullamcorper eget.

Paragraphs

Paragraph block elements are terminated by a blank line (lines containing only space characters do not terminate a paragraph).

Individual paragraph behavior can be modified with a preceding Block Attributes element. The behavior of all paragraphs can be modified with a Delimited Block Definition (block name paragraph for Normal Paragraph; indented for Indented Paragraph; quote-paragraph for Quote Paragraph).

There are three paragraph types:

Normal paragraph

Normal paragraphs can contain inline elements, the first line must start at the left margin.

You can force line breaks in normal paragraphs by putting a space followed by a backslash character at the end of a line.

Line breaks can be escaped by prefixing the trailing backslash with another backslash character.

Examples

Rimu source Rendered HTML
Nunc mauris tempor.
Scelerisque feugiat massa alias.

Nunc mauris tempor. Scelerisque feugiat massa alias.

Indented paragraph

Indented paragraphs begin with one or more space characters. By default the all text in an Indented Paragraph is rendered verbatim. This behavior can be changed using a preceding Block Attributes element. The generated HTML is enveloped with <pre><code>...</code></pre> tags.

Examples

Rimu source Rendered HTML
  Nunc mauris tempor.
  Scelerisque feugiat massa alias.
Nunc mauris tempor.
Scelerisque feugiat massa alias.

Quote paragraph

Quote paragraphs begin with a > character and are rendered inside an HTML <blockquote> element. Leading > characters are optional for all lines except the first line. Leading > characters can be escaped with a backslash character. In all other respects Quote paragraphs behave the same as Normal paragraphs.

Examples

Rimu source Rendered HTML
> Nunc mauris tempor.
  Scelerisque feugiat massa alias.

Nunc mauris tempor. Scelerisque feugiat massa alias.

Lists

Each list item includes an identifier (ID) that groups items into lists. There are three types of list: Bullet, Numbered and Labeled, each with its own unique set of list IDs.

List item ID                  List type
___________________________________________
-, +, *, **, ***, ****        Bullet list
., .., ..., ....              Numbered list
::, :::, ::::                 Labeled list
___________________________________________

Examples

Rimu source
- Lorem ipsum dolor sit amet dis quisque maecenas in tristique arcu
\- lorem dolor fusce nec.
  * Sit pretium quisque in wisi lobortis.
  * Ac curabitur elementum.
    ** Platea ad diam arcu vitae fermentum.
       1. Eu lorem nulla.
       2. In suspendisse at dapibus nostra est.
          .. Montes adipiscing sodales.
    ** Pellentesque nibh sit.
- Viverra pede turpis.
  Esse et dui:: Nonummy modi.
  Wisi ad diam:: Sapien porttitor.
    Condimentum::: Lacus maecenas neque dolor habitant tellus.
- Augue et dui malesuada purus.

  Purus aliquam mauris a aliquam orci. Massa sit sit.
  penatibus. Maecenas at tellus. Sapien quam mauris.
  Non a pede in.

- Facilisi vestibulum montes quam eget donec.
..
Cras proin molestie quam sem conubia. Ligula vel elit. Elit a earum.
Arcu eget magna. Class vivamus morbi.

Ac lacinia mi. Mi in enim. Dui sed ut. Egestas congue quam. Facilisis
non magnis facilisi scelerisque luctus. Quis praesent pulvinar.
..
- Integer quisque hendrerit. Arcu nunc lorem posuere.

> Egestas congue quam.
Rendered HTML
  • 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.
  • Viverra pede turpis.
    Esse et dui
    Nonummy modi.
    Wisi ad diam
    Sapien porttitor.
    Condimentum
    Lacus maecenas neque dolor habitant tellus.
  • Augue et dui malesuada purus.
    Purus aliquam mauris a aliquam orci. Massa sit sit.
    penatibus. Maecenas at tellus. Sapien quam mauris.
    Non a pede in.
  • Facilisi vestibulum montes quam eget donec.

    Cras proin molestie quam sem conubia. Ligula vel elit. Elit a earum. Arcu eget magna. Class vivamus morbi.

    Ac lacinia mi. Mi in enim. Dui sed ut. Egestas congue quam. Facilisis non magnis facilisi scelerisque luctus. Quis praesent pulvinar.

  • Integer quisque hendrerit. Arcu nunc lorem posuere.

    Egestas congue quam.

Quotes

Text can be formatted by enclosing it in one or two quote characters. The built-in quotes are:

Rimu            Rendered HTML             Font style
___________________________________________________________
_emphasis_      <em>emphasis</em>         Italic
*emphasis*      <em>emphasis</em>         Italic
__strong__      <strong>strong</strong>   Bold
**strong**      <strong>strong</strong>   Bold
`code`          <code>code</code>         Monospaced
``code``        <code>code</code>         Monospaced
~~deleted~~     <del>deleted</del>        Strikethrough
___________________________________________________________

Examples

Rimu source Rendered HTML
Some **bold text**,
some _emphasized text_,
some `monospaced text` and
some ~~deleted text~~.

Some bold text, some emphasized text, some monospaced text and some deleted text.

Quote Definition

You can modify existing quote behavior or add new quotes using Quote definitions.

Definition syntax:

quote-delimiter = '<open-tags>|<close-tags>'

The following quote definition envelopes quoted text with an HTML superscript tag:

^ = '<sup>|</sup>'

Replacements

A Replacement replaces matched source text with some other text (usually HTML markup). A replacement is defined by a regular expression (to find the matched text) and the text to be replaced.

With the exception of Quotes all Rimu Inline elements are implemented as replacements e.g. character entities, URLs, inline images, inline HTML tags.

Replacement Definition

Definition syntax:

/pattern/flags = 'replacement'

Example replacement definitions:

/\.{3}/ = '&hellip;'
/\bTODO\b/ = '<b style="color: red; background-color: yellow;">TODO</b>'

URLs

URLs and email address elements are implemented with built-in Replacements.

Syntax:

Rimu                Rendered HTML
______________________________________________________
url                 <a href="url">url</a>       Note 1
<url>               <a href="url">url</a>
<url|caption>       <a href="url">caption</a>
[caption](url)      <a href="url">caption</a>   Note 2
<email>             <a href="mailto:email">email</a>
<email|caption>     <a href="mailto:email">caption</a>
______________________________________________________

Notes:

  1. Only HTTP and HTTPS raw URLs are auto-encoded.
  2. The [caption](url) syntax is Markdown compatible.

Examples

Rimu source Rendered HTML
1. http://example.com
2. <http://example.com>
3. <http://example.com|Foo home>
4. [Foo home](http://example.com)
5. <example.html>
6. <example.html#basics|The basics>
7. <#api-options|API Options>
8. <file:///example/user-guide.pdf|User Guide>
9. <file:///home/example/downloads/>
10. <ftp://example.com/pub/standards/RFC/rfc959.txt>
11. <joe@example.com>
12. <joe@example.org|Joe Bloggs>

Images

Syntax:

Rimu                Rendered HTML
_______________________________________________________
<image:url|alt>     <img href="url" alt="alt">
<image:url>         <img href="url" alt="url">
![alt](url)         <img href="url" alt="alt">   Note 1
_______________________________________________________

Notes:

  1. The ![alt](url) syntax is Markdown compatible. To maintain Markdown compatibility it is always processed as an inline element.

Examples

Rimu source Rendered HTML
An image can be rendered as a block element:

<image:http://www.w3.org/Icons/w3c_home.png|W3C logo>

Centered using [rimuc](#rimuc-command) `--styled` option CSS class:

.align-center
![W3C logo](http://www.w3.org/Icons/w3c_home.png)

Or an image can be <image:http://www.w3.org/Icons/w3c_home.png> an
inline element.

An image can be rendered as a block element:

W3C logo

Centered using rimuc --styled option CSS class:

W3C logo

Or an image can be http://www.w3.org/Icons/w3c_home.png an inline element.

Character entities

HTML character entities can be included in Rimu source.

Examples

Rimu source Rendered HTML
&copy; &reg; &alpha; &omega;

© ® α ω

Character entities can be escaped with a backslash character prefix.

Block Attributes

The Block Attributes Line Block element injects HTML attributes into the opening tag of the next block element. You can specify class names, an element ID and any other HTML attributes. It can also include block-options to control the processing of Delimited Block elements.

Syntax:

.class-names #id "css-properties" [html-attributes] block-options

Examples

Rimu source
.error "color:red"
Lorum ipsum.

.#ref2 "color:green" [title="Reference two"]
Ac curabitur elementum.

{quote-style} = '."padding-left: 10px; border-left: 4px solid silver;"'

{quote-style}
""
Lorem ipsum dolor sit amet sapien. Nascetur et mattis maecenas morbi
porttitor. Vitae vestibulum voluptate. Quam elit id. In eu wisi.
Imperdiet pellentesque minim. Metus mauris tortor. Torquent leo vel.
""

.-macros
Macro {invocations} are not expanded when the `-macros` block option
is set.
Rendered HTML

Lorum ipsum.

Ac curabitur elementum.

Lorem ipsum dolor sit amet sapien. Nascetur et mattis maecenas morbi porttitor. Vitae vestibulum voluptate. Quam elit id. In eu wisi. Imperdiet pellentesque minim. Metus mauris tortor. Torquent leo vel.

Macro {invocations} are not expanded when the -macros block option is set.

Delimited Block Definition

You can change Delimited Block behaviour with Delimited Block definitions.

Definition syntax:

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

The following example generates Code blocks with a no-highlight class attribute:

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

The following example disables Macro Invocation, Quote and Replacement processing in Paragraphs:

|paragraph| = '-macros -spans'

Macros

Macros are a simple yet powerful mechanism for creating shortcuts for repeatedly used markup. They are used to parametrize documents, promote clarity and eliminate repetition.

Rimu provides elements for defining and invoking macros and includes features like macro parametrization, conditional processing and meta-programming.

Macro definitions

A macro definition assigns one or more lines of Rimu markup to a macro name.

Definition syntax:

{macro-name} = 'macro-value'      Simple macro definition
{macro-name?} = 'macro-value'     Existential macro definition

Macro invocations

Invocation syntax:

{macro-name}                      Simple macro invocation
{macro-name|[param1|param2...]}   Parametrized macro invocation
{macro-name=pattern}              Inclusion macro invocation
{macro-name!pattern}              Exclusion macro invocation

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

Macro expansion

Reserved macros

Macros with names starting with two hyphen characters are Reserved macros, a number of reserved macros are defined by the rimuc command.

Vim syntax file

The Rimu distribution includes a syntax highlighter for the Vim editor. Copy rimu.vim to your $HOME/.vim/syntax directory and then use the Vim :set syn=rimu command or put this line in your $HOME/.vimrc file to enable Rimu syntax highlighting:

autocmd BufRead,BufNewFile *.rmu setlocal filetype=rimu

The syntax file also sets Vim text formatting options, if they're not to your taste delete them from the end of the file.

Other