3md

Markdown with a Z axis. A .3md file is ordinary Markdown extended along one free axis: stack your content into planes and tell the reader what the depth means. Time for a daily planner. Frames for an animation. Layers for annotations. Space for a scene.

Try the interactive demo (also on corvidlabs.xyz/3md), open the viewer & editor (paste any .3md and share a link), read the docs, or browse the curated animated gallery, or flip through the animated deck where the strongest examples appear as motion cards.

This repo eats its own dog food: every doc here is also combined into one docs.3md (each Markdown file is a plane). GitHub can't preview .3md natively, so open all the docs in the 3md viewer and scrub through them.

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

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

This repository holds the format specification (SPEC.md), example documents (Examples/), three parsers kept in lockstep (ThreeMD, a cross-platform Swift parser; a TypeScript port in js/; and a Rust crate in rust/), and a shared cross-implementation conformance suite (conformance/) that all three pass.

Why

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. 3md keeps Markdown's plain-text simplicity and adds one axis, with the author declaring what that axis means. Nothing comparable ships today; the closest prior art renders existing Markdown into 3D rather than giving the text a depth dimension of its own.

Installation

Swift Package Manager

Add the package to your Package.swift:

.package(url: "https://github.com/CorvidLabs/3md", from: "1.0.0")

Then depend on the ThreeMD library product:

.product(name: "ThreeMD", package: "3md")

JavaScript / TypeScript

A faithful TypeScript port of the Swift parser is published to GitHub Packages, alongside the <three-md> web component (@corvidlabs/three-md-element). All three implementations (Swift, TypeScript, and the Rust crate in rust/) are kept in sync by the shared conformance suite (conformance/).

GitHub Packages requires a GitHub token to install (even for public packages), so point the @corvidlabs scope at the registry and add a token in a project or user .npmrc, then install:

echo "@corvidlabs:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> .npmrc
bun add @corvidlabs/threemd

No install needed just to use it: try the hosted editor and viewer, or load the self-contained component bundle directly with <script type="module" src=".../three-md.js">.

import { danglingLinks, linkGraph, parse, serialize } from "@corvidlabs/threemd";

const document = parse(source);
console.log(document.axis); // "time"
console.log(danglingLinks(document)); // unresolved [[z=N]] references
console.log(linkGraph(document));     // compact source -> target edge list

// Round trips back to text:
const text = serialize(document);

Rust

The threemd crate is published on crates.io with zero runtime dependencies:

cargo add threemd

let document = threemd::parse(source)?;
println!("{}", document.axis); // "time"

Library usage

import ThreeMD

let document = try Parser().parse(source)
print(document.axis)          // Axis(rawValue: "time")
for plane in document.planesByZ {
    print(plane.label ?? "", plane.body)
}
print(document.danglingLinks()) // unresolved [[z=N]] references
print(document.linkGraph())     // compact source -> target edge list

// Round trips back to text:
let text = Serializer().render(document)

Command-line tool

The threemd CLI ships with the package and self-documents (run threemd --help). A path of - reads from standard input.

swift run threemd validate <file>   # parse a file; print "ok" or exit non-zero with the error
swift run threemd info <file>       # print version, axis, title, and each plane's position
swift run threemd links <file>      # list cross-plane links and dangling references
swift run threemd check-links <file> # exit non-zero when any [[z=N]] target is missing
swift run threemd html <file>       # render the document to HTML on stdout

validate, info, links, and check-links also accept --json for CI, editor integrations, and other tooling.

Format at a glance

• A required --- frontmatter block declares 3md: (the version, and the file's magic marker), an optional axis:, an optional title:, and free metadata.
• @plane z=... label="..." directives start planes; the Markdown between directives is the plane body.
• A plain Markdown file with a 3md header and no directives is a valid one-plane document.

See SPEC.md for the full grammar and conformance rules.

Examples

The Examples/ directory holds the source example documents across 13 axis types - from medical charts, weather, and file transfers to games, maps, and animations. The gallery viewer highlights the curated animated set; a few source examples:

• daily-planner.3md - axis: time, one plane per day.
• animation.3md - axis: frame, one plane per frame.
• layered-notes.3md - axis: layer, stacked overlay layers.
• dungeon.3md - axis: space, rooms wired with [[z=N]] cross-plane links.
• tide-pool.3md - axis: depth, authored by an AI from the spec alone (see docs/PROOF.md).
• game-of-life.3md - axis: frame, a real 24-generation Conway run (animates, and renders as a 3D object in the viewer's blend view).
• 3md-in-3md.3md - 3md explained in 3md, with a @plane inside a code fence.
• Plus recipe, changelog, resume, and kanban.

Want to see it work? docs/PROOF.md records how 3md was verified for machines (a blind AI authored valid 3md from the spec; all three parsers agreed) and for people (plain, readable, diffable text).

Development

This repo uses the CorvidLabs trust toolchain. The single gate is:

fledge lanes run verify

which runs the Swift format check, build, and tests plus the Rust crate. See AGENTS.md for the standing rules every contributor and agent follows. The same gate also checks TypeScript parser parity, generated web-component bundle drift, VS Code grammar tests, and spec-sync. Browser UI tests are exposed separately with fledge lanes run ui.

Each implementation has its own tests (the Swift suite has 122 tests, the TypeScript suite 76), and all three implementations run the shared 43-vector conformance suite in conformance/, which is the cross-implementation contract that keeps the parsers behaving identically.

Status

The format and spec are at version 1.0 (stable, frozen grammar). The latest release is v1.0.0. Older 3md: 0.1 documents remain valid: the parser is version-lenient and never rejects a document by its version string.

License

MIT (c) CorvidLabs. See LICENSE.