Markdown and frontmatter
What the parser supports, and what it deliberately refuses.
The Markdown parser is a Chapel module of about six hundred lines. It emits through MarkupBuilder, which means every text node and attribute value is escaped as it is written — the output is safe by construction before the sanitiser ever sees it.
Frontmatter
---
title: "Markdown and frontmatter"
description: "What the parser supports."
order: 2
published: 2026-02-03
draft: false
---| Key | Type | Default |
|---|---|---|
title | string | The first # heading, else the slugified filename |
description | string | The first 160 characters of plain text |
order | int | 100000, which sorts unordered pages last |
published | ISO date | Empty; rejected unless it is exactly YYYY-MM-DD |
draft | bool | false |
Unknown keys are ignored. A malformed published becomes empty rather than being rendered as whatever the file happened to contain.
Supported blocks
- ATX headings
#through######, each given a slugidand collected into an on-page table of contents - Fenced code blocks with a language tag, highlighted server-side
- Ordered and unordered lists, including nested lists by indentation
- Blockquotes, which are parsed recursively as their own block sequence
- Pipe tables with per-column alignment
- Thematic breaks
- Paragraphs, with lazy continuation
Supported inline syntax
**strong**, *emphasis*, `code`, [links](/with/urls) and backslash escapes. Link targets are passed through a URL policy that permits only https:, http:, mailto:, root-relative paths and fragments — a javascript: target is dropped and the label is rendered as plain text.
Deliberately unsupported
Raw HTML. A <script> in a Markdown file is escaped and rendered as visible text, not passed through. There is no flag to turn that off. The parser has no code path that emits author-supplied markup, which is a stronger guarantee than any filter applied afterwards.
Images. The allow-list contains no img, so an image in a Markdown file renders as its alt text. Illustrations in this site are part of the page chrome, where they are written in Chapel and covered by the same escaping as everything else.
Syntax highlighting
Highlighting happens once, at start-up, in Chapel. The tokeniser understands Chapel, shell, TOML and JSON, and emits <span class="tok-kw"> and friends. The stylesheet maps those classes to colours.
No JavaScript highlighter ships to the browser, which is why a documentation page on this site loads about four kilobytes of script in total — the island runtime, and nothing else.