markupwright 0.1.3

Template-driven workspace documentation generator
Documentation
<!-- @generated by markupwright v0.1.3 -- do not edit by hand. Edit the source template and run `markupwright`. -->

# 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:

```console
npm install --save-dev @wowlab/markupwright
```

Initialize a repository and generate its documents:

```console
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`:

```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:

```toml
[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:

```toml
[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:

```jinja
{% 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](skills/markupwright-setup) 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](CLAUDE.md) for a complete example using project metadata, source trees, skills, and GitHub workflows.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) to get started and [SECURITY.md](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](LICENSE)