Supported Markdown Features

What you can rely on when authoring documents for Demarkus.

The short version

Demarkus accepts UTF-8 markdown at .md paths and preserves the body. Clients render it; knowledge-system writes also pass policy and content checks. demarkus-tui uses Glamour over goldmark: CommonMark + GitHub Flavored Markdown + definition lists.

The rendering features below describe the TUI. The CLI returns markdown; MCP may return a section or outline. The library has its own renderer.

CommonMark

Everything in the CommonMark spec works:

• Headings (#, ##, …, or Setext-style with === / ---)
• Paragraphs, hard and soft line breaks
• Emphasis: *italic*, **bold**, ***both***
• Inline code: `code`
• Fenced and indented code blocks (with optional language hint for syntax highlighting)
• Block quotes (>)
• Ordered and unordered lists, nested
• Inline links: [text](url) and [text](url "title")
• Inline images: ![alt](url)
• Autolinks: <https://example.com>, <[email protected]>
• Horizontal rules (---, ***, ___)
• Reference-style links: [text][label] with [label]: url elsewhere in the document

GitHub Flavored Markdown (GFM)

• Tables: pipe-delimited with a separator row:

  | Column | Value |
  |--------|-------|
  | a      | 1     |
  

• Strikethrough: ~~text~~
• Task lists: - [ ] and - [x]
• Linkify / bare URLs: https://example.com is rendered as a clickable link without needing angle brackets

Definition lists

Term
: Definition for the term
: A second definition

Metadata

Demarkus separates document content (what you author) from metadata (attributes about the document). Metadata does not belong in the body.

Server-managed frontmatter

The server persists each version with its own YAML frontmatter block prepended to the body:

---
version: 3
archived: false
previous-hash: sha256-abc123…
type: Document
title: Architecture Notes
tags: [architecture, notes]
meta.author: Fritz
---
<your body here>

The block mixes three kinds of keys:

• Operational (version, previous-hash, archived): owned by the store. They are reserved: a publisher that tries to set them is rejected.
• Open Knowledge Format fields (type, title, description, resource, tags, timestamp): stored bare under their OKF names, so a demarkus document is content-compatible with OKF v0.1. tags is written as a YAML flow list.
• Other publisher metadata: namespaced under meta.* to keep it clear of the reserved and OKF names.

The handler strips this whole block before returning the body to clients, so you never see it when you FETCH.

Archive state is maintained separately; archiving does not rewrite stored versions.

Publisher metadata

To attach structured metadata to a document, pass it as request metadata on PUBLISH, not by writing YAML inside the body. Recognized OKF fields (type, title, description, resource, tags, timestamp) are stored bare; every other key is namespaced under meta.*. All of it is surfaced in response metadata on FETCH.

If you don’t declare a type, the server assigns type: Document on PUBLISH and APPEND, so every stored document is a typed OKF concept (the reserved index.md and log.md are exempt).

Limits: up to 50 keys totaling 1024 bytes (tags counted at its serialized list length).

Response fields (computed, not stored)

On FETCH, the server returns modified, etag, and content-hash as protocol metadata. These are derived from the version file at read time and are not stored in frontmatter.

If you write --- at the top of your body

It remains body content, not publisher metadata. Authoring gates may reject an in-body frontmatter block. Pass metadata separately.

Open Knowledge Format (OKF) compatibility

A single demarkus document is content-compatible with Google’s Open Knowledge Format v0.1: the recognized OKF fields are stored under their OKF names (see above), and the server assigns a default type so every document is a typed OKF concept.

This is a document-level guarantee. At the system level demarkus is a superset, layering versioning, a SHA-256 hash chain, QUIC transport, capability auth, and LOOKUP around an OKF-compatible document. Demarkus does not serve or ingest OKF bundles over the wire (frontmatter is stripped before serving, and the versions/ store is not a bundle tree). Bundle interop is handled out of band by the demarkus okf codec:

• demarkus okf validate <bundle-dir>: check a directory of markdown files for OKF v0.1 conformance.
• demarkus okf import <bundle-dir> mark://host/prefix: publish an OKF bundle into a demarkus world (sanitizes/caps metadata with warnings, rewrites bundle-absolute links).
• demarkus okf export mark://host/prefix <out-dir>: write a demarkus world subtree back out as a conformant OKF bundle.

See the protocol specification (§14) for the full field mapping and conformance details.

What is not supported

The TUI renderer does not support these, even though you’ll see them in other markdown ecosystems:

• Footnotes ([^1]): not enabled in the default Glamour parser
• Math / LaTeX ($…$, $$…$$): no MathJax or KaTeX equivalent
• Diagrams: no Mermaid, PlantUML, or embedded SVG rendering
• Wiki-style links ([[foo]]): not supported; write standard [text](url) links
• Embeds / transclusion: no ![[foo]] or similar
• Custom containers (::: note, :::warning): no admonitions
• Raw HTML: CommonMark allows it; Glamour passes most tags through unstyled. Do not rely on it for rendering fidelity
• Emoji shortcodes (:smile:): use the actual Unicode character instead

Link graph

Documents are crawlable. The link extractor (used by demarkus graph, document-graph views in the TUI, and federation indexing) parses with the default CommonMark parser and walks ast.Link nodes. It recognizes:

• Inline links: [text](url)
• Reference-style links: [text][label] + [label]: url

It does not track:

• Autolinks inside angle brackets: <https://example.com> (a different AST node type)
• Bare URLs that Glamour linkifies at render time
• Wiki-style [[links]]

If you want a link to appear in the graph, use [text](url) or a reference link.

Publisher keys such as rel-depends-on also declare typed document relations. Graph results distinguish these from ordinary links and carry source revisions.

Document size

• Body: up to 1 MiB (MaxBodyLength = 1048576 bytes)
• Publisher metadata: up to 50 keys, 1024 bytes total (tags counted at its serialized list length)
• Stored frontmatter: up to 2 KiB on disk per version (publisher metadata plus the store’s own operational fields)

Why so minimal?

Demarkus is a protocol for versioned markdown, not a documentation platform. The goal is that any markdown renderer can consume a demarkus document sensibly, and the lowest common denominator (CommonMark + GFM) is well-understood everywhere. Features like Mermaid or math can be layered by specific clients without forcing every consumer to support them.

If a feature you need isn’t here, open an issue. The renderer is swappable.