Almirah ships its own Markdown parser, tuned for specification documents. This page lists what it understands today — and, just as important, what it does not understand yet, so you can author documents that render exactly as intended.
| Element | Syntax | Notes |
|---|---|---|
| Frontmatter | --- title: … --- |
YAML block at the top of the file; sets the document title and metadata |
| Document title | % Title |
Pandoc-style alternative to frontmatter |
| Headings | # … ###### |
Automatically numbered; each heading gets a linkable anchor |
| Paragraphs | plain text | With inline bold, italic, inline code, and links |
| Controlled paragraphs | [REQ-001] text |
The Almirah extension — see Markdown Extension |
| Images |  |
The document-local img/ folder is copied into the build; images open in a zoom overlay on click |
| Unordered lists | - item / * item |
Nesting by indentation is supported |
| Ordered lists | 1. item |
Multi-digit numbering continues correctly |
| Tables | pipe syntax | Grid-table border lines (+---+) are tolerated and ignored |
| Notes | > text |
Rendered as a highlighted note block |
| Code blocks | fenced with ```lang |
Syntax highlighting via Rouge |
| TODO markers | TODO: text |
Rendered as a visible TODO block |
<b> or <span> are escaped and shown as literal text, not interpreted. syntax inside a table renders as literal text; place images in their own paragraph instead.# headings or [ID] paragraphs inside fences — they would show up in the navigation pane or create phantom controlled items.The list of limitations shrinks release by release — if one of them blocks you, open an issue or check whether a newer gem version already lifts it:
$ gem update Almirah