Migration Walkthrough

This walkthrough shows how to adopt mdt in a project that already has documentation drift.

The example is intentionally realistic: the same installation instructions appear in a README, a Rust doc comment, and a docs page.

Before: three copies to maintain

Imagine these three files already exist.

readme.md

## Installation

npm install my-lib

src/lib.rs

#![allow(unused)]
fn main() {
//! ## Installation
//!
//! npm install my-lib
}

docs/src/getting-started.md

## Installation

npm install my-lib

At first this seems harmless. Then the command changes to npm install my-lib@latest, or the project switches to pnpm, or you want to add a second setup note.

Now you have three edits to make, and one of them eventually gets missed.

After: one source, three targets

1. Initialize mdt

mdt init

This creates a starter template file at .templates/template.t.md.

2. Define one source

Add a source block to .templates/template.t.md:

<!-- {@install} -->

## Installation

npm install my-lib@latest

<!-- {/install} -->

3. Replace the README copy with a target

<!-- {=install} -->

Old copied content

<!-- {/install} -->

4. Replace the docs-page copy with a target

<!-- {=install} -->

Old copied content

<!-- {/install} -->

5. Replace the Rust doc comment with a transformed target

#![allow(unused)]
fn main() {
//! <!-- {=install|trim|linePrefix:"//! ":true} -->
//! Old copied content
//! <!-- {/install} -->
}

If your project uses source-file targets heavily, add padding settings in mdt.toml so formatters do not collapse content awkwardly:

[padding]
before = 0
after = 0

6. Sync everything

mdt update

After the update, all three places render from the same source.

What changed structurally

Before

• each surface owned its own copy
• wording changes required repeated manual edits
• CI could not reliably detect drift

After

• the source in .templates/template.t.md becomes the source of truth
• each surface keeps only a target tag
• mdt check can fail CI when a target is stale

The day-two workflow

Once the migration is done, the maintenance loop is simple:

1. edit the source block
2. run mdt update
3. run mdt check
4. commit the synchronized result

That is the real adoption win: not just fewer edits, but a repeatable workflow that prevents drift from coming back.

A small migration strategy that works well

Do not try to template your entire docs set in one pass.

Start with content that is:

• repeated in 2 or more places
• easy to recognize when it drifts
• expensive or embarrassing when it diverges

Good first candidates:

• installation instructions
• support policy / compatibility notes
• API overview paragraphs
• badge/link sections
• CLI usage summaries

How to know the migration paid off

A migration is usually worth it when one of these becomes true:

• you can point to a source that replaced three or more manual copies
• CI now catches stale docs that previously slipped through
• README, source docs, and docs pages no longer need separate wording updates

If you want to see this pattern in a real codebase, inspect the repo-backed examples in Proof of Value.