Goal: a clean primary file stays in place; parallel-docs (Markdown under .parallel-docs/source/) holds the narrative, tied together by config and optional blocks in the metadata index.
- A Git checkout (recommended): hooks and many diagnostics assume
.gitexists. - The CLI available one of the ways in Install—including
npx parallel-docs(no global install);npx parallel-docs --helpshowsUsage: parallel-docs [options] [command].
Commands below assume your shell’s current directory is the repository root (or a subdirectory—ParallelDocs walks up for .parallel-docs.toml, then .git, then falls back to cwd for first-time init).
parallel-docs initThis is idempotent: it ensures .parallel-docs/, a starter .parallel-docs/metadata/index.json if missing, .parallel-docs.toml if missing, refreshes index migrations, merges the ParallelDocs VS Code extension into .vscode/extensions.json when safe, and runs parallel-docs validate. Exit code 1 means validation reported errors (fix them before relying on hooks or any validate step you run in CI).
Optional: install the pre-commit fragment so commits run validate when parallel-docs is on PATH:
parallel-docs init scmConvention: flat layout (no {storage}/source/.default): repo-relative primary path P → .parallel-docs/source/{P}.md (append .md to P; POSIX slashes; no ..). Angles layout (sentinel present): .parallel-docs/source/{P}/{angle}.md. Examples (flat):
README.md→.parallel-docs/source/README.md.mdsrc/app.ts→.parallel-docs/source/src/app.ts.md
To move an existing flat tree to Angles folders and [angles] in one step: parallel-docs migrate-angles (use --dry-run first; see storage spec).
Print the path for any file:
parallel-docs paths src/app.tsCreate the Markdown file (empty is fine to start). Write prose under optional <!-- parallelDocs:block id=… --> markers when you use blocks; see Keeping blocks in sync. For marker: blocks, pair delimiters in the primary file match the editor language — see Source region delimiters.
parallel-docs validate0 = no errors (warnings may still print). 1 = schema, anchors, markers, or other errors—see messages on stderr.
For environment hints (e.g. missing .git):
parallel-docs doctorInstall d-led.parallel-docs (Install). Use commands such as Open parallel-docs beside source and Add block from selection where available; validation output appears in a ParallelDocs output channel.
| Topic | Doc |
|---|---|
| Blocks, index, anchors | Keeping blocks in sync |
| What runs where (hook, CI, editor) | What ParallelDocs detects |
| All CLI commands | CLI reference |
.parallel-docs.toml keys |
Configuration |
| Normative detail | docs/spec/storage.md, anchors.md, blocks.md |