Schemas, queries and a link graph for the Markdown your team — and your AI agents — already write.
Rootline is a single-binary CLI that turns a directory of Markdown files into a validated, queryable dataset. You declare what each folder's documents must look like in a small .stem file; Rootline validates every file against it, answers questions like "which tasks are still pending in this epic?" without grepping, keeps roll-up counts in index files current, and checks that the links between documents actually resolve. Nothing is rendered, nothing is uploaded, and no database is introduced: the files stay plain Markdown in Git.
rootline validate --all docs/ # every document conforms to its schema?
rootline query docs/ --where 'status == "pending"' # records as JSON, no grep
rootline graph docs/ --check # broken links and cycles → exit codeTeams keep more and more of their operating knowledge in Markdown: PRDs, ADRs, roadmaps, runbooks, task files, Obsidian vaults, the docs/ folder an AI coding agent reads before every change. It scales badly:
- Frontmatter drifts.
status: Pendingin one file,estado: pendingin the next, a requiredownermissing in half of them. Nobody notices until something downstream breaks. - Nothing is queryable. "What is blocked right now?" means opening files or writing a one-off script.
- Roll-ups go stale. The
README.mdthat says 12 of 20 tasks done was true two weeks ago. - Links rot silently.
[[T014-migrate-auth]]was renamed; three documents still point at it. - Agents guess at structure. Coding agents write Markdown fast and inconsistently unless something tells them — in a machine-readable way — what a valid record is.
Linters check formatting. Static-site frameworks validate frontmatter only inside their build. Query tools read frontmatter but enforce nothing. Rootline does all four jobs — validate, query, derive, link-check — from one CLI, with inherited schemas and stable JSON output that humans, CI and agents consume the same way.
- Docs-as-code teams keeping PRDs, ADRs, roadmaps or runbooks in a Git repository and wanting CI to reject malformed records.
- Engineering teams using AI coding agents (Claude Code, Codex, Gemini CLI, …) that need a contract for the Markdown those agents read and write.
- Obsidian / Markdown vault owners who want validation and queries from the terminal and in CI, not only inside an editor plugin.
If your Markdown is prose with no metadata, Rootline is not the tool. If it has frontmatter you rely on, it is.
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/pablontiv/rootline/master/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/pablontiv/rootline/master/install.ps1 | iex
# From source (Go 1.26+)
go install github.com/pablontiv/rootline/v9/cmd/rootline@latestRelease builds auto-update within their compatibility boundary; see docs/auto-update.md.
rootline init docs/init reads the frontmatter in docs/, infers field types, enums and required fields, and writes a docs/.stem with root: true (the boundary where schema discovery stops). Preview with --dry-run, or start from someone else's schema with --template owner/repo.
A .stem is small and readable:
version: 2
schema:
title: { type: string, required: true }
status:
type: enum
values: [pending, in_progress, done, blocked]
default: pending
required: true
owner: { type: string }
derive:
slug: 'slugify(title)'
aggregate:
done_count: 'len(filter(descendants, .status == "done"))'
links:
blocked_by:
target: '.*/T[0-9]{3}-.*\.md$'rootline validate --all docs/A typo in an enum value, a missing required field or a link to a file that does not exist is reported with the file, the rule, the .stem that declared it and — when there is an obvious fix — a suggestion:
{
"rule": "enum",
"field": "status",
"message": "value pendig is not in allowed values: [pending, in_progress, done, blocked] (did you mean \"pending\"?)",
"source": "docs/.stem",
"severity": "error",
"suggestion": "pending"
}Exit code is non-zero on any error, so the same command gates a pre-commit hook (rootline hooks install) or a CI job.
rootline query docs/ --where 'status == "blocked"' --select path,title,owner
rootline query docs/ --where 'status != "done"' --count
rootline query docs/ --has-outbound 'status == "blocked"' # records that depend on something blockedFilters use expr-lang syntax over frontmatter, derived and aggregated fields. Output is JSON by default; --output table, jsonl and csv are available where they make sense.
rootline fix --all docs/ --dry-run # proposed repairs (enum typos, missing defaults) — nothing written
rootline new docs/T021-rotate-keys.md # a new record with frontmatter pre-filled from the effective schema
rootline explain docs/README.md # where each field value came from: frontmatter, derive, aggregate, which .stem
rootline graph docs/ --format mermaid -o table # the dependency graph, ready to paste into GitHubDirectories are tables, files are records, .stem files are the schema. When Rootline resolves the schema for a file it walks up the directory tree collecting .stem files until it reaches one marked root: true, then merges them top-down. A child directory can add fields or tighten constraints; it can never remove a guarantee a parent made. That one rule is what makes a large tree governable: whatever docs/.stem promises holds for everything beneath it.
docs/.stem root: true — title, status required for every record
docs/roadmap/.stem adds: id as sequence T###, owner required
docs/roadmap/T014.md validated against the merge of both
A field does not have to live in frontmatter. source: body.section["## Summary"] binds a typed field to a section of the document body, so a heading your team already writes becomes validated, queryable data; frontmatter remains an explicit override when both exist. Rules are small and composable: required means presence, non_empty is separate, values: constrains an enum, and exists checks presence of an effective field — frontmatter, body-sourced or derived.
The pipeline is extract → resolve schema → validate → derive → aggregate → query, and every command emits a versioned JSON envelope ("version": 2, "kind": "rootline/validate-batch") so output shapes are a contract, not an accident.
Rootline never leaves a file its own schema refuses. Repairs go through atomic writes, preserve YAML key order and comments, and each written file is re-validated and restored byte-for-byte if the result fails. Git is optional: .git is only consulted by the explicit --staged, hooks and migrate flows, never for schema discovery.
| Rootline | Markdown linters (markdownlint, mdschema, remark-lint-frontmatter-schema) |
Frontmatter query tools (krafna, markdowndb, Obsidian Dataview) |
Framework collections (Astro, Contentlayer) | |
|---|---|---|---|---|
| Validate frontmatter against a schema | ✅ | ✅ | ❌ | ✅ (only inside the build) |
| Schema inherited through the directory tree | ✅ | ❌ | ❌ | ❌ |
| Infer a schema from existing files | ✅ | partial | ❌ | ❌ |
| Query records with filters | ✅ | ❌ | ✅ | ✅ (in app code) |
| Derived and aggregated fields | ✅ | ❌ | partial | ❌ |
| Link graph, broken-link and cycle checks | ✅ | partial | partial | ❌ |
| Propose and apply safe repairs | ✅ | ❌ | ❌ | ❌ |
| Single static binary, no runtime | ✅ Go | mostly Node (mdschema: Go) |
varies | Node |
Use a linter for prose style; use Rootline when the metadata in your Markdown is data you depend on.
This repository ships a composite action. Add it to any workflow:
- uses: pablontiv/rootline@master
with:
path: docs/
fail-on: error # or: warning | neverIt installs the latest release (or uses a rootline already on PATH), runs validate --all and exposes valid and error_count as outputs.
rootline hooks install # validates staged Markdown on every commit; respects core.hooksPathRootline is built to be the structured source of truth an agent calls instead of reading files: query, validate, describe, explain, tree, stats and graph all return stable JSON, and --field extracts exactly the value a tool call needs. rootline skill install publishes a managed agent skill into ~/.claude/skills and ~/.agents/skills through an explicit plan-and-approve flow — see docs/skill.md.
The engine decides everything that follows from form (a field present in >80 % of records is inferred as required; a majority value becomes a default). Decisions that need meaning are not guessed: analyze marks them requires_agent and reports percentage evidence for a human or an agent to resolve.
| Area | Commands | Docs |
|---|---|---|
| Validate & govern | validate, describe, explain |
validate · describe · explain |
| Query & traverse | query, tree, stats, graph |
query · tree · stats · graph |
| Build & maintain | init, new, set, fix |
init · new · set · fix |
| Analyze & evolve | analyze, schema propose/apply, repair apply, migrate |
analyze · migrate |
| Infrastructure | hooks, skill, completion |
skill · auto-update |
Commands with a JSON envelope accept --output json|table (plus jsonl/csv on query --select) and --field <dot.path> for extracting one value; commands that only write files or print text reject them. query, stats, tree, graph and validate --all accept --where 'expr'. Full contracts: docs/output.md.
Deeper topics: derivation & aggregation · levels & match: scoping · extensibility · upgrading from v1 .stem.
Requires Go 1.26+ and Git (for hooks and CI). Field names in this repository's own governed data (docs/roadmap/) are in Spanish — estado, tipo — because that is how the roadmap was written; Rootline itself has no opinion on language.
just check # gofmt + golangci-lint + go build
just test # go test ./... -race
just validate # rootline validate --all docs/roadmap/Commits follow Conventional Commits and are enforced by a commit-msg hook. See CONTRIBUTING.md and SECURITY.md. Visual identity guidelines live in docs/identity.md.
Apache License 2.0 — free for commercial and non-commercial use.
