markupwright 0.1.3

Template-driven workspace documentation generator
Documentation

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:

version = 1

[workspace]
name = "example"
description = "Example workspace"

[render]
templates = ".markupwright/templates"
header = "header.md.j2"
navigation = "README.md"
source-suffix = ".in"

[domains.cargo]
manifests = ["Cargo.toml", "crates/*/Cargo.toml"]
workspace = "Cargo.toml"
aliases = ".cargo/config.toml"
dependency-graph = true
source-documentation = true

[[documents]]
include = ["README.md.in"]
domain = "cargo"
template = "readme-root.md.j2"

[[documents]]
include = ["crates/*/README.md.in"]
domain = "cargo"
template = "readme-cargo.md.j2"

[[documents]]
include = ["**/*.md.in"]
template = "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:

[workspace]
domain = "cargo"

[directories."services/api"]
domain = "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:

[domains.frontmatter.skills]
include = [".claude/skills/*/SKILL.md"]
fields = ["name", "description"]
sort-by = "name"
scope = "root"

[domains.dotenv.environment]
path = ".env.example"
scope = "directory"

[domains.github-workflows.github]
include = [".github/workflows/*.yml", ".github/workflows/*.yaml"]
scope = "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.

License

MIT