Markdown with a Z axis

Markdown is two dimensional. Plenty of documents are not. A planner moves through time. An annotated contract has overlay layers. An ASCII animation is a stack of frames. A dungeon map has rooms in space. All of those want a third axis, and Markdown gives you nowhere to put it.

So I built 3md: ordinary Markdown extended along one free Z axis. You stack content into planes and you tell the reader what the depth means. The axis is whatever you want it to be: time, frames, layers, depth, space, slides, floors. The file says which.

The whole format fits in your head

If you know Markdown, you know 3md. A document is a short frontmatter header, then @plane lines that slice the file along Z, with plain Markdown in between.

---
3md: 1.0
axis: time
title: My Week
---
@plane z=0 label="Monday"
# Monday
- [ ] Standup

@plane z=1 label="Tuesday"
# Tuesday

The version line is the magic marker. axis names what depth means. Each @plane starts a plane, and everything between directives is the plane's body. That is the whole thing. A plain Markdown file with a 3md header and no directives is a valid one-plane document, so you never start from a blank slate.

Two readers, one file

The bet behind 3md is that a format is only worth shipping if both of its readers are happy: the machine that parses it and the person who writes it. So I held the format to both, and wrote the evidence down in PROOF.md.

For the machine, 3md has three independent parsers kept in lockstep by one shared conformance suite: a Swift library, a TypeScript port, and a Rust crate. If they ever disagree, a vector fails. Right now they are all green (Swift 122 tests, TypeScript 76, Rust plus the 43-vector suite).

Then I ran a blind test. I gave a fresh AI agent exactly one file, the spec, and nothing else: no examples, no parser source. I asked it to invent an original document. It wrote a tide pool read as four depth planes, from the glittering surface film down to the dark floor, with cross-plane links and per-plane coordinates. I fed that document to all three parsers, which had no hand in writing it. They agreed exactly: same axis, same four planes, same attributes, down to the placement numbers.

That is the AI half of the proof. A model that has only read the spec writes correct 3md on the first try, because the grammar is small enough to learn from one page and the parsed shape is flat and predictable. The document it wrote now ships as Examples/tide-pool.3md.

The human half is simpler to argue and just as important. 3md is plain text. Open any .3md file and the depth is legible as a top-to-bottom read, before any tool is involved. It diffs cleanly, it passes through code review unchanged, and you can write it by hand. The blind-author test is itself proof that the rules fit in a head.

See the axis

Reading about a third axis only gets you so far, so the format ships with an interactive lab. Pick an axis, scrub the slider, and the focused plane comes to the front while the rest recede into depth. The same engine renders 100 examples across every meaning of Z, from daily planners to scene layouts to changelogs.

3md is open source under MIT. There is a CLI (brew install CorvidLabs/tap/threemd), the three libraries, a frozen 1.0 spec, and docs. It is a small format with a narrow idea: give Markdown one more axis, and let the author say what it means.

Try it: corvidlabs.github.io/3md.