pmndrs docs

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

Both formats use the same Next.js build and static export. --format fragment (the default) extracts the compiled MDX from that export: no layout, no stylesheet, no script. Mermaid diagrams stay fenced blocks, and Sandpack shows its code without the editor.

Rendering a document runs next build, including a single file or stdin. For those inputs, stdout contains only the HTML; build logs go to stderr. esbuild is used only to package the CLI for publication, not to load consumer components or render documents.

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.

To use your repository's React components and shared data in MDX, add docs.config.ts in the current working directory. Use --config path/to/config.ts or DOCS_CONFIG for another location; the flag takes precedence. See custom components and data for the configuration, website rendering, and HTML fragment behavior.

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

Markdown exports

Copy Page, View as Markdown (/<page>.md), and llms-full.txt use the same document renderer. MDX expressions resolve against scope, including values inside Markdown tables, JSX attributes and commands. Headings, tables, lists, links, images and code are serialized as Markdown. Formatting is normalized; the MDX files are never rewritten. Inline code and fenced examples remain literal, including their braces and JSX.

Built-in components have static representations: tabs include every panel, code blocks include their authored commands, Mermaid keeps its diagram source, and theme presets expose their declared values. Color previews expose their role or CSS value, without computing browser styles. Sandpack and live embeds provide a static notice or destination; contributor and backer lists provide links.

Custom server-renderable components use their rendered content, including async components. A client component that Next exposes as an opaque reference uses a notice and its authored children. Components that need browser APIs, providers, or a particular interactive state should supply a server-renderable alternative in markdownComponents:

import type { DocsConfig } from '@pmndrs/docs/src/config'
import { Example } from './docs/authoring/Example'
import example from './docs/authoring/Example.json'

export default {
  components: { Example },
  scope: { example },
  markdownComponents: {
    Example: ({ initialCount }: { initialCount: number }) => `Count: ${initialCount}`,
  },
} satisfies DocsConfig

markdownComponents overrides both built-in and configured components for Markdown exports only. Keep these alternatives free of client dependencies, including nested client components. Exports describe the authored or initial state at build time; they do not capture a reader's selected tab, edited playground, or theme preferences. Unresolved expressions and rendering errors fail the export with the document path instead of returning raw MDX.

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-playwright.yml and chromatic-storybook.yml.

• pnpm run lgtm — fast gate: types, lint, registry validation, unit tests.
• pnpm run LGTM — full gate CI runs: lgtm + Playwright.

Playwright checks that the custom components example renders the configured data and responds to interaction.

Screenshots Playwright writes locally are throwaway — Chromatic holds the baselines.

$ pnpm run LGTM
$ npx chromatic --playwright --project-token $CHROMATIC_PROJECT_TOKEN