modgui:documentation can point to an HTML file, and MOD UI opens it in a new tab from the plugin's page. This
repository writes each manual once, in Markdown (docs/manual.md), and builds a single, self-contained page from it
(modgui/manual.html) with a cover, a side navigation, numbered steps, callouts, video cards, collapsible questions, a
dark theme and a print style. This guide is for anyone who wants the same for their plugin.
Contents
- Why a self-contained page
- Files
- Building
manual.json- Writing
manual.md - Pictures for the steps
- Using it from the TTL
- Checking
Why a self-contained page
MOD UI serves the documentation at /effect/file/documentation?uri=<plugin uri>: whatever the page links to with a
relative path (images/x.webp, style.css) is looked up at /effect/file/images/x.webp, which does not exist. So the
builder puts everything inside the one file: the CSS, the JavaScript and every image (as data: URIs; screenshots
over 150 KB are re-encoded as WebP). It also works offline and when the file is attached to an e-mail.
Keep the images small (a 2x screenshot of the plugin is enough) and use WebP for screenshots and drawings: they need
the transparency that JPEG lacks, and WebP is about a fifth of the size of PNG (python3 tools/media/to_webp.py FILE.png;
the tools of tools/media/ already write WebP). A PNG or JPEG over 150 KB is re-encoded by the builder anyway.
Use the animations of making-animations.md only where they tell something: they are the largest part of
the file (a manual is typically 2 to 4 MB). An animation is a pair of files, an animated WebP and a GIF with the same name:
write the .webp in the Markdown, , and when images/x-demo.gif exists the builder
embeds both, as <picture> (the browser plays the WebP; the GIF is for what cannot).
Files
tools/manual/build_manual_html.py the builder
tools/manual/manual.css, manual.js the look and the navigation (shared by every plugin)
plugins/resources/<name>.lv2/docs/manual.md the text (the single source of truth)
plugins/resources/<name>.lv2/docs/manual.json the title, the tagline and the colours of the plugin
plugins/resources/<name>.lv2/docs/images/ the pictures the text uses
plugins/resources/<name>.lv2/modgui/manual.html the result (committed: it is what the device serves)
To use it in another repository, copy tools/manual/ and change RESOURCES at the top of the builder.
Building
pip install markdown pillow # Pillow is only used to shrink big screenshots and to read image sizes
python3 tools/manual/build_manual_html.py tetr4-switch # one plugin
python3 tools/manual/build_manual_html.py all # every bundle that has docs/manual.md
Rebuild in the commit that changes the manual or the interface (screenshots).
manual.json
{
"title": "Tetr4 Switch",
"eyebrow": "MOD Audio · Plugin manual",
"tagline": "Four scenes. One stomp.",
"subtitle": "Programmable CV loop switcher for MOD Dwarf, MOD Duo X and MOD Duo",
"badges": ["4 presets", "4 CV outputs", "16 DIP switches"],
"edition": "User manual · November 2026 edition",
"version": "v1.0.0",
"hero": "images/panel.webp",
"brand": "#0a1380", "brand2": "#02094e",
"accent": "#2b41c4", "accentDark": "#a9b6ff",
"colors": ["#ff6667", "#ffff67", "#66ffff", "#bb7cd2"],
"links": [{"label": "Forum thread", "url": "https://..."}]
}
| Field | Use |
|---|---|
title, tagline, subtitle, badges, eyebrow, edition |
the cover (all optional; the title falls back to the first # of manual.md) |
version |
the version of the plugin the manual was written or updated for (v1.2.5: its TTL's major.minor.micro at that moment), not of the manual. Repeat it in manual.md (the Specifications table, or a last line). build_manual_html.py warns when it differs from the TTL |
hero |
the picture on the cover, relative to docs/ (a 2x screenshot of the plugin; default ../modgui/screenshot.png) |
brand, brand2 |
the cover gradient, and the colour of headings and table headers on the light page |
accent |
links and marks on the light page: dark enough to read on white (contrast 4.5 or more) |
accentDark |
the same on the dark page (it follows the system theme): a light tint of the brand |
colors |
the colours of the plugin (one per preset or channel): the strip under the cover, the headings and the recipe grids |
links |
shown under the side navigation |
output |
where the page is written, relative to the bundle (default modgui/manual.html, which is installed on the device and is what modgui:documentation points to). Use docs/manual.html for a page the TTL does not use yet: docs/ is not installed |
Writing manual.md
Plain Markdown, plus a few conventions that the builder turns into components. The text stays readable on GitHub.
# Titleat the top is the cover. Every## Headingis a section (a card, and an entry of the navigation). A number in front (## 3. The controls) becomes the small03above the title; without it there is none. What comes before the first##is the introduction.- Numbered lists are steps: a numbered circle per item, joined by a line. Use them for procedures only. A picture or a second paragraph inside a step needs care (see A picture inside a step, below).
- Callouts, with GitHub's alert syntax and an optional title:
> [!NOTE] Good to know,[!TIP],[!WARNING],[!IMPORTANT]. A plain>quote is a neutral callout. - Figures: an image alone in a paragraph,
; the alt text is the caption. A picture narrower than 760 px is not stretched (a phone screenshot, an animation); wider ones fill the column; click to enlarge. - Videos:
[](https://youtu.be/ID)(a link to YouTube around a thumbnail; the " — " separates the title from the description) becomes a card with a play button. The same with another address is a card without the button (an example pedalboard, a store page). - Questions: in a section whose title contains Questions or FAQ, every
###heading and what follows it becomes a collapsible question. - Parameter sheets: Markdown definition lists (
TERMon a line,: texton the next) become a tinted sheet with the terms in small capitals. - Tables get a coloured header and zebra rows; the first column is bold. Use
<span class="dot" style="--c:#ff6667"></span>for a colour swatch and<span class="num">1</span>for a small numbered badge. - Recipes and pictures with numbered pins are blocks of their own (see the examples below).
- Links to a section:
[Recipes](#recipes)(the id is the heading in lowercase, with dashes; GitHub's own anchor of a numbered heading,#6-recipes, works too).
Write for someone who has never used the plugin: say what to do before saying how it works, show the result of every step, and put the one thing they must not miss in a callout.
A picture inside a step
A picture or a second paragraph inside a step is indented by four spaces and has a blank line before and after it (with three, or without the blank lines, the list breaks and the next numbers become plain text):
4. **Set the DIP switches.** In Config 1, set all four switches down.

5. **Click the footswitches.** ...
A recipe
A grid of switches and a text, for plugins with switches or steps. A row is a name and one 1 (on, in the colour of that
row) or 0 per column:
```recipe
Four-scene guitar rig
cols: 1 2 3 4
Clean: 0000
Modulation: 0011
---
What the recipe does, in a paragraph.
assign: **Assigning the plugin:** Out 1 → Distortion
```
With more than four columns the cells are smaller, and with more than eight (a sequencer of sixteen steps) the grid is laid out above the text instead of beside it.
A picture with numbered pins
Raw HTML, with the position of each pin in percent of the picture. Describe the numbers in a table with
<span class="num">1</span> in the first cell. Every plugin has one in the section about the plugin on the pedalboard, made from its
panel.webp (Gossiper: gossiper-overview.webp). pins in tools/media/shot-specs.mjs lists a selector for each part, and
node tools/media/shots.mjs <plugin> panel.webp prints the <span class="pin"> lines for it; that is only a starting point: look at
the page and move a pin by hand where it hides the label or the control it points at (a pin is 28 px, 20 px on a phone).
<figure class="annotated">
<div class="stage">
<img src="images/panel.webp" alt="The panel">
<span class="pin" style="--x:24.8%;--y:16.4%">1</span>
</div>
<figcaption>What the numbers mean.</figcaption>
</figure>
A piece of HTML of its own (an animated diagram)
When a diagram is better as live HTML than as a picture, keep it in docs/<file>.html (CSS in a <style>, markup, and a <script>
that serves every copy of it on the page) and put it in with a fenced block at the left margin:
```embed:notification-flow.html
```
The builder inserts the file as it is. Namespace every class (Gossiper's uses nf-), keep its colours in its own variables (it sits on its own dark
stage, so it looks the same in the light and the dark theme), make it work from 320 px to desktop, and respect prefers-reduced-motion (no autoplay;
the chapters are shown at their end). plugins/resources/gossiper.lv2/docs/notification-flow.html is the example. On GitHub's own view of
manual.md it shows as a code block, like the interactive one.
A picture of a pedalboard
A card made of a picture and a link (not a video) sits on the dark, dotted board of the interactive section, so give it a picture with a transparent
background. The MOD pedalboards site serves one: https://api.mod.audio/v2/pedalboards/<id>/screenshot is a PNG with transparency (the /preview of the same
address is a JPEG with a white background: do not use it). Scale it down and convert it to WebP, which keeps the transparency:
python3 tools/media/to_webp.py --width 1600 example-pedalboard.png.
The plugin inside the manual
A manual can also hold one section in which the plugin itself is loaded, to tap and to follow in guided tours: a fenced block
```interactive (empty, at the left margin) plus docs/interactive.json. It is its own guide: interactive-manuals.md.
Pictures for the steps
A step is much easier to follow with a picture of what to tap. tools/media/shots.mjs takes them from the modgui preview
(see making-animations.md for the preview and the finger), so they are reproducible and stay in step with
the interface: when the interface changes, run it again.
node tools/media/shots.mjs all # every picture of every plugin
node tools/media/shots.mjs gossiper # the pictures of one plugin
Each picture is one entry in tools/media/shot-specs.mjs: the plugin is put in the state of the step (setup), the
target gets a ring (highlight), the finger points at it (finger) and the picture is cropped to a panel or to the plugin
(crop). For the settings page, scrollTo brings the page of the pager that holds the target into view. Example:
// Step 6: assign the presets to device footswitches
settings('step-assign-preset-buttons.webp', '[mod-port-symbol="Preset_selector_1"]',
{ highlight: ['[mod-port-symbol="Preset_selector_1"]', '[mod-port-symbol="Preset_selector_2"]'] }),
Pictures are written to docs/images/ of the bundle. Take them for the steps that happen in the plugin's interface;
steps that happen in MOD UI's own dialogs (the pedalboard's CV ports, the assignment dialog) are not in the preview and
need a screenshot of MOD UI itself. Do not redo those: they do not change with your plugin.
Using it from the TTL
modgui:documentation <modgui/manual.html> ;
Raise lv2:microVersion when the manual changes: MOD UI caches the files of a modgui for a year, keyed by the version of
the plugin. Keep docs/manual.md as the source: do not edit manual.html by hand (it says so in its first comment).
The page prints well (A4, the cover on its own, navigation hidden, the questions open). The project does not keep PDF manuals: the HTML is the only built form.
Checking
Open the file in a browser and look at it at three widths (phone 390 px, tablet 820 px, desktop 1440 px), in the light and in the dark theme of the system: the cover, one table, a step list, a callout, a video card and every picture. Pictures must keep their proportions at every width (the cover picture is the usual suspect: it must never be stretched). Open the links: a manual full of dead links is worse than none.