Everything you need to read and write .3md - Markdown with one free Z axis you name yourself.
A 3md document is plain UTF-8 text with three regions in order: a required frontmatter block, an optional Markdown preamble, then zero or more planes. Here is a complete, minimal document.
--- 3md: 1.0 axis: time title: My Week --- Optional preamble Markdown. @plane z=0 label="Monday" # Monday - [ ] Standup @plane z=1 label="Tuesday" # Tuesday
The 3md: line is the magic marker - a document without it is not 3md. The axis names what depth means (here, time). Each @plane directive slices the document along Z; everything between directives is ordinary Markdown.
3md is Markdown extended along a single free axis, called the Z axis. A document is a stack of planes, and each plane is ordinary Markdown. The grammar is frozen at version 1.0.
The document MUST begin with a frontmatter block: a line containing exactly ---, one or more key: value lines, and a closing line containing exactly ---. It is its own tiny, flat, line-based mini-format - it only looks like YAML. It is NOT YAML: there is no nesting, no lists, no anchors, and no multi-line values. Each line is split on the first colon; blank lines and lines starting with # are ignored.
3md (required) - the format version string and the file's magic marker. It is recorded but never validated, so parsers are version-lenient: a 3md: 0.1 document stays valid.axis (optional) - the meaning of the Z axis. Defaults to layer. Trimmed and lowercased; any string is permitted.title (optional) - a human-readable title.--- 3md: 1.0 # required - the magic marker axis: frame # optional - defaults to "layer" title: Bouncing dot author: leif # free metadata, always a string fps: "12" # quotes are stripped; value stays a string ---
A plane begins with a directive line whose first whitespace-delimited token is @plane, followed by space-separated key=value attributes. The directive MUST begin at column 0 and MUST lie outside a fenced code block. Every line after it, up to the next @plane or end of file, is that plane's Markdown body (leading and trailing blank lines are trimmed).
z (required) - a finite decimal giving the plane's position on the Z axis. Optional sign, digits with an optional fraction, optional exponent (for example 0, -2.5, 1e3). Hex, inf, and nan are rejected. Two planes MUST NOT share the same z.x, y (optional) - finite decimals giving an in-plane offset for spatial viewers.label (optional) - a human-readable name for the plane.\\ and \" are escapes.@plane z=2 x=-16 y=-26 label="backdrop" author="counsel" # Backdrop midnight curtain
If a document has frontmatter but no @plane directives, the entire body is one implicit plane at z = 0. A normal Markdown file with a 3md header is a valid one-plane document.
--- 3md: 1.0 title: A plain note --- # Just Markdown No directives, so this whole body is one plane.
A plane body MAY reference another plane by its z position with a double-bracket link. The grammar is [[z= followed by a finite decimal, an optional | and link text, then ]]. The matching regular expression is \[\[z=([^\]|]+)(?:\|([^\]]*))?\]\]. If the captured target is not a finite decimal, the sequence is not a link and stays literal body text.
See [[z=2]] for the details, or jump [[z=0|back to the start]].
The core parser leaves links in the body verbatim. Implementations expose them through a separate extraction step that reports the source z, target z, optional text, and whether a plane with that target exists (targetExists) - which makes dangling-reference validation and navigation portable across implementations.
Three parsers are kept in lockstep by a shared conformance suite: a cross-platform Swift parser (ThreeMD), a TypeScript port, and a Rust crate. Pick your stack.
// Package.swift .package( url: "https://github.com/CorvidLabs/3md", from: "1.0.0" ) // then depend on the product .product(name: "ThreeMD", package: "3md")
# point the scope at the GitHub registry once echo "@corvidlabs:registry=https://npm.pkg.github.com" >> .npmrc bun add @corvidlabs/threemd
cargo add threemd
The threemd command-line tool ships with the package and self-documents (run threemd --help). A path of - reads from standard input.
threemd validate <file> # parse; print "ok" or exit non-zero threemd info <file> # version, axis, title, plane positions threemd html <file> # render the document to HTML on stdout
Install the CLI via Homebrew with brew install CorvidLabs/tap/threemd. With the Swift package you can also run it directly: swift run threemd validate <file>.
Learn by reading real documents that span many axis types - time planners, frame animations, layered annotations, and spatial scenes wired with cross-plane links.