Markdown as a data source

mdsmith extract projects a schema-conformant Markdown file into a JSON, YAML, or msgpack data tree; mdsmith export writes a portable, directive-free copy that renders anywhere.

A schema-conformant Markdown file is already structured data: the front matter is a map, and the headings beneath it form a tree. mdsmith extract reads that structure with no extra annotation, because the kind schema is the extraction contract.

mdsmith extract <kind> --format json|yaml|msgpack <file> walks the composed schema alongside the file and emits a tree. Front matter goes under a frontmatter key, each heading becomes an object keyed by its slug, and repeating sections become arrays. A non-conformant file prints the same diagnostics as mdsmith check and exits non-zero, never emitting partial data.

The read side lives on the <?include?> directive. Its extract: parameter walks the same tree and splices one leaf into another file’s body. A README can quote a value from its source of truth, and mdsmith fix keeps the copy current. No intermediate fragment file is left to maintain.

For plain Markdown instead of data, mdsmith export writes a portable, directive-free copy. It strips generated-section markers, inlines <?include?> content recursively, and leaves a file that renders on any Markdown tool with no mdsmith knowledge. By default it refuses to export a stale directive body; --fix regenerates first.

See the Extract Markdown as data guide for when a value belongs in front matter versus a body section. The mdsmith extract and mdsmith export references cover flags, formats, and exit codes.