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 Seed CLI prints it and accepts it.
Folder sync stores a whole space in it.
A site's .md export and the read tool of Seed Agents return a form of it made for reading.
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
Publish a folder, which keeps a folder of these files and a space the same
Seed CLI, document get, document update and the space commands
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime