Appearance
CommonMark Compatibility
Generative DOM implements a subset of the CommonMark specification. This page documents the compatibility status and explains deliberate deviations.
Supported Features
The following CommonMark features are implemented by Generative DOM's standard plugins:
| Feature | Status | Plugin |
|---|---|---|
| ATX headings | Supported | markdown-heading |
| Paragraphs | Supported | markdown-base |
| Line breaks (hard) | Supported | markdown-base |
| Thematic breaks (horizontal rules) | Supported | markdown-base |
| Fenced code blocks | Supported | markdown-code |
| Backslash escapes | Supported | markdown-base |
| Emphasis (italic) | Supported | markdown-inline |
| Strong emphasis (bold) | Supported | markdown-inline |
| Inline code | Supported | markdown-inline |
| Links | Supported | markdown-link |
| Images | Supported | markdown-link |
| Autolinks | Supported | markdown-link |
| Blockquotes | Supported | markdown-quote |
| Ordered lists | Supported | markdown-list |
| Unordered lists | Supported | markdown-list |
Unsupported Features
These CommonMark features are not implemented. They are intentional omissions, not bugs:
| Feature | Reason |
|---|---|
| Setext headings | ATX headings cover the same use case. Setext headings complicate streaming because the underline appears on a subsequent line. |
| Indented code blocks | Ambiguous with list continuation. Fenced code blocks are the recommended syntax. |
| HTML blocks | Allowing raw HTML in the output conflicts with Generative DOM's security model (no innerHTML). |
| HTML inline | Same as above. Use custom element plugins for HTML-like syntax. |
| Reference links | Require a two-pass parse (collect definitions, then resolve). Conflicts with single-pass streaming design. |
| Entity references | Generative DOM renders via DOM APIs, which handle entities naturally. Explicit entity parsing is not needed. |
| Tables (GFM) | Not part of CommonMark core. Could be added as a plugin. |
| Footnotes | Not part of CommonMark core. Could be added as a plugin. |
| Task lists (GFM) | Not part of CommonMark core. Could be added as a plugin. |
Spec Test Results
Generative DOM runs the official CommonMark spec test cases from spec.commonmark.org. Tests for unsupported features are marked as skipped with the reason noted.
To run the spec tests:
bash
pnpm test -- --filter specDeliberate Deviations
Some supported features deviate from the spec in minor ways:
Emphasis at Word Boundaries
Generative DOM follows the CommonMark rules for emphasis delimiters but may differ in edge cases involving Unicode word boundaries. The _underscore_ form requires non-word characters at both boundaries.
List Indentation
CommonMark uses a complex algorithm for list item continuation based on the width of the list marker. Generative DOM uses a simpler approach: 2 or 4 spaces (or 1 tab) creates a nesting level.
Lazy Continuation
CommonMark allows lazy continuation of paragraphs inside blockquotes and list items (lines without the > or indentation). Generative DOM supports basic lazy continuation for blockquotes but may not handle all edge cases identically to the spec.
Adding Missing Features
All unsupported features can theoretically be added as plugins. The plugin system does not restrict what syntax can be matched. However, some features (like reference links) require architectural changes to the single-pass streaming model and are unlikely to be added.
If you need a specific CommonMark feature, see Writing Plugins for how to create a custom plugin that implements it.