Skip to content

Fidelity tiers ​

Every block type declares which tier it exports at. The tier says what happens to it in a file somebody opens in another editor.

TierGuarantee
T1Lossless round-trip through pure CommonMark.
T2Lossless via widely-supported extensions (GFM).
T3Degrades to readable Markdown plus an HTML-comment sidecar carrying the block data.

The per-type table is generated from the block registry — pnpm report:fidelity writes it, and CI regenerates it, so it cannot drift from what the code actually does.

Where each block type sits ​

T1 — paragraph, heading, bulletListItem, numberedListItem, quote, codeBlock, divider, image.

T2 — todoItem, table, tableRow, tableCell.

T3 — callout, blockRef, databaseView. What each loses:

  • callout renders as a plain blockquote (> [!NOTE]). A reader who ignores the sidecar keeps the text and loses the styling.
  • blockRef exports as a blockquote of the referenced block's text, attributed to its page. The link back to the original block is in the sidecar; a reader who ignores it keeps the words and loses the live reference. On a page written as Markdown it is written as Obsidian's ![[page#^name]] instead, which Obsidian follows.
  • databaseView exports as a real GFM table whose first column links to each row's own .md file — the rows are ordinary pages and their cells are those pages' frontmatter, so nothing is trapped. What degrades is the query: filters, columns and sort live in a .base.yaml beside the export, and a reader who ignores it sees a table frozen at the moment of export.

Two properties that cut across every tier ​

A tier belongs to a block type. Two properties belong to a block regardless of type:

  • date — the day the author places it on.
  • timeline — pinned or hidden.

A page's own metadata has somewhere to live — frontmatter. A block has no frontmatter, so these degrade the way every other unrepresentable block datum does: a sidecar comment after the block.

The consequence, stated rather than discovered: a block carrying either property is T3 for that export, whatever its row in the table says. Its text is untouched — a plain Markdown reader sees exactly what it would have seen, and ignores one HTML comment:

markdown
- Ordered the replacement sensor.
<!-- notesflow:paragraph {"date":"2014-03-12"} -->

Only those two keys are ever written this way. A generic "export any unrepresentable property" pass would start writing every block type's internal state into files, and the whole point of declaring a tier per type is that the Markdown story is a deliberate decision rather than a side effect.

Names and regions ​

A block's name and a region of blocks are also properties of blocks, and they do have a Markdown form that other tools read — Obsidian's — so they are written that way rather than in a sidecar, and do not change a block's tier:

markdown
We ship on the first Monday of the month. ^release-day

<!-- region: pricing -->

Plans are billed monthly.

Annual plans get two months free.

<!-- /region -->

Obsidian resolves ^name natively and hides the region comments as it hides any HTML comment. Import reads both back. See block references.

Keeping the formatting as typed ​

A Markdown page can keep each block's own formatting — * bullets, __bold__, a list starting at 3 — and the export writes the block exactly as typed wherever that still reads as the same block. Elsewhere, and on every other page, the export writes the canonical form. Either way the block round-trips at its tier.

Why inline content stays poor ​

Marks are limited to what CommonMark and GFM can express, and code cannot be bold, italic or struck through. It can be a link: [`store.ts`](…) is ordinary CommonMark.

The rule against emphasis is not a simplification for convenience. CommonMark genuinely cannot express a bolded code span adjacent to a word: code spans bind tighter than emphasis delimiters, so the markup reparses as literal asterisks. Bold code is a marginal typographic nicety; silently corrupting a document on export is not.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.