Use it

The reference implementation is on npm as plankmd. It needs Node 18 or later and has no runtime dependencies. The balance check and the drop test use two optional solvers.

Command line

Without installing anything:

npx plankmd validate model.plank.md

✓ model.plank.md: 45 planks, 3 steps, 0 errors, 0 warnings

Or install it in a project, or globally:

npm install plankmd
npm install --global plankmd

Command	What it does
plankmd validate <files…>	Checks each file. Every diagnostic names its line and its plank number.
plankmd validate <files…> --strict	Fails on warnings too.
plankmd validate <files…> --json	Machine-readable output.
plankmd validate <files…> --physics	Adds the balance check: does it stand after every plank, and how much tilt does each step withstand?
plankmd expand <file>	Lists every plank in placement order.
plankmd drop <files…>	Drop test in a physics engine.

Balance check and drop test

The balance check models planks as rigid blocks resting on each other, with friction, and solves a linear program with HiGHS. HiGHS is an optional dependency of the package, installed with it unless you pass --no-optional. Its findings are information (I-unstable, I-fragile), never errors: they are not part of the format.

The drop test uses the Rapier physics engine, which you install next to the package:

npm install @dimforge/rapier3d-compat@0.20.0
npx plankmd drop model.plank.md

Library

const PlankMD = require('plankmd')

const { valid, planks, steps, diagnostics } = PlankMD.validate(text)
for (const d of diagnostics) console.log(`${d.line}: ${d.code} ${d.message}`)

The same file works in the browser, where it defines window.PlankMD:

<script src="https://cdn.jsdelivr.net/npm/plankmd@0.1.0/src/plankmd.js"></script>

The balance check and the drop test are separate modules, which take the solver as an argument:

const PlankMDPhysics = require('plankmd/src/physics.js')
const highs = await require('highs')()
const analysis = PlankMDPhysics.analyse(highs, PlankMD.validate(text))

const RAPIER = require('@dimforge/rapier3d-compat')
await RAPIER.init()
const { createDrop } = require('plankmd/src/drop.js')

Player

The player runs in the browser, with nothing to install. It is also in the npm package and in the repository: open player/index.html from the disk, it works offline except for three.js and the optional solvers, which load from a CDN.

Address	What it opens
/player/	The first sample
/player/#corbel-bridge	A bundled sample or gallery model, by name
/player/?src=<url>	A .plank.md file from the web (served with CORS)
/player/#code=<base64url>	A model given in the link itself (UTF-8 text, base64url)
/player/?lang=fr	The player in French (en for English)

You can also paste a model into the source panel, or drop a file on the scene.

Source

Everything is on GitHub: github.com/plankmd/plankmd. Issues and pull requests are welcome; open an issue before proposing a change to the format.