Parsers and conformance

Reference

Four libraries

ThreeMD 2.2.1 is the current release. Tag v2.2.1 was published on GitHub on 2026-10-09. The Godot 4.7 addon was added in 2.2.0. Text grammar 1.0 stays frozen.

3md ships four libraries:

ThreeMD, the canonical Swift parser. The CLI and reference behavior are built on it. The package pin below is from: "2.2.1".
A TypeScript port, published as @corvidlabs/threemd at 2.2.1. It also backs the <three-md> web component (@corvidlabs/three-md-element, also 2.2.1).
A Rust crate, threemd. The manifest in the GitHub repo reads 2.2.1. crates.io serves 2.2.1.
A GDScript addon for Godot 4.7.

Swift, TypeScript, and Rust stay in the hosted conformance lane. They share one text contract: 43 portable test vectors that each of those three runs. The vectors are the authoritative definition of conforming behavior. Any change that would alter their expected results is a breaking change, so a document parses the same way no matter which of those three reads it.

GDScript is additional. It is checked locally on Godot 4.7.2. Hosted CI does not install Godot.

Each implementation also keeps its own unit tests in addition to the shared vectors.

Swift (the canonical parser)

Add the package to your Package.swift:

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

Depend on the ThreeMD library product:

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

Then parse, inspect, and round-trip:

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

// Serializing and parsing again yields an equivalent document:
let text = Serializer().render(document)

TypeScript / JavaScript

The TypeScript port is published to the public npm registry as @corvidlabs/threemd at 2.2.1, so it installs with no token:

bun add @corvidlabs/threemd

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

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

The <three-md> web component (@corvidlabs/three-md-element, 2.2.1) builds on this parser; see the viewer docs. If you only want rendering and not the data API, the element bundle includes the parser already.

Rust

The threemd crate is on crates.io at 2.2.1. The Rust manifest in the GitHub repo reads 2.2.1. cargo add threemd installs the crates.io release.

cargo add threemd

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

GDScript (Godot 4.7)

Copy gdscript/addons/threemd from tag v2.2.1 into the project and enable the plugin. The addon targets Godot 4.7. It is checked locally on Godot 4.7.2. Hosted CI does not install Godot.

Limits of this port:

LZFSE is refused.
Composition editing is replaceEntry only.
Diagnostics are not fully ported.
Library scripts do not open files. Only ThreeMDFiles reads a chosen path.
The addon does not spawn gameplay.

Which one to use

Building a Swift app or the CLI: use ThreeMD at 2.2.1.
Web, Node, or Bun tooling, or rendering in the browser: use the TypeScript package (or the web component). Both npm packages are 2.2.1.
Native, embedded, or performance-sensitive tooling: use the Rust crate. cargo add threemd installs the crates.io release, which is 2.2.1. The manifest in the GitHub repo reads 2.2.1.
A Godot 4.7 project: copy the GDScript addon from tag v2.2.1 and enable the plugin. The check runs locally on Godot 4.7.2.

The shared text contract is green in Swift, TypeScript, and Rust, so those three can be mixed and still agree. GDScript is additional and local.