Markupwright
Template-driven workspace documentation generator
Markupwright generates repository Markdown from Jinja templates and structured workspace metadata. It keeps project indexes, package READMEs, agent instructions, dependency graphs, and similar documents current.
The repository declares its manifests, templates, and documents in .markupwright/config.toml.
Getting started
Install Markupwright as a development dependency:
npm install --save-dev @wowlab/markupwright
Initialize a repository and generate its documents:
npx markupwright init
npx markupwright
The npm package installs a precompiled binary for the current platform. Markupwright is also available from crates.io for Rust projects.
markupwright init creates .markupwright/config.toml, .markupwright/templates/, and a nested .gitignore for the checksum cache. It refuses to replace an existing setup.
Use --check in CI, --dry-run to preview changes, and --filter <PATH> to limit generation to part of the repository. --root <PATH> and MARKUPWRIGHT_ROOT select a different repository root.
Configuration
Every repository provides a .markupwright/config.toml:
= 1
[]
= "example"
= "Example workspace"
[]
= ".markupwright/templates"
= "header.md.j2"
= "README.md"
= ".in"
[]
= ["Cargo.toml", "crates/*/Cargo.toml"]
= "Cargo.toml"
= ".cargo/config.toml"
= true
= true
[[]]
= ["README.md.in"]
= "cargo"
= "readme-root.md.j2"
[[]]
= ["crates/*/README.md.in"]
= "cargo"
= "readme-cargo.md.j2"
[[]]
= ["**/*.md.in"]
= "document.md.j2"
Document rules use first-match order. A rule with domain only matches directories owned by that domain. If several configured project manifests share a directory, select its primary domain explicitly:
[]
= "cargo"
[]
= "python"
Domains
Project domains parse declared manifests and add structured data to the template context. None are enabled until they appear under [domains].
| Domain | Common manifest | Context |
|---|---|---|
| Cargo | Cargo.toml |
cargo |
| Go | go.mod |
go |
| Lua | *.toc |
- |
| Node.js | package.json |
node |
| PHP | composer.json |
php |
| Python | pyproject.toml |
python |
Cargo, Go, Lua, Node.js, PHP, and Python can also provide source descriptions for tree() when source-documentation = true.
Frontmatter, dotenv files, and GitHub Actions workflows are generic collector domains. Their namespaces and inputs are explicit too:
[]
= [".claude/skills/*/SKILL.md"]
= ["name", "description"]
= "name"
= "root"
[]
= ".env.example"
= "directory"
[]
= [".github/workflows/*.yml", ".github/workflows/*.yaml"]
= "root"
The final table name is the template namespace. Removing a domain from config removes its collector and context.
Templates
Repository templates are loaded recursively from render.templates. They can replace an embedded template by name or extend one:
{% extends "readme-root.md.j2" %}
{% block content %}
Repository-specific content.
{% endblock %}
Override readme-base.md.j2 or instructions-base.md.j2 to apply repository branding to every matching domain template. Markupwright inserts that fragment into its layout shell, so Cargo, Node.js, language, root, and directory sections stay intact.
An input without its own extends uses the template selected by its document rule. The configured header is rendered and inserted into every output.
All templates receive children, description, kind, markupwright.version, name, nav, and version, plus the namespaces provided by configured domains. Helpers cover linked indexes, Mermaid blocks, repository file reads, Markdown tables, and source trees.
Generated Markdown is formatted before it is written. Unchanged runs are skipped using content checksums.
AI agents
The repository ships a markupwright-setup skill that installs Markupwright, builds an explicit repository config, and migrates existing READMEs to generated .md.in sources. It works with Codex, Claude Code, and other Agent Skills-compatible tools.
See the generated CLAUDE.md for a complete example using project metadata, source trees, skills, and GitHub workflows.
Contributing
See CONTRIBUTING.md to get started and SECURITY.md for vulnerability reports.
The polyglot fixture in tests/fixtures/preview exercises every built-in project template. Run cargo test --test cli preview to validate its output and cargo bench --bench generation to measure uncached rendering and checksum-cache hits.