Getting started with ctxgrd

Lint your first structured-markdown record – an ADR, PRD, runbook, or any .md file with <NAMESPACE>-<number> frontmatter – in under five minutes.

Prerequisites

  • A repository with at least one markdown document you want to keep well-formed.
  • The ctxgrd binary on your PATH. Build it with cargo install --path . from a clone, or cargo build --release and copy target/release/ctxgrd.

Create a config

ctxgrd does nothing until a namespace claims a file. The fastest way to a working config is to apply a built-in pack:

ctxgrd pack add project-docs

This appends [ADR], [PRD], [RFC], [BUG], [TODO], and [README] blocks to ctxgrd.toml, each with sensible rules and required headings. To see what a pack writes before committing to it:

ctxgrd pack show project-docs    # the namespaces, rules, and shape it defines
ctxgrd pack add project-docs --dry-run    # print the blocks, touch nothing

Run the linter

ctxgrd            # lint the working tree, human-readable output
ctxgrd --format json | jq    # machine-readable, one diagnostic per object

The exit code tells an agent or CI how the run went without parsing text:

  • 0 – clean.
  • 1 – diagnostics were reported.
  • 2 – a kernel or config error (bad ctxgrd.toml, unreadable file).

Write a guide of your own

End-user documentation has its own pack. Apply it and drop a guide under docs/guides/:

ctxgrd pack add guide

Each guide carries a title and a type from the Diátaxis taxonomy (tutorial, how-to, reference, explanation). The README links the entry guide so readers can find it.

Troubleshooting

cfg.rule-unknown: <rule> – the installed binary predates a rule in your config. Reinstall ctxgrd so the binary matches the config, or remove the rule.

No diagnostics and no files checked – no namespace claims your files. Add a paths glob to the namespace, or give the file an id: <NS>-<number>. A file that claims neither is silently skipped by design.

Next steps