Have you ever wished a “commentary 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 commentray CLI, and a VS Code or Cursor extension. They share one configuration file and one companion tree next to your sources. Tooling ties commentary to the code: optional Git hooks, validation and doctor flows, migrations, rendering, static site output, a serve mode for local browsing, 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 Commentray detects.
Inline comments are not always possible (generated files, tight formats, policy). Commentray keeps the primary artifact clean while storing rationale, warnings, and diagrams in companion Markdown under a commentray folder beside the code it explains. In a meeting you might hear someone say they need to document architecture in commentray 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 commentary 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-commentary static site (for example GitHub Pages) with scroll-linked panes.
Short guides live under docs/user—install, first setup, keeping blocks aligned, what each layer catches, CLI reference, configuration, and troubleshooting:
- Install
- Quickstart
- Keeping blocks in sync
- What Commentray detects
- CLI reference
- Configuration
- Troubleshooting
The install guide walks through npm, 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.
Layout, day-to-day commands, quality gate, Cypress, Pages, and releases for people working on Commentray itself are in Development, including dogfood: README on GitHub Pages. The contributor contract is in CONTRIBUTING.md.
Packages in this monorepo are licensed under MPL-2.0 (see LICENSE and per-package copies).
Repository: github.com/d-led/commentray. The name Commentray sidesteps an existing “commentary” extension identity on the Visual Studio Marketplace; the project nearly used “commentary” instead.
See CONTRIBUTING.md and Development.