Project Manual
Contents

Supported Formatting

On this page

Simple Docs intentionally supports a small Markdown subset. These examples show the formatting produced by the generator.

Page Titles and Headings#

Every page must start on its first line with exactly one H1:

# Page Title

Use H2-H6 for sections within the page. Generated headings receive stable IDs and a # permalink.

Pages with at least one H2 (##) heading also get an “On this page” list of their H2 sections. It stays on the right while scrolling on wide screens and becomes a collapsible list below the page title on smaller screens. These links work without JavaScript, including in the extracted offline ZIP. H3-H6 headings keep their permalinks but are not included in this list.

The article stays centered with the same width on pages with or without this list. Narrower screens use one centered column with collapsible navigation.

IDs are unique within each page. Collisions with other headings or layout IDs receive an unused suffix; the search-result ID prefix is reserved. Use the rendered permalink when linking to a heading whose name collides.

Inline Text#

A paragraph may contain bold text, emphasized text, and inline code. Raw HTML is escaped instead of inserted into the page.

Lists and Quotes#

Lists must be flat. Both unordered and ordered lists are supported:

  • First unordered item.
  • Second unordered item.
  1. First ordered item.
  2. Second ordered item.

Consecutive quoted lines render as one flat block quote.

Use source-relative paths. Link to pages by their Markdown filenames and keep local images under the current language's images/, such as manual/en/images/:

[Commands](01-commands.md)
![Diagram](../images/manual-flow.svg)

The generator rewrites these paths for hosted sites and offline ZIPs.

Destinations may contain balanced parentheses or backslash-escaped parentheses. HTTP and HTTPS links require a host and a valid port when one is supplied. Percent-encode whitespace in HTTP and HTTPS destinations, for example %20. Local image query strings, such as ?v=2, are preserved in both output modes. Local page paths are validated, but fragment targets are not checked.

Code Blocks#

Use three backticks with an optional language. Whitespace is preserved and long lines scroll horizontally.

python3 build.py --theme paper

The language adds a class such as language-sh; syntax highlighting is not applied automatically.

Code block text is searchable under its containing page or heading, alongside prose. Search supports IME text composition and announces loading, result counts, no matches, and errors to assistive technology.

Mermaid Diagrams#

Label a triple-backtick code fence mermaid to write a diagram. Default builds show its source as escaped code, just like other code blocks, without requiring any additional tools. Enable build-time rendering with --mermaid or Make's MERMAID=1 to replace it with a static SVG image.

The example below follows the documentation workflow: write Markdown, build the site, and publish the generated files for readers.

Documentation workflow Authors write Markdown, build the site, and publish static files for readers.
Open diagram

This is a real diagram block, so the bundled manual renders it when Mermaid is enabled and displays readable source by default. Diagram source stays searchable in either mode.

Wide diagrams keep their rendered size so labels stay readable on small screens. Scroll within the diagram panel, or focus it with the keyboard and use the arrow keys. The page itself does not need to scroll horizontally.

Use “Open diagram” below a panel to view the standalone SVG in the current tab, with the full browser window available. Use the browser's Back command to return to the page. The link and scrolling work without JavaScript, including in the offline ZIP. When JavaScript is available, a short horizontal-scroll hint appears only when the diagram overflows its panel and updates when the window changes. Tall diagrams expand the page normally rather than adding a vertical scroll box.

Use accTitle and accDescr to describe the diagram. The generator combines the resulting SVG title and description as image alt text, falling back to the page title if neither is present. Always include a readable nearby explanation of the relationships or steps; a diagram should not be the only explanation.

The selected --theme or Make THEME automatically supplies diagram colors when rendering is enabled, without adding dependencies. For example, use the optional container toolchain to build with Paper:

make bundle-container THEME=paper MERMAID=1

The panel and SVG share the same concrete background. Diagram text uses JetBrains Mono Regular at 14px. The renderer loads the font before measuring labels and embeds the full bundled WOFF2 font and its OFL license inside every SVG. English and Polish use the same font; offline images need no font downloads. Embedding adds approximately 128 KB per SVG before compression, or 96 KB in the ZIP, compared with generic-font diagrams. No font subsetting is performed.

All 13 bundled themes use one shared color mapping. Custom themes with an unsupported or incomplete palette fall back as a whole to neutral diagrams on white, with one stderr message per build rather than a failure. See Mermaid diagram colors for the palette contract. Rebuild after theme changes to update diagram colors; runtime CSS changes do not recolor the static SVGs.

For custom flowchart colors, consult the theme's named authoring color reference and the tested element styling example. Use literal colors in classDef, style, or linkStyle; ordinary static color overrides are distinct from the forbidden global configuration directives.

The initial static subset covers simple flowcharts and sequence diagrams. Mermaid's full feature set is not guaranteed. The renderer controls configuration:

  • Do not add Mermaid YAML frontmatter or configuration directives such as

%%{init: ...}%%.

  • Use plain text labels. HTML labels and math that needs HTML output are not

supported.

  • Do not depend on external images, fonts, styles, links, or other resources in

the SVG. Only the builder's exact embedded font rule is permitted alongside local SVG fragment references; author-supplied embedded resources are rejected.

  • Scripts, event handlers, and animation are not supported.

Both hosted sites and offline ZIPs contain the generated SVG images, with no runtime Mermaid JavaScript or network dependency. Images are written under <language>/_diagrams/<hash>.svg in the output. The hash includes diagram source and render configuration, plus the font, license, and renderer helper. Changes receive different filenames to avoid stale colors or typography. Hosted and offline output reuse the rendered SVGs; source directories are never modified.

Rendering reads the diagram palette and looks up mmdc on PATH only when an enabled build encounters a Mermaid fence. A missing renderer causes no error when rendering is disabled or there are no diagrams. With rendering enabled, missing tools, invalid diagrams, and rejected SVG content fail with the source path and fence line before previous outputs are replaced.

Use the recommended optional Mermaid container or an installed host renderer.

Unsupported Syntax#

Nested lists, tables, task lists, footnotes, reference links, raw HTML, and other Markdown extensions are not supported. Unsupported syntax usually renders as escaped text rather than enhanced HTML.