1<!-- #region parallelDocs:readme-lede -->
| |
3# ParallelDocs — a side-by-side documentation ecosystem
5[](https://www.npmjs.com/package/@parallel-docs/core)
6[](https://www.npmjs.com/package/@parallel-docs/render)
7[](https://www.npmjs.com/package/@parallel-docs/code-parallel-docs-static)
8[](https://www.npmjs.com/package/@parallel-docs/mcp-server)
9[](https://www.npmjs.com/package/@parallel-docs/cli)
10[](https://marketplace.visualstudio.com/items?itemName=d-led.parallel-docs)
12Have you ever wished a “side track” for code the way DVD extras let filmmakers talk over a film without changing the picture? When looking at code, that might answer the whys, reveal the intent besides the code itself.
14The ecosystem is a handful of published npm libraries, the parallel-docs CLI, and a VS Code or Cursor extension. They share one configuration file and one companion tree next to your sources. Tooling ties parallel-docs to the code: optional Git hooks, validation and doctor flows, migrations, rendering, static site output, a **local** `parallel-docs serve` helper for preview (not the production host—you deploy `_site/` elsewhere), and standalone executables when you do not want a Node install. For how checks split across hook, CLI, editor, and what this repository’s own CI runs versus validate, see [What ParallelDocs detects](docs/user/detection.md).
ParallelDocs — a side-by-side documentation ecosystem
Have you ever wished a “side track” for code the way DVD extras let filmmakers talk over a film without changing the picture? When looking at code, that might answer the whys, reveal the intent besides the code itself.
The ecosystem is a handful of published npm libraries, the parallel-docs CLI, and a VS Code or Cursor extension. They share one configuration file and one companion tree next to your sources. Tooling ties parallel-docs to the code: optional Git hooks, validation and doctor flows, migrations, rendering, static site output, a local parallel-docs serve helper for preview (not the production host—you deploy _site/ elsewhere), and standalone executables when you do not want a Node install. For how checks split across hook, CLI, editor, and what this repository’s own CI runs versus validate, see What ParallelDocs detects. | You have the main README.md in the left column: packages, scripts, release flow. This file is parallel-docs for that README—the voice-over beside the facts, not a second brochure.
If this is your first pass, try a quick interaction: scroll either pane and watch the other follow, then tap the Help button in the top bar if you want the guided tour again.
|
16<!-- #endregion parallelDocs:readme-lede -->
| |
17<!-- #region parallelDocs:readme-why -->
| |
21Inline comments are not always possible (generated files, tight formats, policy). ParallelDocs keeps the primary artifact clean while storing rationale, warnings, and diagrams in companion Markdown under a parallel-docs folder beside the code it explains. In a meeting you might hear someone say they need to document architecture in parallel-docs so newcomers can onboard from the source—same word names the tool and the habit; context disambiguates.
23The same split helps when you want rich context for a person or a chatbot—runbooks, product rationale, incident notes, onboarding prose—that does not belong in the source file itself, yet stays tied to specific lines or regions through the metadata index and block anchors, so “this parallel-docs goes with that code” stays obvious without pasting a wall of inline comments into the repo.
25That is useful for developers and architects, for LLM-assisted workflows that need context beside the primary file, for onboarding next to the code, for optional pre-commit checks on companion metadata, and for publishing a code-plus-parallel-docs static site (for example GitHub Pages) with scroll-linked panes.
Why
Inline comments are not always possible (generated files, tight formats, policy). ParallelDocs keeps the primary artifact clean while storing rationale, warnings, and diagrams in companion Markdown under a parallel-docs folder beside the code it explains. In a meeting you might hear someone say they need to document architecture in parallel-docs so newcomers can onboard from the source—same word names the tool and the habit; context disambiguates.
The same split helps when you want rich context for a person or a chatbot—runbooks, product rationale, incident notes, onboarding prose—that does not belong in the source file itself, yet stays tied to specific lines or regions through the metadata index and block anchors, so “this parallel-docs goes with that code” stays obvious without pasting a wall of inline comments into the repo.
That is useful for developers and architects, for LLM-assisted workflows that need context beside the primary file, for onboarding next to the code, for optional pre-commit checks on companion metadata, and for publishing a code-plus-parallel-docs static site (for example GitHub Pages) with scroll-linked panes. | The README’s Why section names the product (ParallelDocs) and the prose you write (parallel-docs). Same checkout, two panes: the left states what exists; this column states why it is shaped that way and where the edges are.
|
27<!-- #endregion parallelDocs:readme-why -->
| |
| |
29<!-- #region parallelDocs:readme-user-guides -->
| |
33Short guides live under docs/user—install, first setup, keeping blocks aligned, what each layer catches, CLI reference, configuration, and troubleshooting:
35- [Install](docs/user/install.md)
36- [Quickstart](docs/user/quickstart.md)
37- [Keeping blocks in sync](docs/user/keeping-blocks-in-sync.md)
38- [What ParallelDocs detects](docs/user/detection.md)
39- [CLI reference](docs/user/cli.md)
40- [Configuration](docs/user/config.md)
41- [Troubleshooting](docs/user/troubleshooting.md)
Using ParallelDocs
Short guides live under docs/user—install, first setup, keeping blocks aligned, what each layer catches, CLI reference, configuration, and troubleshooting:
| The README’s Using ParallelDocs section links short guides under docs/user/—install, quickstart, keeping blocks in sync, detection, CLI reference, configuration, troubleshooting—without walking the whole monorepo first.
On GitHub Pages the split is live: Code is this repo’s README.md; ParallelDocs is this file, rendered as HTML. Scroll either pane—the other follows in lockstep (block stretch when index.json uses marker: anchors backed by paired <!-- #region parallelDocs:… --> / <!-- #endregion … --> delimiters in README.md, plus matching <!-- parallelDocs:block id=… --> markers here; otherwise proportional sync). That is the DVD-style parallel-docs metaphor without installing anything.
The deploy is a single HTML file, so in-parallel-docs Markdown links rewritten to repo-relative paths can 404 on Pages; use full https://github.com/…/blob/… URLs when the link must work from the static site.
Search: Escape clears the query and hides hit results (same as Clear).
Images next to this file
Keep images in the same directory as this .md (or a normal subfolder like ./assets/) and reference them with ./… paths—the VS Code Markdown preview and path completions use the same CommonMark rules. Static HTML rules: docs/spec/storage.md § Images (local img must resolve under .parallel-docs/; use https://… for diagrams outside storage).
Real screenshots: run bash scripts/refresh-root-readme-screenshots.sh (or npm run extension:parallel-docs-screenshots), capture the UI, save files under ./assets/ here, then  like any other Markdown project. For the VS Code extension README walk-through PNGs, see .parallel-docs/source/packages/vscode/README.md/main.md → Maintainer.
The VS Code / Cursor extension is for authoring: ParallelDocs: Open parallel-docs beside source, both editors visible, scroll source and let side track. After ParallelDocs: Add block from selection, sync can snap to the block that owns the visible source lines when index.json and <!-- parallelDocs:block id=… --> markers agree; otherwise you stay on proportional sync. Same storage model as the site; the extension is where editing stays pleasant.
Why this file exists
The README stays scannable. Here we keep motive, trade-offs, and sharp edges—without duplicating another full quickstart.
If you only do one thing
Clone and npm run setup (see README). Then pick editor install script or cli:install; both land on the same .parallel-docs/ layout and validators. Same model, different entrypoints.
About this HTML
You may be reading a generated page: @parallel-docs/code-parallel-docs-static, build-static-pages.mjs, and pages.yml. Point [static_site] at another source file and you get the same layout—configuration is reuse, not a fork.
Cookbook (tone, not a second README)
- Greenfield adopt —
parallel-docs init is idempotent; nothing in the primary tree has to move first.
- One-off CLI —
npx parallel-docs … needs no global install; npx parallel-docs --help prints Usage: parallel-docs [options] [command] (same as Install describes for npm).
- Hook paranoia —
init scm runs validate before merge; opt-in because hooks are a team contract.
- “Why is my tree red?” —
doctor stacks environment checks on validate.
- Binaries — standalone CLI assets ship on GitHub Releases with each
v* tag; CI artifacts from .github/workflows/binaries.yml expire after 14 days by design.
- Your own Pages — Copy
.parallel-docs.toml, adjust [static_site], run npm run pages:build.
Architecture (who talks to whom)
Do not duplicate the README’s package list here—that list is canonical. The diagram below is roles, not package names—see the Architecture angle for the exact @parallel-docs/* dependency graph.
flowchart TB
nCore["Core library paths index config"]
nHtml["HTML pipeline and code-browser shell"]
nSsg["Static site one-page HTML"]
nCli["CLI init validate pages serve"]
nExt["Editor paired files scroll sync"]
nCore -->|builds on| nHtml
nCore -->|paths and index| nSsg
nHtml -->|shell uses| nSsg
nCore -->|uses| nCli
nHtml -->|uses| nCli
nSsg -->|bundled in| nCli
nCore -->|uses| nExt In one line: core holds paths and index truth; render holds safe HTML; cli and the extension are surfaces; the static-site package is the thinnest consumer of render for publishing. Change the HTML contract, then walk that chain backward before you tag.
Reference (jump off points)
What ParallelDocs is not (one beat each)
Not a substitute for inline comments where the medium allows. Not a hosted blog—parallel-docs lives in git with the code it explains. Not editor-exclusive—the CLI is the same story without a GUI.
|
43<!-- #endregion parallelDocs:readme-user-guides -->
| |
| |
| |
| |
47The [install guide](docs/user/install.md) walks through npm global, **`npx parallel-docs`** (one-off; **`npx parallel-docs --help`** → `Usage: parallel-docs [options] [command]`), release binaries, and the Marketplace extension. Clone workflows, local binary builds, and macOS quarantine sit in [Development → CLI, binaries, and Pages](docs/development.md#cli-binaries-and-pages). If you want Node-free installs, use [GitHub Releases](https://github.com/d-led/parallel-docs/releases); [Development](docs/development.md#cli-binaries-and-pages) explains which artifacts are meant to last.
The install guide walks through npm global, npx parallel-docs (one-off; npx parallel-docs --help → Usage: parallel-docs [options] [command]), release binaries, and the Marketplace extension. Clone workflows, local binary builds, and macOS quarantine sit in Development → CLI, binaries, and Pages. If you want Node-free installs, use GitHub Releases; Development explains which artifacts are meant to last. | |
| |
49## AI Coding Assistants (MCP)
AI Coding Assistants (MCP) | |
| |
51ParallelDocs ships an [MCP server](docs/user/mcp-server.md) so AI assistants can validate, discover, read, and write parallel-docs. Start with:
ParallelDocs ships an MCP server so AI assistants can validate, discover, read, and write parallel-docs. Start with: | |
| |
| |
54parallel-docs mcp install # writes .vscode/mcp.json, .claude/mcp.json, etc.
parallel-docs mcp install # writes .vscode/mcp.json, .claude/mcp.json, etc. | |
| |
| |
57This gives your AI coding assistant 16 tools — from `parallel_docs_list_pairs` and `parallel_docs_find_uncommented` to `parallel_docs_read_parallel_docs` and `parallel_docs_validate`. See the [MCP guide](docs/user/mcp-server.md) for setup and tool reference.
This gives your AI coding assistant 16 tools — from parallel_docs_list_pairs and parallel_docs_find_uncommented to parallel_docs_read_parallel_docs and parallel_docs_validate. See the MCP guide for setup and tool reference. | |
| |
59## Ecosystem & this repo
Ecosystem & this repo | |
| |
61Layout, day-to-day commands, quality gate, Cypress, Pages, and releases for people working on ParallelDocs itself are in [Development](docs/development.md), including [dogfood: README on GitHub Pages](docs/development.md#dogfood-readme-on-github-pages). The contributor contract is in [CONTRIBUTING.md](CONTRIBUTING.md).
Layout, day-to-day commands, quality gate, Cypress, Pages, and releases for people working on ParallelDocs itself are in Development, including dogfood: README on GitHub Pages. The contributor contract is in CONTRIBUTING.md. | |
| |
| |
| |
65Packages in this monorepo are licensed under MPL-2.0 (see LICENSE and per-package copies).
Packages in this monorepo are licensed under MPL-2.0 (see LICENSE and per-package copies). | |
| |
| |
| |
69Repository: [github.com/d-led/parallel-docs](https://github.com/d-led/parallel-docs). The name ParallelDocs sidesteps an existing “parallel-docs” extension identity on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=jaredhughes.parallel-docs); the project nearly used “parallel-docs” instead.
Repository: github.com/d-led/parallel-docs. The name ParallelDocs sidesteps an existing “parallel-docs” extension identity on the Visual Studio Marketplace; the project nearly used “parallel-docs” instead. | |
| |
| |
| |
73<!-- #region parallelDocs:readme-mobile-flip-check -->
| |
75See [CONTRIBUTING.md](CONTRIBUTING.md) and [Development](docs/development.md).
| Narrow viewport check (README ↔ this angle)
On GitHub Pages, use a narrow viewport (or a phone), scroll this README to the bottom, then use flip source / parallel-docs. Scroll should stay block-linked with this companion file, and a second flip control appears when the toolbar flip scrolls off-screen.
The readme-mobile-flip-check region pairs README.md delimiters with this <!-- parallelDocs:block id=readme-mobile-flip-check --> section: scroll the Code column to the tail, flip to ParallelDocs and back—the panes should stay aligned with that block, and the duplicate flip should appear once the toolbar control is off-screen. |
77<!-- #endregion parallelDocs:readme-mobile-flip-check -->
| |
| |