mdd2

mdd2 is a standalone Markdown D2 validator written in Go. It parses Markdown with goldmark, finds fenced code blocks whose language is d2, and validates each block in process with D2's Go library.

The executable does not invoke or require a separately installed d2 command. The D2 parser version is pinned by go.mod, validation avoids one subprocess per fence, and diagnostics identify the corresponding Markdown source line.

Requirements

• Go 1.26 or newer to build from source

A built mdd2 executable has no additional runtime dependencies.

Install

If this repository is published at github.com/earendil-works/mdd2, install the latest version with Go's standard tool:

go install github.com/jasalt/mdd2@latest

For a reproducible release, use a version tag:

go install github.com/jasalt/mdd2@v0.1.0

Go installs the mdd2 executable in GOBIN, or in $(go env GOPATH)/bin when GOBIN is unset. Add that directory to PATH if necessary:

export PATH="$(go env GOPATH)/bin:$PATH"

The build downloads the pinned D2 and Goldmark dependencies. The installed executable does not require Go, D2, or any other runtime dependency.

To install directly from a checkout instead:

go install .

Build

go build -trimpath -ldflags='-s -w' -o mdd2 .

Usage

Show help:

./mdd2
./mdd2 --help

Validate a document:

./mdd2 path/to/document.md

On success, mdd2 reports how many D2 blocks it validated. If a block is invalid, it prints D2's diagnostic at the corresponding Markdown line and column and exits nonzero.

Only fenced blocks whose first info-string word is d2 (case-insensitive) are validated. Both backtick and tilde fences accepted by CommonMark are supported. Validation is syntax validation, matching D2's validate command: it calls d2lib.Parse and does not perform layout or rendering.

Coding agent extension

See example Pi coding agent extension at contrib/pi-mdd2-validation.ts.

Examples

Example fixtures demonstrate valid backtick and tilde fences, nested fences, longer fences, a four-backtick D2 fence containing an embedded Markdown three-backtick source block, ignored non-D2 blocks, and Markdown-positioned validation failures:

go run . testdata/examples/valid.md
go run . testdata/examples/nested.md
go run . testdata/examples/long-fence.md
go run . testdata/examples/no-d2.md
go run . testdata/examples/invalid.md # expected to exit 1

Test

go test ./...

The tests use the documents under testdata/examples/ as end-to-end fixtures for fence extraction, D2 validation, block counts, and diagnostic locations.

Platform comparison

The historical runtime implementations and startup comparison are maintained on the platform-comparison branch. See PLATFORM-COMPARISON.md there for the comparison and the rationale for making native Go the primary version.

To inspect the comparison locally:

git switch platform-comparison

License

mdd2 is distributed under the Mozilla Public License Version 2.0. See LICENSE.

The project links the D2 Go library, which is also MPL-2.0 licensed. Other Go modules retain their respective upstream licenses.