Text formatting

This page covers everything you can write in plain text: paragraphs, headers, emphasis, separators, inline code, notes and links.

Normal writing

Just write normally. Lines that follow each other with a blank line between them become separate paragraphs. A single line break inside a paragraph is ignored.

this is normal text

Example:

this is normal text

Headers

Headers go from h1 to h6. h1 is the largest and h6 the smallest.

Note:

The first h1 of an .mmx file becomes the page title shown in the browser tab and in the sidebar.

A header is declared on its own line, just like in Markdown:

# This is a h1
## This is a h2
### This is a h3
#### This is a h4
##### This is a h5
###### This is a h6

Note:

It is strongly recommended to use a single h1 per page (which becomes the title) and as many h2-h6 as you need for the content.

Header tags (anchor links)

You can optionally add a tag to a header so you can link directly to it. The tag goes between %{ and %} after the title.

Note:

Do not add a tag to the first h1 of your page -- the first h1 is already used as the title.

# This is a h1 with a tag %{tag}%
## This is a h2 with a tag %{Anothertag}%
### This is a h3 with a tag %{Anothertag2}%
#### This is a h4 with a tag %{Anothertag3}%
##### This is a h5 with a tag %{Anothertag4}%
###### This is a h6 with a tag %{Anothertag5}%

Linking to a header in the same page:
[Header](#id)

Linking to a header in another page (remember to use .html, not .mmx):
[Header](pages/the/Page/You/Want/To/Go.html#id)

Here are some examples of headers in action.

Bold

Wrap text with two asterisks to make it bold: **Text in bold**.

Example:
This text is in bold

Italic

Wrap text with a single asterisk to make it italic: *Text in italic*.

Example:
This text is in italic

Line breaks

When you are writing normally, line breaks only separate paragraphs. To insert a forced blank line, use the #b element. It must appear on its own line.

#b

Here is an example of 3 #b:

Coloured text

You can colour text with an HTML-style syntax that accepts any CSS colour value: named colours, hex, rgb() or hsl().

<c="color">Text in that color</c>
<c="red">This text will be coloured in red</c>
<c="blue">This text will be coloured in blue</c>
<c="#ffcc40">This text will be coloured in yellow</c>
<c="rgb(130, 130, 130)">This text will be coloured in gray</c>

Examples:

This text will be coloured in red

normal text

This text will be coloured in blue

This text will be coloured in yellow

This text will be coloured in gray

Note:

<c="color"> is shown above as a placeholder, but color is not a valid CSS colour and will be ignored by the browser. Use a real value such as green, #ffcc40 or rgb(130, 130, 130).

Highlighted text

You can highlight text as if you used a marker pen with the <ch> tag. It works like <c> but renders the text with a background colour instead of changing the text colour. It accepts any CSS colour value: named colours, hex, rgb() or hsl().

If you do not specify a colour, it defaults to yellow.

<ch>This text is highlighted in yellow (default)</ch>
<ch="lime">This text is highlighted in lime</ch>
<ch="#ffcc40">This text is highlighted in yellow</ch>
<ch="rgb(255, 150, 150)">This text is highlighted in pink</ch>

Examples:

This text is highlighted in yellow (default) normal text This text is highlighted in lime This text is highlighted in yellow This text is highlighted in pink

Color display

The <colorDisplay="..."/> tag renders a small filled circle next to the literal color value you pass in. It is self-closing (no closing tag) and accepts the same CSS color values as <c="...">: named colors, hex, rgb() or hsl().

The circle and the text sit inline with the surrounding text and scale with the font size, so they line up with normal paragraphs and headings. The whole element is a button: clicking either the circle or the color value copies that value to the clipboard. A green ✓ appears for a second to confirm the copy.

It is useful for documenting a color palette so readers can see the actual color, copy it, and not just read its name.

<colorDisplay="red"/>
<colorDisplay="#ffcc40"/>
<colorDisplay="rgb(130, 130, 130)"/>
<colorDisplay="hsl(200, 80%, 50%)"/>

Examples:

Some text more text

Note:

<colorDisplay="color"> is shown above as a placeholder syntax. color itself is not a valid CSS value and will not be rendered. Always pass a real value such as red, #ffcc40, rgb(130, 130, 130) or hsl(200, 80%, 50%).

Tip:

The click-to-copy behavior uses the browser clipboard API, so it works on pages served over <a target="_blank" href="http://localhost">http://localhost</a> and https://. If a reader opens the generated HTML directly from disk (file://) the modern clipboard API may be blocked, but the script falls back to the legacy document.execCommand('copy') so it still works in that case.

Separators

A horizontal rule is produced with #s on its own line, just like #b.

#s

Example:

Comments

You can leave a comment in any .mmx file using the same syntax as an HTML comment: . The comment is stripped from the source before any MMX pattern runs except the inline code, the raw inline tag or the code block, so the text inside it never appears in the generated HTML and never affects headers, links, lists or any other element.

A comment can sit on its own line, sit on the same line as other content, or span multiple lines. All three forms work the same way.

<!-- this whole line is a comment, it will not appear in the output, but its on a code block so it appears -->

This line is visible.
This line is also fully visible. <!-- Here is a comment -->

<!--
Multi-line comments are also supported.
another line
-->

Some text with a comment at the right <!-- A comment -->

Some text with a comment at the right

Tip:

Use comments to leave notes to yourself (a TODO, a reminder, a draft) or to temporarily disable a section of the page without deleting it. Because the comment is stripped before the rest of the file is compiled, the content inside the comment is not interpreted as MMX: a literal comment marker around **bold** stays exactly as written in the source until you remove the opening and closing delimiters.

Note:

If you need to display the literal text <!-- in the rendered page (for example, in a documentation site that explains HTML comments), wrap it in a :::code ... ::: block, in a #code(path) directive, or in an inline raw tag <code class="inline-raw"> ... </code>. Those constructs keep the content verbatim and are not affected by the comment-stripping step.

Inline code

Wrap text in backticks to render it as inline code. Inline code is not parsed by MMX, uses a monospaced font and has a subtle background.

`code`

Example:

This is some inline code, this is not parsed inside me: [Header](pages/the/Page/You/Want/To/Go.html#id)

Raw inline tag

Like inline code but without formatting

<%write **not bold**, *not italic*, [not a link](https://example.com)%>

Example:

This text is write **not bold**, *not italic*, [not a link](https://example.com).

Tip:

The raw tag is single-line: a newline closes the tag. If you need a multi-line raw block, use a :::code ... ::: block instead.

Raw HTML block

You can insert raw HTML directly into the page with the #html block. The content between #html and ### is rendered as-is, without any escaping or processing by MMX patterns. This is useful when you need to embed custom HTML, interactive elements, or third-party embeds that go beyond what MMX provides.

Unlike :::code ... ::: (which escapes HTML entities for display), the #html block outputs the content as real markup that the browser interprets.

Tip:

Because the content is not parsed by MMX, you cannot use MMX syntax (bold, links, headers, etc.) inside a #html block. Use this block only for raw HTML. For displaying code examples, use :::code ... ::: instead.

Note:

Dont use headers inside this, instead add an style to the html element style="a style" and change the font size

Note:

The default styles of mmx will be aplied to this html

#html
<div style="padding: 1em; background: #f0f8ff; border-left: 4px solid #1E88E5;">
  <div style="margin-top: 0;">Custom HTML block</div>
  <p>This content is rendered <strong>directly</strong> as HTML.</p>
  <ul>
    <li>Lists work natively</li>
    <li><em>Italic</em> and <strong>bold</strong> too</li>
  </ul>
</div>
###

Example:

Custom HTML block

This content is rendered directly as HTML.

Lists work natively
Italic and bold too

Strikethrough

Wrap text with a single tilde to render it as strikethrough: ~Text in strikethrough~.

~This text is in strikethrough~

Example:

~~This text is in strikethrough~~

Underline

Wrap text with two underscores to render it as underlined: __Text underlined__.

__This text is underlined__

Example:

This text is underlined

Subscript

Wrap text in a ... tag to render it as subscript. Subscript text appears smaller and below the normal baseline.

H<sub>2</sub>O
X<sub>i</sub> = 1

Examples:

H₂O is the formula of water.

The variable X_i = 1 represents the i-th element.

Superscript

Wrap text in a ... tag to render it as superscript. Superscript text appears smaller and above the normal baseline.

E = mc<sup>2</sup>
2<sup>10</sup> = 1024

Examples:

According to Einstein, E = mc².

The number 2¹⁰ = 1024 is the smallest 10-bit value.

Note:

Like inline code, ... and ... are parsed by the inline patterns, so you can also nest bold, italic and links inside them.

Notes

A note is a block of text that is rendered with the label "Note:" and a highlighted background. It is a good fit for side information that the reader should keep in mind while reading.

>>>note
This is a note
>>>

Example:

Note:

This is a note

The text inside a note is still parsed, so you can use bold, italic and links.

You can also load the content of a note from a file (see assets/code/note.txt):

Admonitions (Tip, Important, Warning, Caution)

Alongside >>>note there are four more admonition blocks. They follow the exact same syntax and are rendered with a colored background, a colored left border, and a label that describes the kind of information they carry.

The available admonitions are:

>>>tip — a suggestion or best practice (green). Use it for advice that helps the reader get more out of the documentation, but that is not strictly required.
>>>important — a key detail that the reader should not skip (blue). Use it for information that is required to make the rest of the section work.
>>>warning — a risk that is unlikely to cause data loss but can produce unexpected results (orange). Use it when continuing without addressing the warning will probably lead to confusion.
>>>caution — a serious risk that can damage data, break the build or produce incorrect output (red). Use it when the reader must stop and read before continuing.

All of them accept the same syntax as >>>note:

>>>tip
Your tip text
>>>

>>>important
Your important text
>>>

>>>warning
Your warning text
>>>

>>>caution
Your caution text
>>>

Examples:

Tip:

You can use Ctrl + S to save the file at any time.

Important:

The configuration file is read once at build time. Restart the build after editing it.

Warning:

Closing the terminal while the build is running will abort the process and leave temporary files behind.

Caution:

Running clean --all removes the output/ directory. Any file that is not part of the source tree will be deleted permanently.

Like with >>>note, the text inside every admonition is still parsed, so you can use bold, italic and links inside them:

Tip:

Combine >>>tip with a link to the related page to point the reader at more context.

You can also load the content of any admonition from a file using the #code(path) directive. The files used below live in assets/code/:

Tip:

Important:

Warning:

Caution:

Note:

All four admonition blocks share the same base layout as >>>note. They differ only in their background color, left border and label color, so they are safe to mix within the same page.

A side-by-side example of all five admonitions is available at Admonitions example.

Blockquotes

A blockquote is a line that starts with > followed by a space and the quote text. Consecutive > lines are joined into a single blockquote.

> This is a blockquote
> it can span multiple lines
> as long as each line starts with "> "

Example:

This is a blockquote
it can span multiple lines
as long as each line starts with "> "

A blank line starts a new blockquote:

First quote
still the first quote

Second quote, on its own

The text inside a blockquote is still parsed, so bold, italic and links work too:

A quote with bold, italic and a link

Multiline code

The same block that draws notes can also draw code blocks. Code blocks prevent the content from being parsed, so MMX syntax inside them is shown as-is.

The text can come from a file or be written directly in the .mmx file.

Loaded from a file:

Written directly:

#code(assets/code/note.txt)

Both look the same and both accept the following optional classes (separated by spaces):

auto -- enable automatic syntax highlighting (powered by highlight.js).
noMonoSpace -- render the code with a proportional font instead of monospaced.
noCopy -- hide the "copy" button.
noCodeBg -- remove the code background. This also enables noCopy and noFormatted automatically, and disables auto.
noFormatted -- when the code is too long, wrap it to the next line instead of showing a horizontal scrollbar.
noauto -- opt out of automatic syntax highlighting for this block, even when the project sets defaultCodeHighlight = true in its config.mcfg. Use it to keep a single code block plain while the rest of the site uses highlighting.

normal code

code with auto highligthing

this block is not highlighted even when defaultCodeHighlight is true

Project-wide default highlighting

The auto class is per block, so by default you have to add it to every code block you want highlighted. If you would rather highlight every code block in the whole project, set defaultCodeHighlight = true in the project's config.mcfg (the one in your documentation root, not the generator's config.mcfg):

# project's config.mcfg
title = "MMX"
version = "v1.1"
lang = "en"
sidebarBottomText = "Made with MMX"
defaultCodeHighlight = true

When defaultCodeHighlight = true:

Every :::code ... ::: block and every #code(path) directive is highlighted automatically, just as if it had the auto class.
Blocks that already have auto are left untouched (no double-adding).
Blocks that have the noauto class are not highlighted -- use this when a particular snippet should stay plain (e.g. terminal output, ASCII art, a log).
A single #code(path) auto on a block also forces highlighting on even if the project default is false.

Note:

This is a per-project setting, not a per-page one. The flag is read from the project's config.mcfg and applies to every .mmx file in that project.

More examples here.

Links

Use links to point at an external page, another page in your documentation, or a specific header.

Basic syntax:

[External page (it opens in another tab)](https://example.com)
[Documentation page (it opens in this tab)](pages/route/to/page.html)  //do not forget that instead of .mmx here you must put .html
[Header (it scrolls the content to the header)](#headerId)
[Documentation page header (it opens in this tab)](pages/route/to/page.html#headerId)

Examples:

You can also write a bare URL or domain and MMX will turn it into a link automatically:

https://example.com
https://example.com/example
example.com
example.com/example

Examples:

https://example.com https://example.com/example
example.com example.com/example

Anchors (`$[...]` and the `$id` shortcut)

Anchors are reusable bookmarks inside a page. You can define an anchor at any spot in the text and then link to it from anywhere else in the same page (or, for cross-page links, from any other page using the regular [text](page.html#id) syntax). They are useful for building things like a table of contents, a "see also" list at the bottom of a section, or any other situation where you want to jump around inside a long page.

There are two pieces that work together:

$[text](id) -- defines a bookmark at the current position. The text is the visible label (everything between $[ and ]), and the id is the name you can use to link to it (everything between ( and )). The id must contain only letters, digits, dashes and underscores.
$id -- a same-page link to a bookmark. The id becomes both the visible label of the link AND the href target, so $my-anchor is equivalent to writing [my-anchor](#my-anchor). This is a shortcut for the case where you are happy showing the raw id to the reader.

$[this section](my-anchor) is the bookmark.
Click $my-anchor to jump back here.

Example:

this section is a bookmark. Click bookmark-demo to jump back to it.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed mattis accumsan velit. Aenean suscipit sagittis magna, ut consequat nisl. Nunc pulvinar eget eros id rutrum. Nam at ullamcorper augue. Nunc eget est vitae neque posuere eleifend in et justo. Donec consectetur vel neque at mattis.

You can place as many anchors on a page as you need, and you can use the same anchor from as many $id links as you like.

Forward references

The link $id does not have to come after the anchor. The compiler does not verify that the id exists, but the browser will simply jump to the top of the page if it does not find a matching bookmark. Use forward references freely when you want to point the reader at something further down the page:

The full changelog is at the bottom of the page (see $changelog).
...
$[Changelog](changelog)
...

Cross-page anchors

For cross-page links, keep using the regular link syntax with the id appended after a #:

[header on another page](pages/file-sources-and-paths.html#header2)
[the bookmark-demo anchor on this page](pages/Text%20formatting.html#bookmark-demo)

Note:

Cross-page links open in the same tab, just like regular MMX links. The hash is preserved by the build, so the browser scrolls to the matching id and the .resaltado highlight animation plays on the target element (the same animation that runs when you follow a header link).

Text formatting

Normal writing

Headers

Header tags (anchor links)

Bold

Italic

Line breaks

Coloured text

Highlighted text

Color display

Separators

Comments

Inline code

Raw inline tag

Raw HTML block

Strikethrough

Underline

Subscript

Superscript

Notes

Admonitions (Tip, Important, Warning, Caution)

Blockquotes

Multiline code

Project-wide default highlighting

Links

Anchors ($[...] and the $id shortcut)

Forward references

Cross-page anchors

Anchors (`$[...]` and the `$id` shortcut)