# Markdown Extensions Matrix
MD.Viewer ships its own renderer: a set of regular-expression passes plus a block-level
state machine in `renderMarkdown()`. It is **not** a CommonMark or GFM implementation, and
it does not claim conformance. This page is the measured reference — every row was produced
by feeding the input to a running viewer and inspecting the HTML that came back.
Use it to decide what you can safely write. Where a row says "divergent", the renderer
produces output that a CommonMark-conformant reader would not.
## Contents
- [How to read this matrix](#how-to-read-this-matrix)
- [Support summary](#support-summary)
- [Block elements](#block-elements)
- [Inline elements](#inline-elements)
- [Links, images and references](#links-images-and-references)
- [MD.Viewer extensions](#mdviewer-extensions)
- [Known divergences from CommonMark](#known-divergences-from-commonmark)
- [Not supported](#not-supported)
- [Raw HTML](#raw-html)
- [Escaping and sanitisation behaviour](#escaping-and-sanitisation-behaviour)
- [Authoring rules of thumb](#authoring-rules-of-thumb)
- [See also](#see-also)
---
## How to read this matrix
Each entry shows the Markdown you type, the HTML the viewer emits (classes abbreviated for
readability), and the toggle that governs it. "Governed by `—`" means always on.
The renderer works in two phases. Block structure is handled by a line-scanning state
machine in `renderMarkdown()`; inline content then passes through `inlineMarkdown()`,
which protects code spans, images and raw HTML with private-use-area placeholder code
points, escapes everything else with `htmlspecialchars(ENT_QUOTES | ENT_SUBSTITUTE)`,
applies the inline passes, and restores the placeholders.
| Code point | Holds | Escaped when restored? |
|---|---|---|
| `U+FFFC` | inline code span | yes, via `e()` |
| `U+FFFD` | generated `` | n/a — built with escaped attributes |
| `U+FFFE` | **raw HTML tag** | **no — verbatim** |
| `U+FFF9` | `_ * ~` masked inside link URLs | n/a — re-inserted literally |
---
## Support summary
| Area | Status |
|---|---|
| ATX headings, paragraphs, emphasis, code spans, blockquotes, thematic breaks | Supported |
| Fenced code with backticks, including length-aware nesting | Supported |
| Tables with alignment | Supported (GFM-style) |
| Task lists | Supported (GFM-style) |
| Footnotes, reference links | Supported |
| Heading numbering, TOC, source citations, glossary tooltips, universal patterns, emoji | MD.Viewer extensions |
| Nested lists | **Not supported** |
| Indented (4-space) code blocks | **Not supported** |
| Tilde fences `~~~` | **Not supported** by the body renderer |
| Autolinks (bare URLs, ``) | **Not supported** |
| Backslash escapes | **Not supported** |
| HTML entity / numeric character references | **Divergent** — escaped, not decoded |
| Setext headings | **Divergent** — text is emitted twice |
| Raw HTML | **Passed through unescaped** — see [[Security Hardening Guide]] |
---
## Block elements
### ATX headings
```markdown
# Level one
## Level two
### Level three
#### Level four
##### Level five
###### Level six
```
```html
1.Level one
1.Level two
```
- Slugs are generated by `slugify()`; duplicates are deduped with a `-2`, `-3` suffix.
- Levels map to distinct class sets via `getHeadingClasses()`.
- Governed by `AUTO_NUMBERING` for the numeric prefix.
> [!NOTE]
> In viewer mode the document's **first H1 is removed from the body** and re-rendered by the
> page template as the hero title. Numbering therefore starts at the remaining headings.
> See [[Authoring Guide]].
### Paragraphs and line breaks
```markdown
First paragraph.
Second paragraph.
```
```html
First paragraph.
Second paragraph.
```
Governed by `DOUBLE_LINE_BREAKS` and `PARAGRAPH_BREAK_STYLE`
(`double-br` | `single-space` | `margin`).
### Blockquotes
```markdown
> Quoted line one
> Quoted line two
>
> Second paragraph in the quote
```
```html
Quoted line one Quoted line two
Second paragraph in the quote
```
Soft line breaks inside a quote become ` `. Every blockquote gets a copy control.
> [!NOTE]
> Lazy continuation lines (`> line1` followed by an unquoted `line2`) are merged into the
> same paragraph rather than ending the quote.
### Fenced code blocks
````markdown
```php
PHP
<?php echo "hi";
```
- The info string becomes both a visible uppercase language label and a
`language-` class.
- Content is HTML-escaped.
- **Length-aware fencing works correctly**: a four-backtick fence wrapping a three-backtick
fence renders as a single block containing the inner fence literally.
- Every code block gets a copy control.
> [!WARNING]
> **No syntax highlighting is applied.** The repository loads no highlighter — a
> repo-wide search for external asset URLs finds only Tailwind, Google Fonts and Mermaid.
> Code is styled by `css/md/md.css` as monospace on a dark slab. The upstream README
> mentions "syntax highlighting" among its CDN requirements; that is inaccurate and this
> wiki does not repeat it.
> [!CAUTION]
> **Tilde fences are not rendered as code blocks.** `~~~js … ~~~` appears as literal
> paragraph text. The fence-stripping helpers accept `` ` `` and `~`, but the body renderer
> did not produce a code block for tildes in testing. **Always use backticks.**
### Tables
```markdown
| Left | Center | Right |
|:-----|:------:|------:|
| a | b | c |
```
```html
Left
Center
Right
a
b
c
```
- `:---`, `:---:`, `---:` produce `text-left`, `text-center`, `text-right` on both header
and body cells.
- The alignment separator row is optional in the source — a two-line table still renders.
- Cells in the first column carry `data-gc="1"`; other cells carry an
`id="gd-tbl-N-row-col"` used by the glossary tooltip engine.
- Leading and trailing pipes are optional in the parser (`parseTableRow()` strips them).
> [!IMPORTANT]
> **Any table whose first column has a non-empty header is treated as a glossary.** Its
> first-column values become tooltip terms matched across the whole document. A table of
> short or numeric values will therefore produce surprising tooltips elsewhere. See
> [[Authoring Guide]] for how to control this.
### Task lists
```markdown
- [ ] open item
- [x] closed item
```
```html
open item
closed item
```
Governed by `FEATURE_TASK_LISTS`. Completed items get `checked disabled` and a `task-done`
class. Checkboxes are never interactive — this is a reader, not an editor.
### Lists
```markdown
1. one
2. two
- bullet a
- bullet b
```
```html
one
two
bullet a
bullet b
```
An ordered list's first number is preserved as `start` and each item carries `value`.
> [!CAUTION]
> **Nested lists do not work.** Indented children are not parsed as sublists:
>
> ```markdown
> - top
> - child
> ```
>
> renders as `
top
` followed by a **paragraph containing the literal text**
> `- child`. Four-space indentation fares no better — the child becomes a stray `
`.
> The upstream README lists "nested lists" as supported; testing contradicts this.
> **Flatten your lists**, or express hierarchy with headings and tables.
### Thematic breaks
```markdown
---
***
___
```
```html
```
All three characters work.
### Mermaid diagrams
````markdown
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|yes| C[OK]
```
````
```html
MERMAID
graph TD
A[Start] --> B{Decision}
B -->|yes| C[OK]
```
PHP emits the **source** in a `
`. `js/md/md.js` then, only if at least
one such element exists, dynamically imports Mermaid 11 from
`https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs` and runs it. Info strings
`mermaid` and `mmd` are both recognised.
Client-side behaviour worth knowing:
- An **auto-repair** pass normalises common authoring mistakes before parsing:
PlantUML-style class notes, literal `\n`, unclosed ` `, PlantUML `return`, unquoted
parentheses.
- Diagnostics are **English-only** and written to the console.
- On a parse failure the element gets `mermaid-error` and `data-mermaid-error="true"`.
- The original source is preserved in `data-mermaid-source`, and the copy control returns
that source rather than the rendered SVG.
- Mermaid is initialised with `securityLevel: 'loose'` and `htmlLabels: true`.
> [!WARNING]
> `securityLevel: 'loose'` permits HTML inside diagram labels and enables click callbacks.
> For untrusted diagram source this is an additional script-capable surface on top of the
> raw-HTML issue. See [[Security Hardening Guide]].
---
## Inline elements
| Input | Output | Toggle |
|---|---|---|
| `**bold**` | `bold` | — |
| `__bold__` | `bold` | — |
| `*italic*` | `italic` | — |
| `_italic_` | `italic` | — |
| `~~strike~~` | `strike` | — |
| `==highlight==` | `highlight` | — (not CommonMark or GFM) |
| `H~2~O` | `H2O` | `FEATURE_SUBSUP` |
| `x^2^` | `x2` | `FEATURE_SUBSUP` |
| `` `code` `` | `code` | — |
| `:rocket:` | 🚀 | `FEATURE_EMOJI` |
Inline code is click-to-copy: the `copy-on-click` class is served by one delegated handler
in `js/md/md.js`.
### Emoji shortcodes
The complete supported set — sixteen entries, no others:
| Shortcode | | Shortcode | | Shortcode | | Shortcode | |
|---|---|---|---|---|---|---|---|
| `:smile:` | 😊 | `:laughing:` | 😆 | `:joy:` | 😂 | `:heart:` | ❤️ |
| `:thumbsup:` | 👍 | `:thumbsdown:` | 👎 | `:warning:` | ⚠️ | `:error:` | ❌ |
| `:check:` | ✅ | `:x:` | ❌ | `:star:` | ⭐ | `:fire:` | 🔥 |
| `:bulb:` | 💡 | `:rocket:` | 🚀 | `:link:` | 🔗 | `:info:` | ℹ️ |
Any other `:shortcode:` is left as literal text.
> [!TIP]
> Because the map is small and fixed, prefer the literal emoji character in your source for
> anything outside this list. It renders identically and does not depend on a toggle.
---
## Links, images and references
### Inline links
```markdown
[Example](https://example.com)
[Anchor](#a-heading)
[Relative](docs/other.md)
```
```html
ExampleAnchor
```
- Absolute `http(s)` links open in a new tab with `rel="noopener noreferrer"`.
- Anchors and relative paths render without `target`.
- `_`, `*` and `~` inside a URL are masked during emphasis processing and restored
afterwards, so URLs containing underscores survive intact.
> [!NOTE]
> `[click](javascript:alert(1))`, `[click](data:text/html,…)` and URL-encoded variants are
> **not** turned into links — the inline-link passes only match `#…` or `https?://…`, so
> such input stays literal text. Reference-style links are the exception; see below.
### Reference-style links
```markdown
See [the specification][spec] and [Example][ex].
[spec]: https://spec.commonmark.org/
[ex]: https://example.org "Example Title"
```
```html
Example
```
Governed by `FEATURE_REF_LINKS`. Keys are matched case-insensitively; an empty key
(`[text][]`) falls back to the text itself. Definitions are removed from the rendered body
by `removeReferenceLinkDefinitions()`. An unresolved reference renders as a greyed span:
```html
[text]
```
> [!CAUTION]
> **Reference-link URLs are not protocol-filtered.** A definition of
> `[r]: javascript:alert(1)` produces ``. The URL is escaped
> for attribute context but the scheme is never checked. This is a real XSS vector in
> documents an untrusted party can author — see [[Security Hardening Guide]].
### Images
```markdown
```
```html
Image: Badge
```
Governed by `FEATURE_IMAGES`. Images are extracted **before** the escape pass so that a
linked badge `[](url)` is not double-wrapped in an anchor — a documented v2.2.4
fix. Consequences:
- All images are lazy-loaded and decoded asynchronously.
- A failed load hides the `` and reveals a fallback caption built from the alt text.
- Images are `inline-block`, so a row of badges flows on one line without ` ` between
them.
- `src`, `alt` and `title` are attribute-escaped, so `![x](y.png" onerror="alert(1))`
cannot break out of the attribute — it renders as literal text.
### Footnotes
```markdown
Text with a footnote[^note1].
[^note1]: This is the footnote body.
```
```html
```
Governed by `FEATURE_FOOTNOTES`. The reference carries a `title` with the first 100
characters of the note (tags stripped), and the closing section provides a backlink.
Definitions are removed from the body by `removeFootnoteDefinitions()`.
---
## MD.Viewer extensions
These have no CommonMark or GFM equivalent.
### Automatic heading numbering
`AUTO_NUMBERING` prefixes each heading with a hierarchical number rendered in a muted
monospace span, in both the body and the TOC:
```html
1.2.
```
`hasManualNumbering()` detects a number the author already wrote and suppresses the
automatic prefix for that heading, so numbering is never duplicated. Recognised manual
forms include `1. Title`, `2) Title`, `3: Title`, `2 Title`, `1.1 Subsection`,
`10.2.3. Deep`, `I. Intro`, `XIV. Chapter`. Explicitly **not** recognised: `2024 year`,
`101 Title`, `3D`, `5G`, `4K`, `№1 Title`, `Chapter 1`, or a bare ambiguous Roman letter
such as `M Title`.
### Automatic table of contents
`AUTO_TOC` renders a `
Image: Badge ``` Governed by `FEATURE_IMAGES`. Images are extracted **before** the escape pass so that a linked badge `[](url)` is not double-wrapped in an anchor — a documented v2.2.4 fix. Consequences: - All images are lazy-loaded and decoded asynchronously. - A failed load hides the `