v0.3.0 — A document you can read alone

The cycle in which the specification stopped being a document you read with two other documents open.

Until now it named CommonMark 0.31.2 and GFM 0.29-gfm, declared both normative in full, and linked away. So reading it properly meant three specifications side by side — and the part that mattered most was in none of them. A fenced code block is CommonMark; that a [[link]] inside one produces no edge is this profile. A block quote is CommonMark; that one beginning [!warning] is a callout is this profile. CommonMark admits raw HTML; that a Reader here must not render it is this profile, as a security boundary. Every one of those joins is invisible from either side alone, and none of them was written down.

Added

• The base and the extended ring, restated in the document, in full — §3 covers CommonMark 0.31.2 and §4 covers GFM 0.29-gfm, every block and every inline, with the form as it is typed and what it produces. §2.1 states what a restatement is: where it and its source disagree, the source governs and this document is in error. The compatibility promise is exactly what it was; what changes is that the reader no longer has to reconstruct it. Each crossing into the third ring is stated where an author meets it, and again in the section that governs it.
• profile.json carries the base and extended forms — 23 entries, 54 in all. An implementation that builds its documentation from the data now gets the whole notation and not only the third ring.
• Appendix B, the notation at a glance — every form in one table, with what it does beyond being rendered, including the rows whose answer is nothing.
• The repository gained the rules of working on it — CONTRIBUTING.md, CLAUDE.md, two issue forms, a pull request template, and npm run check: a dependency-free consistency check that refuses SPEC.md, profile.json and tests/conformance.json drifting apart, now required on every pull request.

Changed

• The third ring is named MemorySmith, and no longer Vault. In a document that uses "vault" on nearly every page for the thing a person keeps — the folder resolution may not cross, the boundary an edge stays inside — the same word named a layer of the specification, and the reader had to tell the two apart from context. A ring is named after the specification that governs it, and the one that governs this ring is this document.
• The sections after the two new rings are renumbered. Links, frontmatter, the reading surface and the rejections move from §3–§6 to §5–§8, and everything after them by the same two.

Fixed

• The header of SPEC.md said 0.1.0 while profile.json said 0.2.0 — released and tagged that way. It was the first thing the new check caught, on its first run, and the reason it now holds every file carrying the version to the one in profile.json.
• The task-list entry pointed at §5.5, which stopped being "Task lists" when 0.2.0 inserted "Marked text" at that number.

Compatibility

Minor, and the whole of it is one field: read memorysmith where you read vault in the ring field of profile.json.

No notation was added, removed or given a different effect. tests/conformance.json is unchanged apart from its version, so a suite that passed against 0.2.0 passes against 0.3.0 with nothing touched. Anything citing section numbers of this profile in its own documentation should re-check them against §5 to §8.

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

v0.2.0 — The rest of the vault ring

The rest of the vault ring, and the two things the profile had been silent about on purpose without saying so.

Everything added here is already written in real vaults and does nothing in any implementation, because the profile had not specified it.

Added

• ==highlight== — marked text, carrying no meaning beyond emphasis.
• %%comment%% — text the author does not want read on the page. It leaves the reading surface and stays in the bytes, so a tool that returns the note returns it and an agent sees what a person on the page does not. That asymmetry is the decision, and it is declared rather than left to be discovered: text somebody did not want on the page is still text they wrote, and this profile asks nobody to delete bytes to make a page tidier.
• ^block-id and ![[note#^id]] — the identified block and the embed that resolves to it. The edge is exactly the edge [[note]] produces: the graph does not tell an embed from a reference apart, and does not tell a block embed from either.
• $inline$ and $$block$$ — mathematics, with the rule that a $ which is not opening or closing a formula stays text. A price and a shell variable are not formulas, and the suite carries the negatives.
• Date intervals in a query (§4.8) — created:>=2026-01-01, plus created:2026-01-01..2026-03-31 as sugar for two comparisons, both ends inclusive. One semantics: one thing to implement, one to test, one to explain. An interval over an attribute that is not a date, and one whose ends are inverted, are errors and not empty results.

Rejected, and declared as such

• Superscript and subscript (§5.9). There is nothing to inherit: GitHub writes them with raw HTML, which §5.10 declares off, and the Pandoc ~x~ / ^x^ render in no vault editor — a note written with them would read correctly here and look broken in every other tool its author uses. The ^ form would also collide with a block identifier.
• Raw HTML (§5.10). Not rendered, stored and returned as written, shown as text. Stated as a security boundary rather than as a rendering preference: a vault is written by several people and by agents, and a page that renders arbitrary HTML out of it is a script injection whose trigger is written by whoever wrote the note.

Changed

aliases gained the reason it does not resolve wikilinks (§4.4). §6.4 shrank to what is genuinely unwritten, now that most of what it listed is specified.

Compatibility

Minor, not major: no notation is removed and no effect changes. All eight new conformance cases were run against the first implementation's extractors before publication and pass unchanged, so the bump breaks no build.

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

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.