md-template-vars

A CLI tool to replace {{variables}} in Markdown templates with values from a YAML file.

Installation

npm install -g md-template-vars

Or use with npx:

npx md-template-vars ./templates ./output

Usage

md-template-vars <input> <output> [options]

Arguments

| Argument | Description | | -------- | ----------------------------------------- | | input | Input directory containing template files | | output | Output directory for processed files |

Options

| Option | Default | Description | | --------------- | ---------------- | --------------------------------------------------- | | --vars | variables.yaml | Path to the variables YAML file | | --include | - | Glob pattern to include specific files | | --exclude | - | Glob pattern to exclude specific files | | --watch | false | Watch for file changes and rebuild automatically | | --rename-from | - | Variable name to rename from (use with --rename-to) | | --rename-to | - | Variable name to rename to (use with --rename-from) |

Examples

Basic usage

md-template-vars ./templates ./output

Custom variables file

md-template-vars ./templates ./output --vars production.yaml

Filter files

# Include only files matching pattern
md-template-vars ./templates ./output --include "api-*.md"

# Exclude files matching pattern
md-template-vars ./templates ./output --exclude "draft-*.md"

Watch mode

md-template-vars ./templates ./output --watch

This will watch for changes in:

• Template files in the input directory
• The variables YAML file

When changes are detected, templates are automatically rebuilt.

Rename variables

Rename a variable across all template files and the variables YAML file:

# Simple rename
md-template-vars ./templates ./output --rename-from "name" --rename-to "title"

# Rename nested variable
md-template-vars ./templates ./output --rename-from "database.host" --rename-to "db.host"

This updates:

• All {{oldName}} occurrences in template files → {{newName}}
• The key in the variables YAML file

Template Syntax

Use {{variableName}} syntax in your Markdown files:

Template (templates/hello.md):

# Hello {{name}}

Welcome to {{project}}!

Variables (variables.yaml):

name: World
project: My Project

Output (output/hello.md):

# Hello World

Welcome to My Project!

Nested Variables

You can use nested objects in your variables file and access them with dot notation:

Template:

# {{app.name}}

Database: {{database.host}}:{{database.port}}

Variables (variables.yaml):

app:
  name: My App

database:
  host: localhost
  port: 5432

Output:

# My App

Database: localhost:5432

Error Handling

| Case | Behavior | | --------------------------- | --------------------------------------------------- | | Undefined variable | Warning is displayed, variable syntax is kept as-is | | Same input/output directory | Error and exit | | Variables file not found | Error and exit |

License

MIT