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 270 examples in the gallery (all of Examples/, rendered live), or flip through the animated gallery where every example is a card showing its motion as a GIF.

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 { parse, serialize } from "@corvidlabs/threemd";

const document = parse(source);
console.log(document.axis); // "time"

// 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)
}

// 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 html <file>       # render the document to HTML on stdout

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 all 270 example documents across 13 axis types - from medical charts, weather, and file transfers to games, maps, and animations. Browse them all live in the gallery viewer; a few highlights:

• 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.

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.