mdt

manage markdown templates across your project

mdt helps library and tool maintainers keep README sections, source-doc comments, and docs-site content synchronized 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.

Installation

• Install with npm:

npm install -g @ifi/mdt

• Or run it without installing:

npx @ifi/mdt --help

• Or download a prebuilt binary from the latest GitHub release
• Or install with Cargo:

cargo install mdt_cli

See It in Practice

• Proof of Value shows how this repository already syncs README content, Rust source docs, and mdBook pages from shared providers.
• Migration Walkthrough shows a before/after adoption path for moving repeated docs onto mdt.

Template Syntax

Provider tag (defines a template block in *.t.md definition files):

<!-- {@blockName} -->

Content to inject

<!-- {/blockName} -->

Consumer tag (marks where content should be injected):

<!-- {=blockName} -->

This content gets replaced

<!-- {/blockName} -->

Inline tag (provider-free interpolation using configured data):

Current version: <!-- {~version:"{{ package.version }}"} -->0.0.0<!-- {/version} -->

| Artifact | Version                                                                   |
| -------- | ------------------------------------------------------------------------- |
| mdt_cli  | <!-- {~cliVersion:"{{ package.version }}"} -->0.0.0<!-- {/cliVersion} --> |

Filters and pipes: Template values support pipe-delimited transformers:

<!-- {=block|prefix:"\n"|indent:"  "} -->

Available transformers: trim, trimStart, trimEnd, indent, prefix, suffix, linePrefix, lineSuffix, wrap, codeBlock, code, replace, if.

CLI Commands

• mdt init [--path <dir>] — Create a sample .templates/template.t.md file and starter mdt.toml.
• mdt check [--path <dir>] [--verbose] — Verify all consumer blocks are up-to-date. Exits non-zero if any are stale.
• mdt update [--path <dir>] [--verbose] [--dry-run] — Update all consumer blocks with latest provider content.
• mdt info [--path <dir>] — Print project diagnostics and cache observability metrics.
• mdt doctor [--path <dir>] [--format text|json] — Run health checks with actionable hints, including cache validity and efficiency.
• mdt assist <assistant> [--format text|json] — Print an official assistant setup profile with MCP config and repo-local guidance.
• mdt lsp — Start the mdt language server (LSP) for editor integration. Communicates over stdin/stdout.
• mdt mcp — Start the mdt MCP server for AI assistants. Communicates over stdin/stdout.

Diagnostics Workflow

• Run mdt info first to inspect project shape, diagnostics totals, and cache reuse telemetry.
• Run mdt doctor when you need actionable health checks and remediation hints (config/data/layout/cache).
• Use MDT_CACHE_VERIFY_HASH=1 when troubleshooting cache consistency issues and comparing reuse behavior.

Crates

| Crate | Description | | ------------------------ | ------------------------------------------------------------------------------ | | mdt_core | Core library — lexer, parser, scanner, and template engine | | mdt_cli | CLI tool — mdt binary for managing templates | | mdt_lsp | LSP server — editor integration with diagnostics, completions, hover, and more | | mdt_mcp | MCP server — AI assistant integration via the Model Context Protocol |

Contributing

devenv is used to provide a reproducible development environment for this project. Follow the getting started instructions.

To automatically load the environment you should install direnv and then load the direnv.

# The security mechanism didn't allow to load the `.envrc`.
# Since we trust it, let's allow it execution.
direnv allow .

At this point you should see the nix commands available in your terminal. Run install:all to install all tooling and dependencies.