QMDC — A Markdown-native context graph for humans and agents

Human-readable docs. Machine-queryable graph. Agent-ready context.

Alpha release

QMDC is early and moving fast — the format, APIs, and tooling may still change, and some edges will be rough or broken. If something doesn't work, please open an issue. Bug reports and feedback are hugely welcome.

What's new in 2.0

One document, one answer, in every language. The Rust, Python and TypeScript parsers now give identical output for every document in the QMDC repository (in 1.x, 32 of 108 parsed differently) and agree on 4,500+ shared conformance cases, on Linux, macOS and Windows.
Nothing is lost in silence. Field values, comments and text blocks are the source text as you wrote it, so parse → rebuild no longer rewrites your document. Constructs that used to be dropped or mangled — a second table, prose under an inline field, 1e5, a value wrapped onto two lines — are now named validation errors that say what to write instead.
Many repositories, one graph. -w composes workspaces from anywhere on disk, references can name a workspace ([[#shop:storage:users]]), and the MCP server composes a folder of sibling repositories instead of refusing it.
Libraries that work as published. import { parse } from '@qmdc/qmdc' works now. Every package is tested as the installed artifact, README examples included.
.qmdcignore is .gitignore. A port of git's own matcher, pinned against git on 79 line forms.

Upgrading from 1.x — four breaking changes: drop the Kind segment from references ([[#Table:users]] → [[#users]], or [[#storage:users]] when the id is in several namespaces); read workspaces[0].id instead of workspace and objectId instead of object in workspace parse output; and rebuild anything that stored synthesised doc_… / text_… ids. Details in the CHANGELOG.

QMDC turns your documentation into a knowledge graph — without leaving Markdown. Headings become objects, list items become fields, and [[#references]] create typed edges. The result is one source of truth with three audiences: humans read it as Markdown, machines query it with SQL, and agents navigate it over MCP.

QMD.md vs QMDC

QMD.md is the format — the Markdown convention you write, stored in .qmd.md files. QMDC is the toolchain that reads it: the qmdc CLI, the qmdc-py / qmdc-ts / qmdc-rs parsers, the VS Code extension, and the documentation-site generator. In short — you author QMD.md; QMDC parses, validates, and queries it. The file extension stays .qmd.md.

Install

uvx qmdc --help        # PyPI (bundles the native binary)
npx @qmdc/qmdc --help  # npm (bundles the native binary)
cargo install qmdc     # crates.io (builds from source)

Editor support: the VS Code extension ships on the VS Code Marketplace and Open VSX.

Get Started

Quickstart — Install, create a file, parse it, query it — 5 minutes.
Why QMDC? — What problem does QMDC solve and who is it for.
Markdown → Graph — How headings and lists become a queryable knowledge graph.
QMDC for Agents — Give your AI coding assistant structured context.
MCP Server — Expose your project graph to AI agents over the Model Context Protocol (qmdc mcp): search, SQL, graph walks, rename.
VS Code Extension — LSP-powered editing, live preview, SQL queries. Install from the VS Code Marketplace or Open VSX.

Tutorials

Learn QMDC by doing:

Quickstart — zero to a working graph in 5 minutes
Write Your First QMD.md File — a detailed lesson with explanations

How-to Guides

Recipes for specific tasks:

Validate a Document — check for errors and fix them
Query Your Graph — SQL queries against your workspace
Build a Workspace — multi-file project from scratch
Use with VS Code — IDE integration with diagnostics and navigation

Reference

Format Specification — complete syntax reference (objects, fields, references, arrays, types)
CLI Commands — qmdc parse, validate, query, rebuild
VS Code Extension — commands, settings, views
LSP Server — diagnostics, completion, navigation, refactoring

How It Works

## API Gateway [[gateway: Service]]

- port:8080
- depends:[[#auth]], [[#users]]

## Auth Service [[auth: Service]]

- protocol:JWT
- database:[[#postgres]]

## User Service [[users: Service]]

- depends:[[#auth]]
- database:[[#postgres]]

## PostgreSQL [[postgres: Resource]]

- version:16

graph TD GW[API Gateway :8080] --> AUTH[Auth Service JWT] GW --> USERS[User Service] USERS --> AUTH AUTH --> PG[(PostgreSQL 16)] USERS --> PG

One file. One parse. A queryable graph with typed edges — depends, database, protocol — all from plain Markdown.

Then query it like a database:

SELECT source_id, target_id FROM edges WHERE edge_type = 'depends'

source_id	target_id
gateway	auth
gateway	users
users	auth

Three parsers (Python, TypeScript, Rust). VS Code extension with LSP. SQL queries over your docs.