MMX Documentation

Welcome! This is a sample documentation site built with MMX, a small, file-based documentation generator. The page you are reading lives in index.mmx and the whole site is generated from .mmx files in the pages/ folder.

What you will find here

The sidebar on the left is the table of contents. The pages are grouped by topic:

• Text formatting -- paragraphs, headers, bold, italic, links, notes, code blocks and everything else you can write in plain text.
• Lists -- unordered, ordered (auto and manual) and nested lists.
• Tables -- vertical, horizontal and both-sides tables.
• File sources and paths -- how to reference local files and remote URLs.
• Multimedia -- images, videos, audios, inline images and iframes.
• Examples -- worked examples of headers and code blocks.

A short tour of MMX

MMX files are plain text. The first line is the page title (a # h1 heading). Everything else is normal text with a few small additions:

• Inline formatting: **bold**, *italic*, inline code , [links](url) and <c="color">coloured text</c>.
• Block elements: # table, ::: note, ::: code, lists, separators, and the #b line break.
• Media elements: ![alt](image.png), !!(video.mp4), !!!(audio.mp3), <-icon.svg-> and #iframe(...).
• Comments: HTML-style <!-- ... --> blocks (single-line, inline, or multi-line) are stripped before the page is compiled, so they are a safe way to leave notes to yourself or to disable a section without deleting it. See the Comments section of the Text formatting page.
• Headers can carry an anchor tag: ## Section %{my-id}% so you can link to it with [Section](page.html#my-id).

You do not need a build step in your editor. Write the .mmx files, run MMX, and you get a static site of HTML files you can open directly or upload to any web host.

How this site is organised

The structure under 1Example/input/ is:

input/
  config.mcfg        -- title, version, language, sidebar text
  index.mmx          -- the page you are reading
  assets/            -- images, videos, audios and code samples
  pages/             -- all the other pages of the documentation
    Examples/
    Multimedia/
    Tests/

Open any page from the sidebar to see how it is written. The source is the single source of truth -- if you spot a typo or want to expand a page, edit the corresponding .mmx file and regenerate the site.

Describing a folder with indexText.mmx

Every folder under pages/ gets an auto-generated index.html listing its children under an Index heading. To add a short description to that landing page, just drop a file called indexText.mmx inside the folder:

pages/
  Multimedia/
    indexText.mmx   <- folder description (not a real page)
    Audios.mmx
    Videos.mmx
    Images.mmx

Anything you write in indexText.mmx (headings, lists, images, code blocks…) is rendered between the folder name and the auto-generated Index list. The file itself is never listed in the sidebar and does not appear in the search index, so it is safe to use as a pure folder blurb. If you want full control over the landing page, write an index.mmx in the folder instead -- that one is rendered normally and the auto-generator steps aside.
Example of a folder with this

Hiding or showing the auto-generated Index

Sometimes you do not want the auto-generated directory list at all -- for instance, when the indexText.mmx already enumerates every page in the folder with friendly descriptions and a second list would be noise. MMX gives you two layers of control over that list:

1. Project-wide default: noDefaultIndex in config.mcfg

Add this line to 1Example/input/config.mcfg:

noDefaultIndex = true

• false (the default) -> every folder shows the auto-generated Index list.
• true -> every folder hides the auto-generated Index list by default. You can still opt individual folders back in (see below).

This is a per-project switch, not a per-folder one, so it is a one-line way to flip the default behaviour for the whole site.

2. Per-folder override in indexText.mmx

The first non-blank line of indexText.mmx may carry a single directive token that overrides the project default for that folder. Two tokens are recognised, case-insensitively:

• #noDefaultIndex -> hide the auto-generated Index list in this folder.
• #defaultIndex -> show the auto-generated Index list in this folder.

The directive is consumed by the build (it is stripped from the content before parsing) and never appears in the rendered page, so you can write it on the very first line without polluting the description.

Resolution rules:

| noDefaultIndex (config) | Directive in indexText.mmx | Result |
| --- | --- | --- |
| false (default) | _none_ | Index shown |
| false (default) | #noDefaultIndex | Index hidden |
| true | _none_ | Index hidden |
| true | #defaultIndex | Index shown |

The per-folder directive always wins. When the index is hidden, the folder landing page contains only the folder name (H1) and the description from indexText.mmx -- no <hr> divider, no <h2>Index</h2>, no list.

Example: project hides the index, except where it helps

A typical setup for a small docs site where the landing descriptions already list every page:

# 1Example/input/config.mcfg
noDefaultIndex = true

# 1Example/input/pages/Multimedia/indexText.mmx
#defaultIndex

## About this folder

This folder is a **reference for every kind of media** you can embed in an
MMX page: regular images, inline icons, audio, video, and iframes.

- **Audios** -- the `!!(path/to/audio)` block directive.
- **Videos** -- the `!!!(path/to/video)` block directive.
- **Images** -- the `![](path/to/image)` block directive.
- **Inline images** -- the `<-path->` inline syntax.
- **Iframes** -- the `#iframe(...)` directive.

In this case the project default hides the index in every folder, and the Multimedia folder opts back in because the author wants both the description and the standard list (e.g. to surface newly added media pages that have not been added to the bullet list yet).

Live example of #defaultIndex in action -- the project config currently uses noDefaultIndex = false, so this folder keeps the index even without the directive, but the directive on the first line is what documents the behaviour here.