Skip to content
Merlon Docs

Docs dogfooding

This repo’s documentation is sharded under docs/. Shards are the source of truth. Compiled output is generated.

Guide directories

Section titled “Guide directories”
Directory Audience Output
glossary/ Shared terms (cross-guide) No output of its own; see below
features/ Tool capabilities, migration map docs/_build/features.md and the monolith docs/_build/guides.md (gitignored local review)
developer/ Contributing to this repo DEVELOPERS.md at repo root
client-cli/ npm CLI consumers packages/merlon-docs-cli/README.md
client-core/ Programmatic API consumers packages/merlon-docs-core/README.md
repo-readme/ Repository visitors, skill adopters README.md at repo root

A guide whose compile.scopeRoot is glossary stitches in every term the link walk from its shards finds (Linked shards).

Each compiled output marks every stitched shard with <!-- merlon-shard: start … --> and end comments that give the shard’s path.

Surface ownership: repo-readme/ = Agent Skill landing; client-cli/ = CLI commands/config only; client-core/ = library API/hooks only. Cross-link the other surfaces instead of duplicating skill, CLI, or API narrative across package READMEs.

Config: docs/merlon.config.json. Guides with compile.outputFile publish to a separate path and are excluded from the monolith. Coverage checks on this repo use scan.strict: true with standaloneGuides / scan.ignore so tooling trees (.worktrees, .cursor, .changeset, tests, examples, …) never fail merlon check. Publishable skills under skills/ are registered as standalone.

Publish landing style for root README: Personas and priority tiers.

Compile rebases each shard’s ../ links relative to the file being assembled, the guide’s link base, except the links that Publish-relative exclusions lists. A publish guide’s link base is its output in the table above. features is assembled twice: its compiled guide rebases relative to docs/_build/features.md, and its copy in the monolith relative to docs/_build/guides.md. Repo scripts pass --config docs/merlon.config.json --docs-root docs, and Config essentials says how each option resolves.

Edit workflow

Section titled “Edit workflow”
  1. Edit shard .md files under the relevant guide directory.
  2. If you changed a guide’s index.md link order, re-run compile — order is read from the manifest. See Manifest compile order when using compile.sectionsHeading.
  3. Run pnpm docs:compile:repo, then pnpm docs:check, which also checks the examples.
  4. Review the change at both levels of two-level review: each shard on its own, then against the guides, skills, and code that describe the same behavior. To review the docs as a set, run the doc-review workflow.
  5. Commit shard changes. Regenerated docs/_build/ (monolith, per-guide outputs, refs.json) is gitignored. CI and pnpm docs:check compile it locally. Every other output in the guide table is committed, in the same commit as the shard change that regenerates it.

Agent context

Section titled “Agent context”

Find a shard under docs/ with host search and read that one shard, as refs says.

Linting docs

Section titled “Linting docs”
  • markdownlint: the shard preset on the shards, then the repo’s own compiled config, docs/compiled-lint.markdownlint-cli2.jsonc, on the monolith, DEVELOPERS.md and the published READMEs. That config turns off fewer rules than the compiled preset in @merlon-docs/merlon-docs-presets, which the examples use.
  • Vale: prose lint on the vale.scanGlobs directories in the config, which are glossary/, features/, developer/, client-cli/, client-core/ and repo-readme/, plus every standaloneGuides file. docs/.vale.ini opts CODE_OF_CONDUCT.md out, because its text is the vendored Contributor Covenant. Vale is not an npm dependency, so install it on PATH as Local setup describes.
  • Vale MerlonDocs / MerlonDocs-PandocId: peer prose rules for unlinked heading mentions and dated claims, plus this repo’s local rule against Pandoc IDs. They run in the peer Vale stage of merlon check, and --require-vale makes a missing Vale fail the run.
  • link lint: built-in validation runs on every docs:check at the default "error" severity. Each publish guide lists features in compile.crossGuideLinks.ignoreGuides. A cross-guide link to a features shard then keeps its docs/features/ path, rebased for the output’s location, as Publish-only link policy says. A link to a shard that the guide stitches can take an in-document anchor instead (Same compiled output preference).

First-time bootstrap syncs the Vale styles and says when to sync them again.