docs/getting-started/introduction.mdx

Usage

Read

$ npx @pmndrs/docs                                 # the reader: every library, every page
$ npx @pmndrs/docs drei                            # straight into one
$ npx @pmndrs/docs drei/performances/instances     # straight to a page
$ npx @pmndrs/docs search instanced mesh           # one result per line, on stdout

↑↓ drives whichever pane has the focus — the list of pages, or the page itself. ⏎ or ⇥ hands the focus over, esc or ⇥ hands it back, and the lit border says where it is — the wheel moves whichever pane it points at, focus or no focus. ←→ changes library, b folds the sidebar away, / searches every library at once, o opens the page in a browser, q quits. Links inside a page are clickable wherever the terminal honours OSC 8 hyperlinks — iTerm2, Ghostty, WezTerm, Kitty, Windows Terminal.

search is the half a pipe or an agent can use: results read {lib} {path} - {title}, the shape the MCP server publishes its index in, and nothing found exits 1. --in drei narrows to one library, --in drei/performances/instances to the matching lines of one page.

Both read the published llms-full.txt of each library, cached for an hour under ~/.cache/pmndrs-docs — --refresh fetches again. Outside a terminal, a page target is written to stdout, so npx @pmndrs/docs drei/performances/instances | glow works.

Build

$ cat foo.mdx | npx @pmndrs/docs@latest build               # one HTML fragment, on stdout
$ npx @pmndrs/docs@latest build docs out                    # one .html per .mdx, assets alongside
$ npx @pmndrs/docs@latest build docs out --format website   # the whole website, statically exported

--format fragment (the default) needs nothing but node — no next build, no bundler. A fragment is the compiled MDX and nothing else: no layout, no stylesheet, no script. Mermaid diagrams stay fenced blocks, and Sandpack shows its code without the editor.

build --help lists every website option — --libname, --base-path, --icon, --theme-*… Each one falls back to the environment variable it maps to, the same ones configuration documents.

$ curl -sL https://raw.githubusercontent.com/pmndrs/docs/refs/heads/main/preview.sh | \
  MDX="docs" \
  ICON="🥑" \
  sh

Builds the website, then serves it — alongside the MDX folder itself, so relative assets resolve while you edit. Any option from configuration goes in the same way, and VERSION picks a published version of the CLI.

Releasing

Every push to main redeploys docs.pmnd.rs via ci.yml — no changeset needed for that.

Add one (pnpm changeset) only when downstream consumers pinning pmndrs/docs/.github/workflows/build.yml@v4 or @pmndrs/docs@4 should pull the change. It bumps package.json, publishes to npm, and tags vX.Y.Z + vX — so @v4 resolves to the latest.

TL;DR — site-only tweak: skip. Anything consumers see (workflow, build behavior, templates): add one.

Test

Visual tests are performed in the cloud, through chromatic.yml.

You can also replay locally:

$ npx playwright test --update-snapshots
$ npx chromatic --playwright --project-token $CHROMATIC_PROJECT_TOKEN