hyper-markdown

Skip to content

Introduction

Namespaces

Features

Presentation

Vision

Tutorial

Language Specification

Wiki

Tools

Hyper-markdown¶

Hyper-markdown (.hmd) is ordinary Markdown plus rich visuals plus wiki links<br>into a knowledge graph. Every .md file is already valid .hmd.

TL;DR&para;

A superset of CommonMark. Rename a .md file to .hmd and it is already<br>valid — nothing breaks, and the format is adopted one file at a time.

Names, not paths. [[tokens]] is looked up beside the card and then upward<br>through its parent folders. A name that could mean two documents is an error<br>rather than a guess.

Documents made of documents. ![[glossary/token#^definition]] splices one<br>named block into another page. Write a definition once and embed it everywhere<br>it is needed.

Rich content is assumed, not optional. TeX mathematics, D2 diagrams,<br>callouts, footnotes, task lists, and tables are part of what a card may carry.<br>A diagram is text in the file and a diff you can read, and it degrades to its<br>own labelled source rather than to a blank space.

The specification is the artifact. The Python CLI, the MkDocs plugin, and<br>the VS Code extension are implementations around it; they conform to it rather<br>than define it.

Version 0.x is a stage, not the scope. The resolver, linter, embed<br>expander, renderer, and MkDocs plugin work today. Queries over the document<br>graph and namespaces beyond one tree are specified in outline and unbuilt.

Language&para;

Three layers stack in one file. At the base, CommonMark , inherited whole —<br>nothing redefined and nothing taken away, which is why a .md file is already<br>a valid card. Above it a rich layer — tables, footnotes, task lists,<br>callouts, TeX mathematics, D2 diagrams — taken from the wider Markdown<br>ecosystem rather than invented here, and assumed present rather than optional.<br>And the hyper layer — arguably the most innovative part, and the reason the<br>format exists at all: a small set of constructs that are all variations on one<br>idea, naming another document or a part of one. Those upper two layers are<br>what hyper-markdown adds, and a specification is what fixes them, not<br>convention.

See [[tokens]] for the format, or pull one block in whole:

![[glossary/token#^definition]]

A card may open with YAML frontmatter, where four keys mean something to the<br>toolchain — tags, use, import, nav — and every other key belongs to the<br>author. The whole language fits on one page and can be learned in one sitting:<br>the HMD Tutorial. What that page teaches, the<br>HMD Language Specification states normatively.

Features&para;

Wiki links to documents, headings, and named blocks; transclusion of any of<br>them; filesystem-shaped modules with explicit imports; TeX mathematics, D2<br>diagrams, callouts, collapsible sections, footnotes, tables, and the GitHub-<br>flavoured Markdown baseline. HQL, a query language over the document graph, is<br>reserved and not yet designed.

What a page can carry, shown working rather than described, is<br>Features. How a bare name becomes a page — the spine walk,<br>imports, ambiguity as an error, and the module/namespace distinction — is<br>Namespaces.

Tools&para;

hmd lints a tree, renders a card to markdown or HTML, and dumps the resolved<br>graph. A missing target is a warning, because writing forward is how a wiki<br>grows; an ambiguous or malformed one is an error, because that is the one thing<br>the format refuses to guess at.

There are three of them, one directory each under tools/ in the repository,<br>each carrying its own version, README, and changelog:

hmd —<br>the Python line, published to PyPI as<br>hyper-markdown: the CLI<br>(lint, render, graph), the library beneath it, and the MkDocs plugin<br>that builds this site. Canonical — where two implementations disagree, this<br>one defines the answer — and it will host the language server.

hmd-ts-core<br>— @hyper-markdown/core, a second implementation of the format in<br>TypeScript rather than extension code, answering to the same<br>conformance corpus<br>the canonical tool does.

hmd-vsc-ext<br>— the VS Code extension, in development: live preview that keeps the embed<br>boundary visible, plus backlinks, red links, and diagnostics.

Presentation is not part of the language. A card is plain text, so an editor,<br>GitHub, or a chat window already shows it. The MkDocs plugin builds a tree of<br>cards into a published site — this one, a hand-ordered book with a generated<br>wiki inside it — and the extension renders one in the editor as it is typed.<br>The trade-offs between them are Presentation.

The VS Code extension: the card's source on the left, the rendered card on the<br>right, updated as it is typed.

Specification&para;

The normative text is one document, the<br>HMD Language Specification: what a card is, what each<br>construct means, and what an implementation must do with it. It describes no<br>particular program, and no program's behaviour overrides it.

It is stated against a named baseline — CommonMark 0.31.2 — because "markdown"<br>names a family rather than a...