docvars

日本語版 README はこちら

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

Supports any text-based files: Markdown, HTML, TXT, and more.

Usage

npx docvars <input> <output> [options]

Arguments

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

Options

| Option | Alias | Default | Description | | --------------- | ----- | ---------------- | --------------------------------------------------- | | --vars | -v | variables.yaml | Path to the variables YAML file | | --only | -o | **/* | Glob pattern to filter files (e.g. **/*.md) | | --exclude | -e | - | Glob pattern to exclude specific files | | --watch | -w | false | Watch for file changes and rebuild automatically | | --rename-from | -F | - | Variable name to rename from (use with --rename-to) | | --rename-to | -T | - | Variable name to rename to (use with --rename-from) | | --list-vars | -l | false | List all variables used in templates | | --dry-run | -d | false | Preview changes without writing files |

Examples

Basic usage

npx docvars ./templates ./output

Custom variables file

npx docvars ./templates ./output --vars production.yaml

Filter files

# Process only markdown files
npx docvars ./templates ./output --only "**/*.md"

# Process multiple file types
npx docvars ./templates ./output --only "**/*.{md,html,txt}"

# Process only files matching pattern
npx docvars ./templates ./output --only "api-*.md"

# Exclude files matching pattern
npx docvars ./templates ./output --exclude "draft-*.md"

By default, all text files are processed (binary files like images are automatically excluded).

Watch mode

npx docvars ./templates ./output --watch

Output:

👁 Watch mode enabled

┌───────────┬─────────────────────────┐
│ Templates │ /path/to/templates      │
│ Variables │ /path/to/variables.yaml │
└───────────┴─────────────────────────┘

Waiting for changes... (Ctrl+C to stop)

👀 Change detected: README.md (change)

✨ Build complete

┌───────────┬────────┐
│ File      │ Status │
├───────────┼────────┤
│ README.md │ ✓ done │
└───────────┴────────┘

Processed: 1 file(s)

Rename variables

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

# Simple rename
npx docvars ./templates ./output --rename-from "name" --rename-to "title"

# Rename nested variable
npx docvars ./templates ./output --rename-from "database.host" --rename-to "db.host"

# Prefix rename - renames all variables with matching prefix
# {{database}} → {{db}}
# {{database.host}} → {{db.host}}
# {{database.port}} → {{db.port}}
npx docvars ./templates ./output --rename-from "database" --rename-to "db"

Output:

✏️  Rename complete
   database → db

┌────────────────┬───────────┐
│ File           │ Status    │
├────────────────┼───────────┤
│ variables.yaml │ ✓ updated │
│ README.md      │ ✓ updated │
│ config.md      │ ✓ updated │
└────────────────┴───────────┘

Updated: 3 file(s)

List variables

Show all variables used in templates and their status:

npx docvars ./templates ./output --list-vars

Output:

📋 Variables

┌──────────────────┬──────────────────┬───────────┐
│ Variable         │ Value            │ Used in   │
├──────────────────┼──────────────────┼───────────┤
│ app.name         │ MyApp            │ README.md │
├──────────────────┼──────────────────┼───────────┤
│ api.endpoint     │ https://api.e…   │ config.md │
└──────────────────┴──────────────────┴───────────┘

Dry run

Preview what files would be created or updated without actually writing them:

npx docvars ./templates ./output --dry-run

Output:

🔍 Dry run - no files written

┌──────────────┬─────────────┐
│ File         │ Status      │
├──────────────┼─────────────┤
│ config.md    │ + create    │
│ README.md    │ ~ update    │
│ api.md       │ ~ update    │
│ changelog.md │ = unchanged │
└──────────────┴─────────────┘

Summary: 1 create · 2 update · 1 unchanged

Template Syntax

Use {{variableName}} syntax in your template 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

Array Variables

You can use arrays in your variables file and access them with index notation:

Template:

## Features

1. {{features.0}}
2. {{features.1}}
3. {{features.2}}

Variables (variables.yaml):

features:
  - User authentication
  - Data analytics
  - API integration

Output:

## Features

1. User authentication
2. Data analytics
3. API integration

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