Proof of Value

This repository is the best example of mdt solving a real problem. It uses source blocks from .templates/*.t.md to keep repeated content in sync across multiple surfaces:

• root and crate READMEs
• crate-level Rust docs
• mdBook pages

The value proposition in one repo: write shared content once, then fan it out wherever people actually read it.

1. README synchronization

The source block mdtCliUsage lives in .templates/overview.t.md.

It is consumed in multiple README-style surfaces:

• readme.md
• mdt_cli/readme.md

That means the command list and diagnostics workflow stay aligned without copying edits by hand.

2. Source-doc synchronization

The source block mdtLspOverview also lives in .templates/api-and-install.t.md, but it fans out into both markdown and Rust source docs:

• mdt_lsp/readme.md
• mdt_lsp/src/lib.rs

The source file uses a transformer chain so markdown content becomes Rust crate documentation comments:

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

The same pattern is used for:

• mdt_core/src/lib.rs
• mdt_mcp/src/lib.rs
• mdt_core/src/parser.rs

The payoff: you do not maintain one explanation for README readers and a second for API docs readers.

3. Docs-site synchronization

The mdBook docs also consume shared source blocks.

For example, mdtInlineBlocksGuide is reused in more than one docs page:

• docs/src/reference/template-syntax.md
• docs/src/advanced/inline-blocks.md

This keeps the conceptual explanation of inline blocks consistent across both a reference page and a guide page.

Why this matters

Without mdt, these edits drift in predictable ways:

• the README gets the newest wording
• the source-doc comment keeps an older explanation
• the docs site uses slightly different examples
• command lists diverge across pages

With mdt, one source update can refresh all of those targets in one run:

mdt update
mdt check

What to look at in this repo

If you are evaluating adoption, inspect these files together:

Shared sources

• .templates/overview.t.md and .templates/api-and-install.t.md

README targets

• readme.md
• mdt_cli/readme.md
• mdt_core/readme.md
• mdt_lsp/readme.md
• mdt_mcp/readme.md

Source-doc consumers

• mdt_core/src/lib.rs
• mdt_core/src/parser.rs
• mdt_lsp/src/lib.rs
• mdt_mcp/src/lib.rs

Docs-site targets

• docs/src/reference/template-syntax.md
• docs/src/advanced/inline-blocks.md

The pitch

Describe mdt to a teammate like this:

We keep a few pieces of documentation repeated across our README, crate docs, and docs site. mdt lets us define those pieces once, reuse them everywhere, and verify in CI that they never drift apart.

If that description matches your project, the tool is worth trying.