The user guide for docsync: what it does, how to set it up, and the reference for every directive, command, config key and integration. Every example in these pages is a test: the project's gate runs each command against the ds binary and fails when a page shows output ds does not print, so the pages and the tool cannot drift apart. Where the binary does less than the spec describes, the pages say what it does today. How the pages are written and run is in CONTRIBUTING.md.
| Page |
Read it when |
| docsync at a glance |
you are deciding whether docsync fits: the problem, the vocabulary, one full round of the loop with real output, and a def in every language on one screen |
| Getting started |
you are setting it up: install, ds init, your first defs and citations, a change caught by ds check, the fix and the ack, committing .ds/, adopting existing links |
| Page |
What it covers |
| Directives |
every directive (ds:def, ds:block, ds:cfg, ds:claim, ds:url, ds:run, ds:table, ds:chain), every argument, ids and labels, pick, environments, deprecation, translations |
| Languages |
per language and format: the comment a def goes in, what ds def file#Name can address, exactly which lines a def binds |
| Page |
What it covers |
| Command reference |
every ds command with its flags, exit codes and a real run, grouped by job |
| Configuration |
every key in .ds/config.toml, its default, and how the file is validated |
| CI |
ds check as a gate in GitHub Actions, GitLab and pre-commit; frozen checks; PR comments; notifications |
| Troubleshooting |
ds doctor, every finding state and how to clear it, common mistakes, ds undo, FAQ |
| Page |
What it covers |
| Cross-repo workspaces |
a docs repo and a code repo citing each other: ds publish, ds sync, frozen and syncing checks, branches, repo mode |
| Secrets, runs and URLs |
ds:run (and [run] shell), ds:url, secret chains and --resolve, writing a resolver plugin |
| Agents and editors |
ds mcp and its tools, ds lsp, ds map and ds context budgets, the VS Code client |
| Integrations |
Hugo, Docusaurus, VS Code, pre-commit and the GitHub Action |
| Using docsync as a Go library |
embedding the checks in a Go program, the no-writes contract, building your own ds |
The normative design, with a conformance fixture behind every rule, is docs/SPEC.md.