Project Manual
Contents

Supported Formatting

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.

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 manual/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.

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.