Markdown dialect
The markdown dialect is the markdown form of a Hypermedia document that loses nothing; this page lists what each part of the syntax carries and the SDK functions that read and write it.

The markdown dialect is a way to write a Hypermedia document as a markdown file without losing anything. A document is a tree of typed blocks with annotations and metadata. Plain markdown can say most of that, and the dialect adds the rest. If you write a document to markdown and parse it again, you get the same document.

Several programs use it:

The code exists once, in the SDK.

The format

    Ordinary markdown where it exists. Headings, paragraphs, lists, block quotes, fenced code, math, images, links, tables, bold, italic, strikethrough and inline code are plain markdown.

    Frontmatter. A YAML block at the top holds every metadata key of the document. It keeps keys the program does not know.

    Block identity. Each block ends with an HTML marker, <!-- id:X -->. The id tells a program that an edit changes that block and does not replace it.

    What markdown cannot say. The same marker may carry type:, naming a block type such as Video, File, Button, Embed or Query, and attrs:, a JSON object of attributes such as an image width or a query definition.

    Nesting. A block's children sit two spaces deeper, or at the content column of a list marker. A heading's children follow it at the same indentation, and <!-- end:X --> closes a heading when a non-heading sibling follows.

    Text. Markdown syntax characters in text are escaped. A newline inside a block is
    . Styles markdown lacks, such as underline, highlight and colors, are inline HTML tags.

    Diagrams. A mermaid code fence is a diagram and must parse.

    Files without ids. A file you write by hand needs no markers. Its blocks are matched to an existing document by position.

Functions

Write and parse. blocksToMarkdown(doc) and parseMarkdown(md) are a pair that loses nothing. Every block type, annotation, attribute and metadata key comes back the same after a round trip.

    parseMarkdown returns {tree, metadata}.

    flattenToOperations turns the tree into DocumentOperations, the steps you publish.

    markdownBlockNodesToHMBlockNodes converts the parsed tree to the shape the API uses.

Errors.

    parseMarkdown throws MarkdownFrontmatterError when the YAML in the frontmatter does not parse. Pass {strictFrontmatter: false} where the code only shows the text and must accept anything.

    assertValidMermaid(nodes, parser) rejects with InvalidMermaidError when a mermaid Code block does not parse.

    loadMermaidParser() from @seed-hypermedia/client/mermaid-parser gives you the parser in a browser, Node or Bun. You install mermaid yourself, and also linkedom when you are not in a browser.

Publish a folder describes the dialect from a writer's side.

For reading. documentToResolvedMarkdown(doc, {client, maxDepth?}), commentToResolvedMarkdown and contentToResolvedMarkdown fetch embeds, mentions and query blocks over the network and put their content in the text. commentToResolvedMarkdown does this for a comment. The web .md export and the read tool of Seed Agents return this form.

Drafts. slugify(title), draftFilename(slug, id) (<slug>_<id>.md) and parseDraftFilename name draft files the way the CLI and the desktop app do.

See also

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime