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