Crate mdt_core 

mdt_core is the core library for the mdt template engine. It provides the lexer, parser, project scanner, and template engine for processing markdown template tags. Content defined once in provider blocks can be distributed to consumer blocks across markdown files, code documentation comments, READMEs, and more.

Processing Pipeline

Markdown / source file
  → Lexer (tokenizes HTML comments into TokenGroups)
  → Pattern matcher (validates token sequences)
  → Parser (classifies groups, extracts names + transformers, matches open/close into Blocks)
  → Project scanner (walks directory tree, builds provider→content map + consumer list)
  → Engine (matches consumers to providers, applies transformers, replaces content)

Modules

• config — Configuration loading from mdt.toml, including data source mappings, exclude/include patterns, and template paths.
• project — Project scanning and directory walking. Discovers provider and consumer blocks across all files in a project.
• [source_scanner] — Source file scanning for consumer tags inside code comments (Rust, TypeScript, Python, Go, Java, etc.).

Key Types

• Block — A parsed template block (provider or consumer) with its name, type, position, and transformers.
• Transformer — A pipe-delimited content filter (e.g., trim, indent, linePrefix) applied during injection.
• ProjectContext — A scanned project together with its loaded template data, ready for checking or updating.
• MdtConfig — Configuration loaded from mdt.toml.
• CheckResult — Result of checking a project for stale consumers.
• UpdateResult — Result of computing updates for consumer blocks.

Data Interpolation

Provider content supports minijinja template variables populated from project files. The mdt.toml config maps source files to namespaces:

[data]
pkg = "package.json"
cargo = "Cargo.toml"

Then in provider blocks: {{ pkg.version }} or {{ cargo.package.edition }}.

Supported formats: JSON, TOML, YAML, and KDL.

Quick Start

use mdt_core::project::scan_project_with_config;
use mdt_core::{check_project, compute_updates, write_updates};
use std::path::Path;

let ctx = scan_project_with_config(Path::new(".")).unwrap();

// Check for stale consumers
let result = check_project(&ctx).unwrap();
if !result.is_ok() {
    eprintln!("{} stale consumer(s) found", result.stale.len());
}

// Update all consumer blocks
let updates = compute_updates(&ctx).unwrap();
write_updates(&updates).unwrap();

Re-exports

pub use config::*;

pub use project::*;

Modules

config

project

Structs

Block

CheckResult

Result of checking a project for stale consumers.

OrderedFloat

A float wrapper that implements Eq via approximate comparison, allowing Argument to derive PartialEq cleanly.

Point

One place in a source file. This is taken from the [unist] crate with the Copy trait added.

Position

Location of a node in a source file. This is taken from the unist crate with the Copy trait added.

RenderError

A template render error associated with a specific consumer block.

StaleEntry

A consumer entry that is out of date.

TemplateWarning

A warning about undefined template variables in a provider block.

Transformer

UpdateResult

Result of updating a project.

Enums

Argument

BlockType

MdtError

ParseDiagnostic

A diagnostic produced during parsing. These are issues that don’t prevent parsing from completing but indicate problems in the source content.

TransformerType

Functions

apply_transformers

Apply a sequence of transformers to content.

build_blocks_from_groups

Build blocks from already-tokenized groups. This is the shared logic used by both markdown parsing and source file scanning.

build_blocks_from_groups_lenient

Like build_blocks_from_groups, but silently discards unclosed blocks instead of returning an error. Used for source files where HTML comments may appear in string literals without matching close tags.

build_blocks_from_groups_with_diagnostics

Build blocks from token groups, collecting diagnostics instead of hard-erroring. Unknown transformers and unclosed blocks are reported as diagnostics rather than causing parse failure.

build_render_context

Build a data context that merges base project data with block-specific positional arguments. Consumer argument values are bound to the provider’s declared parameter names, with block args taking precedence over data variables. Build a data context that merges base project data with block-specific positional arguments. Returns None if the argument count doesn’t match.

check_project

Check whether all consumer blocks in the project are up to date. Consumer blocks that reference non-existent providers are silently skipped. Template render errors are collected rather than aborting, so the check reports all problems in a single pass.

compute_updates

Compute the updated file contents for all consumer blocks.

extract_html_comments

Extract HTML comments (<!-- ... -->) from raw text content, returning Html nodes with correct byte positions. This is used for source files where the markdown AST parser won’t find HTML comments inside code comments.

find_undefined_variables

Find template variables referenced in content that are not defined in data. Returns the list of undefined variable names (with nested attribute access like "pkgg.version"). This uses minijinja’s static analysis to detect undeclared variables, so it does not depend on runtime control flow.

get_html_nodes

parse

Parse markdown content and return all blocks (provider and consumer) found within it.

parse_source

Parse source code content (non-markdown) for mdt blocks by extracting HTML comments directly from the raw text.

parse_source_with_diagnostics

Parse source code content and return blocks together with diagnostics. When filter is enabled, HTML comments inside fenced code blocks (within doc comments) are excluded from scanning.

parse_with_diagnostics

Parse markdown content and return blocks together with diagnostics. Unlike parse(), this does not error on unclosed blocks — instead they are collected as diagnostics.

render_template

Render provider content through minijinja using the given data context. If data is empty or the content has no template syntax, returns the content unchanged.

validate_transformers

Validate that all transformer arguments are well-formed. Returns an error for the first invalid transformer found.

write_updates

Write the updated contents back to disk.

Type Aliases

AnyEmptyResult

AnyError

AnyResult

MdtResult