v0.1.0 — The MemorySmith Markdown Profile

The first published version of the MemorySmith Markdown Profile.

There are exactly two formal specifications in the Markdown family: CommonMark and GFM. Everything above that line — wikilinks, embeds, callouts, frontmatter, the notation every knowledge vault is actually written in — is convention, and each tool means something slightly different by it. This profile writes down one meaning, as prose, as data and as an executable suite.

What it declares

• The three rings. CommonMark 0.31.2 and GFM 0.29-gfm as the base, and the vault ring specified here.
• Links. The wikilink and its alias and anchor forms, the embed, the relative Markdown link, and one resolution rule for all of them: basename, extension dropped, slug, resolved within the vault, anchor kept for display only. Pending links are kept, reported, and resolve on their own later.
• Frontmatter. The YAML subset an indexer reads, and the rule that the shape of the value decides indexing — date, boolean, short value, list of short values; prose above forty characters discarded. The reserved vocabulary is aliases, tags, created and updated, in en-US, with translation allowed on the label and never on the bytes.
• The reading surface. Callouts, mermaid, one-level transclusion, the visible pending link, and the writing-back rule for an interactive task list.
• What is rejected, and why. The inline #subject, title as a reserved key, the external link as an edge, and prose in the frontmatter. Absence from the specification is a statement, not an oversight.

What ships

SPEC.md is the specification. profile.json is the same notation as data, with a JSON Schema. tests/conformance.json is the suite that proves an implementation reads it, including the cases whose expected result is nothing.

The suite earned its place before publication: run against the first implementation's extractors, it found a real defect on the first attempt.

Depending on it

pnpm add github:memorysmithapp/markdown-profile#v0.1.0

import profile from '@memorysmith/markdown-profile/profile.json' with { type: 'json' };
import cases from '@memorysmith/markdown-profile/conformance.json' with { type: 'json' };

An implementation that keeps a copy of the notation drifts from the specification on the first cycle, and the drift is silent. That is the failure this profile exists to prevent one layer up, and it is why it is consumable by version rather than by copy.

Licence

The text of the specification is CC BY 4.0; profile.json, the schema and the conformance suite are MIT. Anyone may implement this profile; only an implementation that passes the conformance suite may describe itself as conforming to it.