/notabene-authoring

name: notabene-authoring
description: >-
  What you can put in a notabene doc — the full rendering palette, so you can author or
  expand documentation using everything the renderer supports. Use when writing or editing
  docs in a notabene repo: "write the documentation for X", "add a docs page", "document
  this feature", "add a diagram / flowchart / ER diagram to the docs", "what Markdown/MDX
  features does notabene support", "make the docs richer". Covers CommonMark/GFM, code +
  syntax highlighting, Mermaid diagrams, inter-doc links, images, and the MDX-safety rules.
  This skill does NOT install/configure notabene (that's `notabene-setup`) or process review
  comments (that's `notabene`) — it's the authoring reference for the content itself.

<!-- Generated from docs/guide/authoring.md + packages/claude-plugin/overlays/notabene-authoring.md by scripts/gen-protocol.mjs — do not edit. -->

Authoring notabene docs — the rendering palette

What actually renders in a notabene site, so you can write a **complete** doc with every tool available and nothing that silently degrades to plain text. Docs are plain files in the repo (Markdown/MDX), rendered by the notabene renderer (Astro + GFM + Shiki + Mermaid).

Run every CLI command shown below through the plugin forwarder — `node "${CLAUDE_PLUGIN_ROOT}/bin/nb.mjs" <cmd> --root <repo-root>` — never `npx notabene` (unscoped: not our package).

First: know the format

Read `format` in `notabene.config.mjs` (or run `npx -y @z29k/notabene@latest doctor --json`). It decides the pipeline:

• **`commonmark`** (the `init` default) — globs `.md` + `.markdown`, **lenient** CommonMark/GFM,

**no MDX**. `<`, `{`, `Promise<T>`, raw HTML, GFM tables all render without a crash. Simplest.

• **`mdx`** — globs `.md` + `.mdx`. `.md` stays lenient; **`.mdx` is strict** (JSX/expressions):

a stray `{` or `<` outside a code fence is a build error.

Everything below works in **both** formats. The MDX-only extras (components/expressions) are called out at the end.

The palette (all verified to render)

• **Prose + CommonMark**: headings, lists, `**bold**`, `_italic_`, `> blockquotes`, `---` rules,

inline `` `code` ``, links.

• **GFM**: tables, task lists (`- [ ] todo` / `- [x] done`), `~~strikethrough~~`, autolinks,

footnotes (`text[^1]` … `[^1]: note`).

• **Code blocks with syntax highlighting** — fenced with a language, highlighted by **Shiki**

(`github-dark` unless the site sets its own [code theme](./customize.md), soft-wrap on). Any Shiki-supported language:

  ```ts
  export const x: number = 1;

- **Mermaid diagrams** — see the next section (the reason this palette exists).
- **Inter-doc links**: link between docs with **relative `.md`/`.mdx` paths**
  (`[see setup](../guide/setup.md)`) — they're auto-rewritten to site routes. External/absolute/
  anchor links are left as-is.
- **Images**: standard Markdown `![alt](path)` (also good for embedding a pre-rendered SVG — see MCD below).
- **Headings drive the page**: the **first `# H1`** becomes the page title (unless frontmatter
  `title` overrides it — see *Page metadata* below), and headings build the table of contents +
  anchor links. Use **one H1** per page.

## Page metadata: title, sidebar label & order (frontmatter)

Optional YAML frontmatter at the very top of a page controls how it appears in the **sidebar**,
**breadcrumb** and **page `<title>`** — so you don't have to encode ordering as numeric
file-name prefixes:

```yaml
---
title: Cartographie du réseau interne   # page <title> + breadcrumb (overrides the H1)
description: Plan des segments et VLANs # public builds: meta description + OpenGraph
publish: false                          # public builds: keep this page OUT of `build --public`
sidebar:
  label: Cartographie                   # sidebar text (else title, else humanized file name)
  order: 9                              # position among siblings (ascending)
---

• **Sidebar label** resolves `sidebar.label` → `title` → humanized file name. Set

`sidebar.label` to keep a short sidebar entry while the H1 / `title` stays verbose.

• **`order`** sorts siblings ascending. Entries **without** `order` keep sorting

alphabetically, after the ordered ones — and groups and pages share one ordering, so a numbered folder slots into a numbered page sequence without any file-name prefix.

• **A folder** is named and ordered by its **landing page** — `<folder>/index.md` (whose id

collapses to the folder path) or `<folder>/readme.md`. Put the `sidebar` frontmatter there and it applies to the whole group; that page becomes the group's *Overview* entry (label localized per UI language, e.g. FR *Aperçu* — override it with `sidebar.indexLabel`).

• **`description`** feeds the meta description / OpenGraph / JSON-LD of a **public build**

(`notabene build --public`) — one plain sentence summarizing the page.

• **`publish: false`** keeps the page **out of public builds** entirely (route, nav, search,

`llms.txt`, Markdown twin, sitemap) — the dev/review site always shows it. **Preserve this key when editing a page that carries it.** Whole spaces (`roots[].publish: false`) and sub-trees (`publish.exclude` globs in the config) scope the same way. **Don't link from a public page to private content** — the link 404s in the public artifact and the build won't warn; check the target's frontmatter (and the config's `publish.exclude` / `roots[].publish`) before adding an inter-doc link.

• **`lastUpdated`** overrides the *Updated on* date in the page footer (normally the page's

git author date). Set it only when git history misleads — imported or generated content; any date-parsable value.

• Frontmatter is **optional**: with none, the sidebar shows humanized file names sorted

alphabetically (unchanged). Only `title`, `description`, `publish`, `lastUpdated` and `sidebar` are interpreted — any other keys pass through untouched.

Mermaid diagrams