A package manager for markdown. Compose prompts, documentation, configs, and any other structured text from reusable modules with declared
requires/suggests/conflicts— plait figures out the right set and emits them in the right order.
Status: v1.0.0 released — feature-complete; active maintenance. Bug
fixes, dependency updates, and small enhancements are ongoing; larger
changes are being evaluated against real-world feedback. See
docs/roadmap.md for what is and isn't on the
table.
The crates.io registry name is
plaitedbecause the originalplaitname is owned by an unrelated HTML templating crate. The CLI binary, the libraryuse plait::...API, the~/.config/plait/config directory, and theplait.tomlproject file all keep the original name — only the registry slug differs.
Markdown composition and dependency resolution are both well-trodden
problems, but plait is the only tool that combines them. If you've ever
wanted cargo-style declared constraints applied to prose instead of
code, this is that tool.
| Tool | Markdown + frontmatter | Dependency resolution | Conflict semantics | Multi-format output |
|---|---|---|---|---|
| plait | Yes | Requires / suggests / conflicts, topo-sorted | Yes | Markdown, text, JSON, YAML, HTML |
| Hugo / Zola / mdBook | Yes | No (include directives only) | No | Site HTML only |
| Antora | AsciiDoc | Module catalog, but no constraint solver | No | Site HTML only |
| Fabric (pattern library) | Yes | No (flat pattern library) | No | Passthrough |
| Jsonnet / CUE / Kustomize | No (structured data) | Yes, different model | Yes (CUE unification) | Structured config |
| noweb / org-mode tangle | Yes (literate) | Positional only | No | Tangled source |
Put differently: if you have more than a few dozen markdown modules and
manual ordering hurts, or if you need to model mutually-exclusive
options (reasoning-verbose vs reasoning-terse), or if you want to
ship the same content to multiple audiences via presets — plait is the
only tool with all three primitives.
- Modular content — reusable markdown snippets with TOML frontmatter
- Dependency resolution — automatic ordering via
requires/suggests/conflicts - Preset system — reusable module selections with multi-parent inheritance
- Variable interpolation — MiniJinja templating with strict undefined-variable behavior
- Multiple output formats — Markdown, plain text, JSON, YAML, HTML
- Plugin system — WASM (
wasmtime) and external-process plugins for loaders, resolvers, and renderers - Programmatic hooks — pre/post resolve and render with JSON-in/JSON-out scripts
- Runtime generators — build modules dynamically from YAML/JSON/TOML data files via Jinja templates
- JSON Schema — editor/IDE integration via
plait schema {project,user,module,preset} - Rich errors — source-span diagnostics with fuzzy-matched suggestions via
miette
- Rust 1.90+ (edition 2024)
git clone https://github.com/plaited-dev/plaited
cd plaited
cargo build --release
cargo install --path .cargo install plaitedThe plaited crate installs a binary named plait (the rename only
affects the registry slug; everything you type still uses plait).
The shortest path from zero to a working plait project is the
examples/hello/ directory in this repository. It
ships three modules, one preset, and no generators/hooks/plugins — the
absolute minimum needed to see composition in action. Clone the repo
and run:
cd examples/hello
plait list # Shows the three modules
plait compile --preset basic # Composes them into a single documentFor a first project of your own:
mkdir -p ~/.config/plait/modules/core
cat > ~/.config/plait/modules/core/intro.md << 'EOF'
+++
id = "core/intro"
order = 10
+++
# {{ project_name | default("Project") }}
Author: {{ author | default("Unknown") }}
Date: {{ date }}
EOFmkdir -p ~/.config/plait/presets
cat > ~/.config/plait/presets/basic.toml << 'EOF'
[preset]
id = "basic"
description = "Basic preset with core modules"
[modules]
include = ["core/*"]
[context]
author = "Your Name"
EOFplait compile --preset basic --set project_name="My Project"Modules are markdown files with TOML frontmatter:
+++
id = "security/auth"
description = "Authentication guidelines"
order = 50
requires = ["core/intro"]
tags = ["security"]
+++
## Authentication
Security guidelines for authentication...Presets define reusable module selections with multi-parent inheritance:
[preset]
id = "api-service"
extends = ["basic", "rust-base"]
[modules]
include = ["core/*", "security/*", "api/*"]
exclude = ["mobile/*"]
[context]
service_type = "REST API"| Command | Description |
|---|---|
plait compile |
Generate composed output |
plait list |
List available modules |
plait show <id> |
Display module details |
plait graph |
Visualize dependency graph (text or DOT) |
plait resolve |
Show resolution order with reasons |
plait check |
Validate configuration |
plait lint <path> |
Validate module/preset format |
plait init |
Create project configuration |
plait doctor |
Diagnose setup issues |
plait schema |
Emit JSON Schemas for editor tooling |
plait hooks |
List configured hooks |
plait plugins |
List and inspect configured plugins |
plait completions <shell> |
Generate shell completions |
| Environment variable | Default | Description |
|---|---|---|
PLAIT_CONFIG |
~/.config/plait/config.toml |
User config path |
PLAIT_MODULES |
From config | Module paths (colon-separated) |
PLAIT_PRESETS |
From config | Preset paths (colon-separated) |
NO_COLOR |
Unset | Disable colored output |
RUST_LOG |
info |
Log level |
- Getting Started — installation and first steps
- Architecture — system design and components
- CLI Reference — complete command documentation
- Specification — format details and algorithms
- Deployment — installation and configuration
- Testing — testing strategy and guidelines
- Security — threat model and mitigations
- Roadmap — what is and isn't planned for v1.1
- Troubleshooting — common issues and solutions
| Example | What it shows |
|---|---|
examples/hello/ |
Minimal first project: 3 modules + 1 preset, no advanced features |
examples/technical-docs/ |
Documentation composition with sections and cross-references |
examples/polymorphic-agents/ |
Every advanced feature: 4-level inheritance, conditional deps, generators, hooks, multi-source context |
examples/plait-ultimate/ |
Kitchen-sink example exercising the full plait surface |
# Run tests
cargo test --all-features
# Run with debug logging
RUST_LOG=debug cargo run
# Check formatting
cargo fmt --check
# Run lints (CI treats warnings as errors)
cargo clippy --all-features --all-targets -- -D warnings
# Run all checks
just checkLicensed under either of Apache License, Version 2.0 or MIT License at your option.
See CONTRIBUTING.md for guidelines.