Template Files

Template files are the single source of truth for shared content. They hold source blocks that define the content distributed to consumers throughout your project.

Naming convention

Template files use the .t.md extension:

template.t.md
docs.t.md
shared/api-docs.t.md

Any file ending in .t.md is treated as a template file. The t stands for “template.”

Only *.t.md files can contain source blocks. Source tags ({@name}) in other files are ignored. This prevents accidental content injection from arbitrary files and gives you one place to look for content definitions.

Structure

A template file is regular markdown containing one or more source blocks:

<!-- {@installGuide} -->

Install the package:

  npm install my-lib

<!-- {/installGuide} -->

<!-- {@contributing} -->

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

<!-- {/contributing} -->

Content outside source blocks is ignored by mdt. Use it for notes, organization, or documentation about the templates themselves.

Template variables

Provider content can include minijinja template variables that reference data from project files. This requires an mdt config file (mdt.toml, .mdt.toml, or .config/mdt.toml). See Data Interpolation for details.

<!-- {@installGuide} -->

Install `{{ package.name }}` version {{ package.version }}:

  npm install {{ package.name }}@{{ package.version }}

<!-- {/installGuide} -->

When mdt renders this source, {{ package.name }} and {{ package.version }} are replaced with actual values from package.json (or whichever file is mapped to the package namespace).

Where to place template files

Template files can live anywhere in your project directory.

Canonical recommendation: use .templates/ at the project root.

Canonical layout (.templates/):

my-project/
  .templates/
    template.t.md
    docs.t.md
  readme.md

Compatible alternative (templates/):

my-project/
  templates/
    docs.t.md
    examples.t.md
  readme.md

Legacy single template at the root (still supported):

my-project/
  template.t.md
  readme.md

You can also configure explicit template paths in mdt.toml:

[templates]
paths = ["shared/templates"]

Multiple template files

A project can have multiple template files. Source names must be unique across all template files. If two files define {@installGuide}, mdt reports an error:

error: duplicate source `installGuide`: defined in `docs.t.md` and `api.t.md`

Each piece of content has exactly one source of truth.