notabene

nota bene - the margin mark that means “note this well.”

Leave notes in the margins of your repo's docs - right on the rendered page -
then let your AI agent apply them, resolve the threads, and journal what changed & why.

English · Français · 📖 Documentation

---

Iterate on your docs with an LLM - leave feedback anywhere, not squeezed into one prompt. A navigable doc site with multi-user comments, self-hosted in your git - no SaaS, no database. The anchored comment is the instruction: located, unambiguous, nothing to quote. Your agent reads it, edits the source, and journals what changed & why.

How it works (30 seconds)

1. npx notabene dev → open the site, select any text → leave a comment (or comment a whole page, diagram or image).
2. Tell your agent: "address the doc comments."
3. The agent reads .notabene/, edits the docs faithfully, marks each comment resolved, and appends a journal entry (what / why / which comments).
4. Read the trail at /journal - or validate each real git diff yourself in approve mode.

Try it

npm install -D @z29k/notabene   # or pnpm / bun
npx notabene init               # writes the config, the .notabene store + the agent protocol
npx notabene dev                # → http://localhost:3009

Using Claude Code? /plugin marketplace add z29k/notabene then /plugin install notabene@z29k - and just say "set up notabene". → Full install guide

Features

Each one is a link into the documentation - go deep only where you're curious:

• Anchored comments - select text on the rendered page, or comment a whole page, diagram or image. Threads, resolve, hold, a global /comments view, touch-first on mobile.
• Editing in the page - a ✎ in the margin opens any block right where you're reading it; the same save closes the comments it answers and journals the change. Dev-only, and it refuses to write a file git isn't tracking.
• The agent review loop - a file-I/O-first protocol any agent can follow (no server, no port, no MCP). Ships as a Claude Code skill; the skill file is the spec.
• Two-phase review - approve mode: the agent proposes, you validate each edit against its real git diff (cascades included) at /review.
• A real doc site - spaces, frontmatter-driven sidebar, search, commentable Mermaid diagrams with a pan/zoom lightbox, a light/dark toggle, responsive.
• MDX and CommonMark/GFM - lenient .md, strict .mdx, mixable per extension.
• Multi-language docs - clean prefixed URLs, a language switcher, per-language comments, EN/FR/… .
• PDF export - any page, folder, space or the whole doc: cover + clickable TOC in the browser, or a bookmarked PDF via notabene pdf.
• Make it yours - a custom home page, logo + favicon + social card, navigation links (topbar, sidebar block, site footer), and theming via stable --nb-* design tokens, your own fonts, a code theme, or your own stylesheet (cascade-layer-safe: your CSS always wins).
• Publish a public site - a read-only static build with an agent-readable surface (llms.txt, per-page Markdown twins, sitemap, OpenGraph), private-content scoping, optional full-text search (Pagefind: per-language stemming, highlighted excerpts — in the dev app too), GitHub Pages workflow included. The documentation site is notabene publishing itself.
• Link validation - notabene lint checks every internal link against the routes the last build actually emitted - dead links with did-you-mean suggestions, plus public→private leaks after build --public.
• A git-native store - comments + journal as versioned JSON in your repo: diffs in PRs, conflict-free merges, a schema agents can rely on.
• Safe by default - the write API is dev-only, loopback-bound, CSRF/rebinding-gated; public builds contain none of it.

Repo layout

• packages/renderer - the @z29k/notabene npm package (Astro renderer + CLI).
• packages/claude-plugin - the Claude Code plugin (setup + the review skill/protocol).
• docs/ - this documentation, reviewed and published by notabene itself.

License

MIT