mdt

Write it once, sync it everywhere.

Markdown templates that keep your READMEs, doc comments, and docs sites in sync, with data interpolation, transformers, and CI verification.

mdt helps library and tool maintainers keep README sections, source-doc comments, and docs-site content in sync across a project. Define content once with comment-based template tags, then reuse it across markdown files, code documentation comments, READMEs, mdbook docs, and more, so your docs do not drift.

You have the same install instructions in three places:

readme.md:

## Installation

npm install my-lib

src/lib.rs:

//! ## Installation
//!
//! npm install my-lib

docs/getting-started.md:

## Installation

npm install my-lib

You update one. The others drift. CI doesn't catch it.

Define it once in a *.t.md template file (the "t" stands for template):

<!-- {@install} -->

npm install my-lib

<!-- {/install} -->

Use it everywhere:

<!-- {=install} -->

(replaced automatically)

<!-- {/install} -->

Run mdt update and all three files are in sync. Run mdt check in CI and drift is caught before merge.

• Install the prebuilt binary with npm:

npm install -g @m-d-t/cli

• Or run it without installing:

npx -y @m-d-t/cli --help

• On macOS or Linux, install with Homebrew (no Node.js or Rust needed):

brew install ifiokjr/mdt/mdt

• Or download a prebuilt binary from the latest GitHub release.
• Or build from source with Cargo (slower):

cargo install mdt_cli

mkdir my-project && cd my-project
mdt init

mdt init creates mdt.toml, a sample greeting provider in .templates/template.t.md, and, because the project has no README yet, a readme.md whose greeting consumer is already in sync.

In .templates/template.t.md:

<!-- {@greeting} -->

Hello from mdt! Edit me once, update everywhere.

<!-- {/greeting} -->

Add a consumer to any other markdown file, for example docs/intro.md:

<!-- {=greeting} -->
<!-- {/greeting} -->

mdt update
mdt check

mdt update writes the provider's content into every greeting consumer. mdt check exits non-zero when a consumer is out of date or names no provider, so run it in CI.

• Quick Start
• Template Syntax
• CLI Reference
• Data Interpolation
• Transformers
• Configuration
• CI Integration
• Source File Support
• Proof of Value
• Migration Walkthrough

The mdt binary carries an agent skill that teaches assistants the tag syntax, transformers, configuration, and workflow for the installed version. Any agent that can run shell commands can load it:

mdt skill              # print the skill
mdt skill --reference  # print the detailed reference

Or install it where your agent looks for skills:

mdt skill --install .claude/skills   # Claude Code
mdt skill --install .agents/skills   # Codex and other agents
mdt skill --install .github/skills   # GitHub Copilot

The same skill is published as @m-d-t/skills for Pi (pi install npm:@m-d-t/skills). For MCP setup, run mdt assist <claude|cursor|copilot|pi|generic>; see Assistant Setup.

devenv provides a reproducible development environment for this project. Follow its getting started instructions, then enter the environment from the repository root:

devenv shell

Run install:all to install the remaining tooling. Repository commands such as build:all, test:all, lint:all, and fix:all are available inside the shell.