HyperMarkDown for VS Code

Live preview for HyperMarkDown (.hmd) knowledge bases: source on the left, the rendered card on the right, keeping up as you type.

HyperMarkDown is ordinary markdown plus links into a knowledge graph: you write the name of a card and it is resolved for you, a card can be built out of other cards, and a linter checks the whole graph. Every .md file is already valid .hmd. The format itself — every construct, the resolution rules, the rule IDs — is documented at hypermarkdown.org. This page is about the extension.

Install

ext install hypermarkdown.hmd

• VS Code — the marketplace listing, or search HyperMarkDown in the Extensions view.
• Cursor, Windsurf, VSCodium — Open VSX.
• From a VSIX — every CI run attaches one, and each release carries it: releases.

Then open any .hmd file and click the ⚡ at the top right of the editor. Nothing else is required: no interpreter, no virtualenv, no configuration. Requires VS Code 1.90 or newer.

Preview release. Everything below is built and gated by tests. The graph tab and the publication model are not here yet — see Known gaps.

What it does

• Rendered preview, updating from the unsaved buffer, scroll-synced with the editor in both directions.
• Embeds render as cards — labelled with the card and fragment they came from, collapsible, and navigating to the embedded card rather than the embedding one. An embed flattened into anonymous prose is a defect here.
• Red links for targets that do not resolve, with a create-the-card action.
• Backlinks for the current card, listing link and embed edges separately.
• Diagnostics in the Problems panel using the HMD001–HMD016 rule IDs, identical to hmd lint.
• Math, callouts, and D2 diagrams. KaTeX ships inside the extension; a d2 fence draws when d2 is on PATH or Docker is available, and shows its source otherwise.
• Syntax highlighting for .hmd as its own language.

What it needs

The extension is the preview and the viewer, and it carries its own implementation of the format for them. Nothing has to be installed to render a card: no interpreter to find, no virtualenv to activate, and no subprocess between a keystroke and the preview. The hmd CLI remains the canonical implementation and CI checks the two against a shared conformance corpus.

Completion and the other language-server features are not here yet. They arrive with the Python language server, which lives with the canonical implementation — so a later version will want Python for those, while the preview keeps rendering without it.

Settings

Commands

• HyperMarkDown: Open Preview in This Column — a preview tab in the editor group you are in
• HyperMarkDown: Open Preview to the Side — the same, in the group beside it
• HyperMarkDown: Pin Preview to This Card — stop following the active editor
• HyperMarkDown: Create Missing Card — write the card a red link points at
• HyperMarkDown: Rebuild Index — re-scan the namespace root

Where the preview appears

The preview is an editor tab, not a side-bar view. Click the ⚡ at the top right of any editor group and a preview opens in that group — including when the neighbouring group is locked, which is where "open to the side" gives up and splits a third group instead.

A preview follows the active editor: click another card in the Explorer or the tab bar and the preview re-renders on it. Clicking a [[wikilink]] moves the preview to the target and opens its source alongside, leaving focus in the preview so the next link is one click away.

Open as many as you like — each is titled after its card. To hold one on a card while you read elsewhere, click the 📌 in its title bar; the breadcrumb shows pinned while it is held. Tabs come back on their own cards after a window reload.

Known gaps

Every divergence from the canonical hmd CLI is ledgered with its reason in conformance-xfail.json, and a ledgered entry that stops diverging fails the build. The ones worth knowing about while you write:

• Raw HTML in a card is escaped rather than passed through. Deliberate, and a divergence from the MkDocs build: a webview rendering HTML out of a workspace is a script-injection surface reachable from any cloned repository.
• HMD017 is never reported. The publication model behind it — nav.visibility, which the CLI inherits down a subtree and defaults to private — is unported, so nothing here knows whether a card is published.
• A setext heading (a title underlined with =====) gets a slug here and none in the CLI, so [[Card#Section]] against one resolves in the preview and not in a build. Write ATX headings.
• Math is typeset by KaTeX rather than by the site's MathJax, and ~x~ subscript is unsupported.
• The graph tab is specified and not built yet.

What has changed is in CHANGELOG.md; work points are tracked in doc/vsc-ext/STATUS.md. Bugs and questions go to the issue tracker.

Working on it

The extension is specified by HMD-0021; the parser, resolver, and renderer come from @hypermarkdown/core, specified by HMD-0020. DEVELOP.md is the contributor's guide: the two bundles, the Extension Development Host, what to walk through by hand, and how the VSIX is built and published.

License

MIT — see LICENSE.