# The _construct_ atlas

The construct atlas

Penguin-Flavoured Markdown, one construct at a time.

Every mdsvex document is built from these 36 constructs, in 5 families. Each plate takes a real source and shows what the parser reads in it and what mdsvex makes of it, with the edges where the syntax stops holding and where it parts from CommonMark.

Open the atlas

Reading a score. Each line over the source is one node, from its first character to its last, with a bar where it opens and one where it closes, and its name in the corner. Each row of lines sits on a stave. Quiet unnamed lines are text. Each construct has its own colour. The family headings use a separate set of four colours.

Hover over a phrase or its output to see the match. Click or tap to keep it highlighted, and tap again to clear it. Use the arrow keys to explore a focused score.

block

Heading

One to six #, a space, and the heading text, on one line.

As the parser reads it

# Install

## Step 2 ##
Heading, as the parser reads it, choose a phrase

Compiles to
<h1>Install</h1>
<h2>Step 2 ##</h2>

Edges

  • Trailing # are heading text, so the second heading reads Step 2 ##.
  • A heading is one line: a backslash at its end is a literal backslash, not a break.
  • It ends a paragraph without a blank line before it.

Against CommonMark

ATX only. Setext underlines (===, ---) are gone, and closing # are no longer stripped.

block

Paragraph

Lines of text up to a blank line or a line that starts another block. Single newlines inside it are soft breaks.

As the parser reads it

A paragraph runs
over lines until a blank line.

<Chart />
<Legend />
Paragraph, as the parser reads it, choose a phrase

Compiles to
<p>A paragraph runs
over lines until a blank line.</p>
<Chart />
<Legend />

Edges

  • A paragraph of only tags, components and {@…} tags gets no <p>, so <Chart /> and <Legend /> render bare.
  • Text beside a tag wraps the whole line: <Badge /> new today is one <p>.
  • An image is text by default, so a lone image keeps its <p>; the unwrap_images option changes that.

Against CommonMark

CommonMark wraps any run of inline content in <p>. PFM leaves a paragraph of only tags unwrapped, so Svelte components lay out as written.

block

Block quote

Lines that start with >. It holds the same blocks the document does.

As the parser reads it

> Every line
> has its marker.

> foo
bar
Block quote, as the parser reads it, choose a phrase

Compiles to
<blockquote>
  <p>Every line
  has its marker.</p>
</blockquote>
<blockquote>
  <p>foo</p>
</blockquote>
<p>bar</p>

Edges

  • The first line without a > ends the quote: bar above is a paragraph of its own.
  • Emphasis, a link or a code span still open at a line that starts another block ends there, and its opener is text.
  • A link reference definition inside a quote stays on one line.

Against CommonMark

No lazy continuation. CommonMark carries a paragraph on over unmarked lines; PFM needs the > on every line, so each line is decided on its own.

block

List

Bullet items (-, *, +) or numbered items (1.), each holding blocks indented under its marker.

As the parser reads it

- tight
- items

11. any number

27. you like
List, as the parser reads it, choose a phrase

Compiles to
<ul>
  <li>tight</li>
  <li>items</li>
</ul>
<ol start="11">
  <li>
    <p>any number</p>
  </li>
  <li>
    <p>you like</p>
  </li>
</ol>

Edges

  • Numbers need not be sequential; the first sets the start, so the second list starts at 11.
  • Tight or loose is decided per list. Blank lines between all items make it loose, with a <p> in each; mixed blank lines are loose too.
  • Inside a list item any number ends a paragraph; elsewhere only 1. does. - --- is a thematic break.

Against CommonMark

Tightness is local: a blank line in one list never cascades into another, and non-sequential numbers are allowed.

block

Task item

A list item whose content starts with [ ], [x] or [X], a space, and more text on the line.

As the parser reads it

- [x] parse
- [ ] ship
- [x]done
Task item, as the parser reads it, choose a phrase

Compiles to
<ul>
  <li><input type="checkbox" checked disabled /> parse</li>
  <li><input type="checkbox" disabled /> ship</li>
  <li>[x]done</li>
</ul>

Edges

  • [x]done, with no space, is text, and so is a marker with nothing after it (- [ ]).
  • The rest of the marker's line never opens a block: - [ ] # title is a task with the text # title.
  • In a loose list the checkbox goes inside the first paragraph.

Against CommonMark

Not in CommonMark. As in GFM, a disabled checkbox before the text, in ordered and unordered lists at any depth.

block

Code fence

Lines between a run of three or more backticks and a line of at least as many. The info string after the opener names the language.

As the parser reads it

```md
```js
let x = {1};
```
Code fence, as the parser reads it, choose a phrase

Compiles to
<pre><code class="language-md">```js
let x = &#123;1&#125;;</code></pre>

Edges

  • A fence closes only at a line of nothing but backticks, so the js line above is code inside the md fence.
  • Braces in code are text, escaped in the output.
  • The fence's own indent is not code: an indented fence holds the same code as an unindented one.

Against CommonMark

Fences only. Indented code blocks are removed and indentation is insignificant. There are no tilde fences.

block

Math

Display math is a fence with the language math. Inline math is a code span wrapped in dollars, all on one line.

As the parser reads it

```math
\frac{1}{2}
```

Inline, $`e^{i\pi}`$.
Math, as the parser reads it, choose a phrase

Compiles to with math, Temml
<div class="math math-display" translate="no">
  <math display="block" class="tml-display" style="display:block math;">
    <mfrac>
      <mn>1</mn>
      <mn>2</mn>
    </mfrac>
  </math>
</div>
<p>Inline, <span class="math math-inline" translate="no"><math><msup><mi>e</mi><mrow class="tml-sml-pad"><mi>i</mi><mi>π</mi></mrow></msup></math></span>.</p>

Edges

  • Both dollars are needed and nothing may stand between them and the code span: $5, $x$ and $$x$$ are text.
  • Only math is math: a latex or tex fence shows its source.
  • The LaTeX stays raw, so braces, \, _ and ^ need no escaping.

Against CommonMark

Not in CommonMark. Both forms are what GitHub and GitLab render as math, so a document degrades well.

block

Table

GFM pipe tables: a header row, a delimiter row, then body rows, one line each.

As the parser reads it

| key || a | >  |
|-----||---|----|
| one || x | y  |
| ^   || z | w  |
Table, as the parser reads it, choose a phrase

Compiles to
<table>
  <thead>
    <tr>
      <th>key</th>
      <th colspan="2">a</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row" rowspan="2">one</th>
      <td>x</td>
      <td>y</td>
    </tr>
    <tr>
      <td>z</td>
      <td>w</td>
    </tr>
  </tbody>
</table>

Edges

  • || in the delimiter row makes header columns; their body cells render as <th scope="row">.
  • A cell of only > merges into the cell to its left, and a body cell of only ^ merges into the cell above.
  • A marker that cannot merge, like > in the first column, stays text. A row is one line: nothing in a cell reads past it.

Against CommonMark

Not in CommonMark. GFM tables, plus header columns and cell merging; whitespace alignment means nothing.

block

Thematic break

A line of three or more -, * or _.

As the parser reads it

Above

***

Below
Thematic break, as the parser reads it, choose a phrase

Compiles to
<p>Above</p>
<hr />
<p>Below</p>

Edges

  • --- at the very top of a file opens frontmatter instead.
  • Under a paragraph line, --- is a break, never a setext heading underline.
  • - --- is a thematic break inside a list item.

Against CommonMark

The same, except that --- under text can no longer make a heading.

block

Footnote

A reference is a label in brackets after a caret. A definition is the same at the start of a line, with a colon and its text.

As the parser reads it

A claim[^1].

[^1]: The source.
Footnote, as the parser reads it, choose a phrase

Compiles to
<p>A claim<sup><a href="#fn-1" id="fnref-1" role="doc-noteref">1</a></sup>.</p>
<section class="footnotes" role="doc-endnotes" aria-label="Footnotes">
  <ol>
    <li id="fn-1">
      <p>The source. <a href="#fnref-1" role="doc-backlink" aria-label="Back to reference 1">↩︎</a></p>
    </li>
  </ol>
</section>

Edges

  • A reference is one by its syntax alone, defined or not, before or after: escape a bracket, \[^abc], to write it as text.
  • A definition is a container, continued by lines indented four spaces.
  • mdsvex numbers notes by first reference and collects every definition into one section at the end. A missing or repeated label is an error.

Against CommonMark

Not in CommonMark. GFM's syntax, with the reference read by syntax alone so it streams.

block

Comment

An HTML comment, kept in the output as written.

As the parser reads it

<!-- draft -->
A paragraph.

<!-- note --> in the text
Comment, as the parser reads it, choose a phrase

Compiles to
<!-- draft -->
<p>A paragraph.</p>
<p><!-- note --> in the text</p>

Edges

  • Alone on its line it is a block, and the next line starts a block of its own.
  • With text after it on its line, it sits in that text's paragraph.
  • It counts as a tag, so a paragraph of only comments and tags gets no <p>.

Against CommonMark

CommonMark reads a comment as an HTML block that swallows the lines after it up to a blank line. PFM ends it at -->.

inline

Text and escapes

Everything the parser reads as no construct at all. A backslash before punctuation makes it text, and a character reference is its character.

As the parser reads it

Braces are Svelte, so \{ this \} is text,
as is &#123; and a | b.
Text and escapes, as the parser reads it, choose a phrase

Compiles to
<p>Braces are Svelte, so &#123; this &#125; is text,
as is &#123; and a | b.</p>

Edges

  • \{ and &#123; are how you write a brace that is not Svelte.
  • A | outside a table is text unless it marks intraword emphasis.
  • A NUL character is ordinary text, kept as written.

Against CommonMark

The same escapes. CommonMark replaces NUL with U+FFFD; PFM keeps it, so a parse never scans the source twice.

inline

Emphasis

_ around text. It opens after whitespace or punctuation and closes before it.

As the parser reads it

some _emphasis_ and fan|_tas_|tic
Emphasis, as the parser reads it, choose a phrase

Compiles to
<p>some <em>emphasis</em> and fan<em>tas</em>tic</p>

Edges

  • Inside a word, mark the boundary with |, which is not rendered: fan|_tas_|tic.
  • A | is the marker only beside a _, * or ~ that opens or closes. Before a mark that never closes, it is text.
  • Han, kana and hangul count as a boundary, so CJK prose needs no marker.

Against CommonMark

_ is emphasis and only emphasis, never strong, and intraword emphasis takes the explicit | instead of CommonMark's flanking rules.

inline

Strong

* around text, under the same open and close rules as emphasis.

As the parser reads it

some *strong* text, *_both_*
Strong, as the parser reads it, choose a phrase

Compiles to
<p>some <strong>strong</strong> text, <strong><em>both</em></strong></p>

Edges

  • The two nest either way: *_both_* and _*both*_.
  • A doubled delimiter nests, so **(x)** is strong inside strong.
  • Delimiters with nothing between them stay text.

Against CommonMark

* is strong and only strong. CommonMark's ** and __ are gone; the two marks never swap.

inline

Strikethrough

Two tildes around text.

As the parser reads it

that is ~~gone~~ now
Strikethrough, as the parser reads it, choose a phrase

Compiles to
<p>that is <del>gone</del> now</p>

Edges

  • The open and close rules of emphasis apply.
  • ~~~~(x)~~~~ is strikethrough inside strikethrough.
  • One tilde is subscript, not strikethrough.

Against CommonMark

Not in CommonMark. As in GFM, with two tildes only.

inline

Superscript

Carets around text.

As the parser reads it

E = mc^2^, Soon ^TM^
Superscript, as the parser reads it, choose a phrase

Compiles to
<p>E = mc<sup>2</sup>, Soon <sup>TM</sup></p>

Edges

  • A caret after [ starts a footnote reference instead: [^1].
  • In a table, a cell of only ^ is a merge marker.

Against CommonMark

Not in CommonMark. Pandoc's syntax.

inline

Subscript

Single tildes around text.

As the parser reads it

H~2~O and x~1~
Subscript, as the parser reads it, choose a phrase

Compiles to
<p>H<sub>2</sub>O and x<sub>1</sub></p>

Edges

  • Two tildes are strikethrough.
  • A | marks it inside a word, as it does emphasis.

Against CommonMark

Not in CommonMark. Pandoc's syntax.

inline

Code span

Text between runs of the same number of backticks, kept as written.

As the parser reads it

call `compile({ source })` first
Code span, as the parser reads it, choose a phrase

Compiles to
<p>call <code>compile(&#123; source &#125;)</code> first</p>

Edges

  • A brace in code is always text, escaped in the output.
  • A span is one or two backticks long, so two can hold a single backtick. Three or more in a line are text, and at its start they open a fence.
  • A code span in dollars is inline math.

Against CommonMark

Only runs of one or two backticks make a span; CommonMark takes any length. Braces inside are text, where elsewhere they are Svelte.

inline

Image

A link with a ! before it: the text is the alt, the destination the source.

As the parser reads it

![a penguin](./penguin.png)
Image, as the parser reads it, choose a phrase

Compiles to
<p><img src="./penguin.png" alt="a penguin" /></p>

Edges

  • An image is text, so a paragraph of one image keeps its <p> unless unwrap_images is on.
  • With import_images, which the Vite plugin turns on, a relative image is imported so the bundler sees it.
  • A footnote reference is not read in the alt.

Against CommonMark

The same syntax.

inline

Hard break

A backslash at the end of a line, between two lines of one paragraph.

As the parser reads it

one line\
the next
Hard break, as the parser reads it, choose a phrase

Compiles to
<p>one line<br />
the next</p>

Edges

  • Before a blank line, a new block or the end of input, the backslash is literal.
  • At the end of a heading or a table row it is literal too.

Against CommonMark

A backslash only. Trailing spaces mean nothing, since invisible syntax is bad.

svelte

Expression

A Svelte expression in braces, anywhere text can go.

As the parser reads it

You clicked {count} times.
Expression, as the parser reads it, choose a phrase

Compiles to
<p>You clicked {count} times.</p>

Edges

  • Escape a brace, \{, to write it as text; in code it is always text.
  • An expression does not run past its container: if a line leaves the quote or list item, its brace is text.
  • An unclosed brace is an error, not a fallback.

Against CommonMark

Not in CommonMark, where braces are text.

svelte

Element

An HTML element. A block level element that starts a line is a block; a phrasing element is inline.

As the parser reads it

<div>one</div> two

<b>bold over
two lines</b> and text
Element, as the parser reads it, choose a phrase

Compiles to
<div>one</div>
<p>two</p>
<p><b>bold over
two lines</b> and text</p>

Edges

  • Text after a block level close tag starts a paragraph of its own: two above.
  • A phrasing element that starts a line with content after its tag starts a paragraph, also across lines.
  • An element that never closes is literal text. <script>, <style>, <pre> and <textarea> hold text as written.

Against CommonMark

CommonMark's seven kinds of HTML block are one rule: an element holds what its lines hold and ends at its close tag.

svelte

Component

A Svelte component, a capitalised tag. It holds the same blocks the document does.

As the parser reads it

<Counter start={2} />

<Note>

Markdown *inside* it.

</Note>
Component, as the parser reads it, choose a phrase

Compiles to
<Counter start={2} />
<Note>
  <p>Markdown <strong>inside</strong> it.</p>
</Note>

Edges

  • Attributes are Svelte's, expressions included.
  • An open tag may run over lines, and a close tag's > may sit on the next line.
  • A repeated attribute is still a tag; Svelte rejects it when it compiles.

Against CommonMark

Not in CommonMark, which would read it as raw HTML.

svelte

Logic block

{#if}, {#each}, {#await}, {#key} and {#snippet}, with their branches. A container: markdown inside is markdown.

As the parser reads it

{#if open}
- {item}
{:else}
Nothing yet.
{/if}
Logic block, as the parser reads it, choose a phrase

Compiles to
{#if open}
  <ul>
    <li>{item}</li>
  </ul>
{:else}
  <p>Nothing yet.</p>
{/if}

Edges

  • Each branch ({:else}, {:then}) is its own container.
  • mdsvex closes a block left open at the end of its container; a stray {/if} is an error.

Against CommonMark

Not in CommonMark.

svelte

Special tag

Svelte's {@html}, {@const}, {@render}, {@debug} and {@attach} tags, as written.

As the parser reads it

{@html raw}

{@const x = 2}
Special tag, as the parser reads it, choose a phrase

Compiles to
{@html raw}{@const x = 2}

Edges

  • A paragraph of only tags gets no <p>.
  • In live code, {@html} is the one tag that may be live.

Against CommonMark

Not in CommonMark.

svelte

Script and style

The component's <script>, <script module> and <style>, with imports and state for the whole document.

As the parser reads it

<script>
	let count = $state(0);
</script>

{count}
Script and style, as the parser reads it, choose a phrase

Compiles to
<script>
  let count = $state(0);
</script>
<p>{count}</p>

Edges

  • Their content is text up to the close tag; nothing in it is markdown.
  • mdsvex merges its own imports, for directives and templates, into the script.

Against CommonMark

Not in CommonMark, which would read it as an HTML block.

directive

Inline directive

A colon, a name, text in brackets and optional named arguments, in running text.

As the parser reads it

Press :kbd[Ctrl](os=mac) to copy.
Inline directive, as the parser reads it, choose a phrase

Compiles to
<script>
  import { kbd as Kbd_MDSVEX_D_G } from './directives.js';
</script>
<p>Press <Kbd_MDSVEX_D_G os="mac">Ctrl</Kbd_MDSVEX_D_G> to copy.</p>

Edges

  • The brackets are required, even empty (:name[]), so :tada: and std::vector stay text.
  • The text takes simple inline marks but not links or images, and its brackets must balance.
  • A malformed argument list closes the directive at ] and leaves (…) as text.

Against CommonMark

From the generic directives proposal, with named arguments in parentheses where the proposal has {key=val}, since braces are Svelte.

directive

Leaf directive

Two colons and a name, alone on its line, with optional text and arguments.

As the parser reads it

::figure[A penguin](src=./penguin.png)
Leaf directive, as the parser reads it, choose a phrase

Compiles to
<script>
  import { figure as Figure_MDSVEX_D_G } from './directives.js';
</script>
<Figure_MDSVEX_D_G src="./penguin.png">
  {#snippet label()}
    A penguin
  {/snippet}
</Figure_MDSVEX_D_G>

Edges

  • Brackets are optional: ::name is a directive with no text.
  • After the name only the argument list may follow. ::name some text is a paragraph.
  • When both are given the brackets come first; ::name(k=v)[text] is a paragraph.

Against CommonMark

From the generic directives proposal. Arguments are named only, key=value.

directive

Container directive

Three colons and a name open it, a line of three colons closes it, and it holds the same blocks the document does.

As the parser reads it

:::note[Heads up](tone=warn)
Markdown *inside* it.
:::
Container directive, as the parser reads it, choose a phrase

Compiles to
<script>
  import { note as Note_MDSVEX_D_G } from './directives.js';
</script>
<Note_MDSVEX_D_G tone="warn">
  {#snippet label()}
    Heads up
  {/snippet}
  <p>Markdown <strong>inside</strong> it.</p>
</Note_MDSVEX_D_G>

Edges

  • Its label becomes a label snippet and its arguments props of the component it maps to.
  • Since arguments are props, a wrong value is a type error in the editor.
  • With no component or handler for its name, the compile throws unless strict_directives is off.

Against CommonMark

From the generic directives proposal.

document

Frontmatter

YAML between --- lines at the very top of the file, exported as metadata.

As the parser reads it

---
title: Getting started
---

# {metadata.title}
Frontmatter, as the parser reads it, choose a phrase

Compiles to
<script module>
  export const metadata = {"title":"Getting started"};
</script>
<h1>{metadata.title}</h1>

Edges

  • Only at the top of a document; inside a container --- is a thematic break.
  • A template gets it as props, typed against them in the editor.
  • Another format, such as TOML, is a frontmatter.parse option away.

Against CommonMark

Not in CommonMark, where --- at the top is a thematic break.

document

Import

An import line at the top of the document, moved into the component's script.

As the parser reads it

import Counter from "./Counter.svelte";

<Counter />
Import, as the parser reads it, choose a phrase

Compiles to
<script>
  import Counter from "./Counter.svelte";
</script>
<Counter />

Edges

  • Read at the top of a document only, like frontmatter.
  • Inside a container the line is text.

Against CommonMark

Not in CommonMark, where it is a paragraph.

document

Live code

A fence whose braces become Svelte expressions, through the eval flag or an [!eval] comment on a line.

As the parser reads it

```sh eval
{install} @pkg/my-pkg
```
Live code, as the parser reads it, choose a phrase

Compiles to with highlight
<pre class="twinkleplop language-sh" data-language="sh">
  <code>
    <span class="l"><span class="tok">{install}</span> @pkg/my-pkg</span>
  </code>
</pre>

Edges

  • Without eval or a marker, braces in code are text.
  • Only expression tags may be live, one line each; {#if} or {@const} fail the build.
  • It needs highlighting, which the Vite plugin turns on; this compile has it on.

Against CommonMark

Not in CommonMark, where code is always literal.

document

Template

A Svelte component that wraps the document, picked by the template key. Its module exports replace elements by name.

As the parser reads it

---
template: docs
---

## Install
Template, as the parser reads it, choose a phrase

Compiles to
<script>
  import Template_MDSVEX, { h2 as H2_MDSVEX_T } from './templates/docs.svelte';
  let __mdsvex_props = $props();
</script>
<script module>
  export const metadata = {"template":"docs"};
</script>
<Template_MDSVEX {...metadata} {...__mdsvex_props}>
  <H2_MDSVEX_T level={2}>Install</H2_MDSVEX_T>
</Template_MDSVEX>

Edges

  • This compile registers a docs template that exports h2, so the heading becomes its component.
  • With no key, default_template or select_template decides, or none wraps the page.
  • The frontmatter is spread on the template as props.

Against CommonMark

Not in CommonMark: a template is what mdsvex does with a document, not syntax.

Every score on this page is @mdsvex/parse reading its source, and every output is mdsvex’s compile, run when the site is built. Nothing is drawn by hand.

Set in Playfair, Source Serif 4 and Berkeley Mono, with IBM Plex Mono where Berkeley is not installed.

mdsvex, markdown with Svelte in it. MIT licence.