Markdown Subset

Supported block elements

Element	Syntax
Headings	`##` through `######` (H2–H6). H1 is the page title from frontmatter.
Paragraphs	Plain text separated by blank lines
Blockquotes	`> quoted text`
Fenced code blocks	``` with language identifier
Ordered lists	`1. item`
Unordered lists	`- item`
Task lists	`- [x] done` / `- [ ] todo`
Tables	GFM pipe tables
Horizontal rules	`---`
Callouts	`> [!TYPE]` (NOTE, TIP, WARNING, DANGER, IMPORTANT)
Mermaid diagrams	Fenced `mermaid` code blocks or `::: mermaid` containers

Supported inline elements

Element	Syntax	Result
Bold	`text`	text
Italic	`text`	text
Strikethrough	`~~text~~`	~~text~~
Inline code	`code`	`code`
Links	`[text](url)`	linked text
Images	`![alt](url)`	rendered image

Callout types

Type	Purpose	Icon
`NOTE`	Informational context	Info
`TIP`	Helpful advice	Star
`WARNING`	Potential issues	Warning triangle
`DANGER`	Destructive or irreversible actions	Error
`IMPORTANT`	Key information not to be overlooked	Star

Syntax:

> [!WARNING]
> This action cannot be undone.

Sanctioned HTML tags

These HTML tags are allowed within Markdown content and will not be stripped by the sanitization pipeline:

Tag	Purpose
`<details>`	Collapsible section wrapper
`<summary>`	Collapsible section title
`<kbd>`	Keyboard shortcut display
`<sub>`	Subscript text
`<sup>`	Superscript text

Code block languages

Syntax highlighting is supported for these languages (via Shiki):

typescript, javascript, bash, shell, json, yaml, bicep, css, html, markdown, powershell, python, sql, xml, csharp, go, rust, java, dockerfile

Mermaid code blocks render as expandable diagram figures in the reader. Authors can use either fenced mermaid blocks or ::: mermaid containers; the build normalizes containers to fenced blocks before rendering.

flowchart LR
 source[Markdown source] --> server[Server Markdown pipeline]
 server --> sanitized[Sanitized HTML]
 sanitized --> renderer[MarkdownRenderer]
 renderer --> preview[PNG preview when canvas conversion is available]
 renderer --> fallback[SVG fallback]
 preview --> dialog[Expandable full-size dialog]
 fallback --> dialog

Rendering behavior:

Step	What happens
Server Markdown parse	The page body is parsed, sanitized, and emitted as HTML.
Client enhancement	`MarkdownRenderer` finds Mermaid code blocks after hydration.
Diagram render	Mermaid produces SVG in the browser.
Preview display	The reader inserts the SVG inline so HTML labels and line breaks render reliably.
Fallback	If Mermaid cannot parse a diagram, the source block remains visible for troubleshooting.
Expand	Clicking the preview opens a dialog with the full rendered diagram and a source disclosure.

Use the page width control to switch to Wide view for large diagrams, tables, and code blocks. Wide view collapses the left navigation and right table of contents while keeping prose readable.

flowchart LR
 source[Markdown source] --> render[Reader renderer]
 render --> preview[PNG preview]
 preview --> expand[Expanded diagram]

See Mermaid Gallery for visual smoke-test examples of the diagram types supported by the reader.

The reader intentionally smoke-tests common Mermaid families: flowcharts, sequence diagrams, state diagrams, class diagrams, ER diagrams, journeys, Gantt charts, pie charts, mindmaps, timelines, Git graphs, quadrant charts, requirement diagrams, C4 context diagrams, Sankey charts, and XY charts. Mermaid beta diagram families may change syntax between Mermaid releases; keep examples in the gallery when adding one to production content.

Mermaid authoring tips

Prefer flowchart, sequenceDiagram, and stateDiagram-v2 for platform documentation.
Use short node labels and subgraphs to keep diagrams readable in Standard view.
Avoid raw HTML inside Mermaid labels; use plain text separators instead of <br/>.
Put implementation details in nearby tables when a diagram would become too dense.
For call traces, use sequenceDiagram with concrete route names such as /api/GetRoles.

Standard and Wide view

Reader pages have a Standard/Wide page-width control in the article toolbar. Standard view keeps the full three-column documentation layout: left navigation, article, and right table of contents. Wide view collapses the rails and expands media surfaces for diagrams, large tables, and code-heavy runbooks.

Mode	Best for	Layout behavior
Standard	Reading prose, short guides, normal reference pages	Left nav and right TOC remain visible.
Wide	Architecture diagrams, call traces, large tables, long code blocks	Nav/TOC rails collapse and content media can use the wider page.

The user's choice is stored in the browser as hub-docs-wide-view and restored before first paint so pages do not flash between layouts.

Unsupported features

The following features are not supported and will be stripped or ignored:

Feature	Reason
Footnotes	Not in CommonMark; inconsistent rendering
Math / LaTeX	Requires KaTeX/MathJax integration (not planned)
Raw HTML blocks	Security risk; bypass sanitization
Emoji shortcodes	Use actual Unicode emoji instead
Definition lists	Not in CommonMark or GFM
Abbreviations	Limited browser/editor support