twain-md

Twain's offline Markdown/MDX renderer, packaged as a command-line tool for CI pipelines and coding agents. It runs the exact rendering pipeline the desktop app uses, so what the CLI reports is what the app shows. The renderer is bundled into the package, so it works standalone with no extra dependencies.

Install

npm i -g twain-md

Or run it without installing:

npx twain-md check docs/

From a repo checkout, node cli/twain-md.mjs ... works the same way.

Requires Node 18 or newer. No network access is made unless you ask for it (see --remote below).

check

Report diagnostics for one or more files: MDX imports and expressions, unknown components, and broken local links or missing images. Exits 1 when there are findings, 0 when clean, so it drops straight into CI.

twain-md check README.md docs/*.mdx
twain-md check --json doc.mdx          # machine-readable output
twain-md check --strict doc.mdx        # treat informational findings as failures
twain-md check --remote doc.mdx        # also probe remote links and images
twain-md check --remote --timeout 3000 --concurrency 4 doc.mdx

--remote is opt-in and offline-safe: network errors never crash the run, and without the flag no requests are made. --timeout is per request in milliseconds; --concurrency caps parallel probes.

Give check a directory instead of files and it runs in project mode: every Markdown/MDX file under the folder, plus the cross-file checks a single file cannot see. On top of the per-file findings it reports broken anchor fragments, a link like other.md#section where the target file has no heading with that slug. The output shape and exit code are the same as for files.

twain-md check docs/                    # project mode
twain-md check docs/ --json

The walk skips the same noise directories the app's workspace does (node_modules, .git, dist, build, and so on) and hidden entries, caps at 5,000 files, and marks truncated rather than silently dropping the rest.

inventory

Build a project inventory for a folder of Markdown/MDX: per file its headings with their rendered anchor slugs, frontmatter, links and images with line numbers, MDX component usage, and task-list items; project-wide the link graph (orphan files with nothing linking to them), broken cross-file links, broken anchors, and a task rollup. This is the one call a coding agent makes to learn the shape of a doc set before it starts editing.

twain-md inventory docs/                # human summary
twain-md inventory docs/ --json         # the full structured inventory

open

Hand a file to the running Twain app through its twain-md:// URL scheme (macOS only). --changes opens it with its changes marked against the last saved version; --print writes the URL instead of launching, for scripting.

twain-md open notes.md
twain-md open notes.md --changes
twain-md open notes.md --print          # prints twain-md://open?path=...

render

Render a file to a single self-contained HTML page written to stdout, or to a file with -o. The app stylesheet and KaTeX CSS are inlined and local images are embedded as data URIs, so the output travels on its own.

twain-md render doc.mdx                 # HTML to stdout
twain-md render doc.mdx -o doc.html     # HTML to a file

export

Like render, but applies a profile that controls theme, font, reading width and whether assets are embedded.

twain-md export doc.mdx -o doc.html --profile dark
twain-md export doc.mdx --profile ./my-profile.json

A profile is a small JSON object; every field is optional:

| Field | Values | Default | | ------------- | ------------------------------------------------- | -------- | | theme | auto, light, dark, sepia, high-contrast | auto | | font | sans, serif | sans | | width | narrow, normal, wide | normal | | embedAssets | true, false | true | | title | any string | document title |

theme: auto follows the reader's prefers-color-scheme. Setting embedAssets to false leaves image src attributes untouched rather than embedding them.

The --profile value resolves in this order:

1. A path or a .json file that exists on disk.
2. A user profile at $XDG_CONFIG_HOME/twain-md/profiles/<name>.json (falling back to ~/.config/twain-md/profiles/<name>.json).
3. A built-in profile: default, dark, sepia, or print.

An unknown profile name is a usage error.

Licence

MIT. See LICENSE.

Third-party software

The bundled renderer is built from open-source packages. Their exact versions and full licence texts ship in the package at vendor/THIRD-PARTY-LICENSES.txt.