## 1. Project Overview & Quickstart (pmndrs/performance.mdx)
# performance.mdx
Open-source repository pmndrs/performance.mdx
### Repository Details
- **Repository:** [pmndrs/performance.mdx](https://github.com/pmndrs/performance.mdx)
- **Primary Language:** Code
*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*
## 2. Official Technical Reference & Guides (pmndrs/docs)
## File: README.md
[](https://www.chromatic.com/library?appId=696fd126f0e504f96615dec9&branch=main)
[](https://www.chromatic.com/library?appId=6977e41687a50b30c4349650&branch=main)
[](docs/getting-started/introduction.mdx)
[docs/getting-started/introduction.mdx](docs/getting-started/introduction.mdx)
# Usage
## Read
```sh
$ 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](https://docs.pmnd.rs) 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
```sh
$ 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](docs/getting-started/introduction.mdx#Configuration) documents.
Preview a folder of MDX, served
```sh
$ 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](docs/getting-started/introduction.mdx#Configuration) goes in the same way, and
`VERSION` picks a published version of the CLI.
# Releasing
Every push to `main` redeploys [docs.pmnd.rs](https://docs.pmnd.rs) via [ci.yml](.github/workflows/ci.yml) — no [changeset](.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`](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](.github/workflows/chromatic.yml).
You can also replay locally:
```sh
$ npx playwright test --update-snapshots
$ npx chromatic --playwright --project-token $CHROMATIC_PROJECT_TOKEN
```
---
## File: Readme.md
# Poimandres
```bash
git clone https://github.com/pmndrs/website.git
cd website
yarn
yarn dev
```
---
## File: readme.md
# Poimandres
```bash
git clone https://github.com/pmndrs/website.git
cd website
yarn
yarn dev
```
---
## File: docs/getting-started/introduction.mdx
---
title: pmndrs/docs
nav: 0
---
A static MDX documentation generator, with a GitHub [reusable workflow](./github-actions.mdx). It is primarily used for some `pmndrs/*` projects, but will work for anyone.
[Those projects](https://github.com/search?q=%22uses%3A+pmndrs%2Fdocs%2F.github%2Fworkflows%2Fbuild.yml%22+language%3AYAML&type=code&l=YAML) are known to be using this generator.
## INSTALL
Pre-requisites:
- Install [nvm](https://github.com/nvm-sh/nvm), then:
```sh
$ nvm install
$ nvm use
$ node -v # make sure your version satisfies package.json#engines.node
```
nb: if you want this node version to be your default nvm's one:
`nvm alias default node`
```sh
$ git clone https://github.com/pmndrs/docs.git
$ cd docs
$ pnpm install
```
## Configuration
> [!IMPORTANT]
>
> Default value is always: `""` (think *empty*).
| var | description | example |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `MDX`\* | Path to `*.mdx` folderNB: can be relative or absolute | `docs` or `~/code/myproject/documentation` |
| `NEXT_PUBLIC_LIBNAME`\* | Library name | `React Three Fiber` |
| `NEXT_PUBLIC_LIBNAME_SHORT` | Library short name | `r3f` |
| `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL` | Text for the ".docs" suffix link inside the header | `docs` |
| `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF` | Href for the ".docs" suffix link inside the header | `https://docs.pmnd.rs` |
| `BASE_PATH` | Base path for the final URL | `/react-three-fiber` |
| `DIST_DIR` | Path to the output folder ([within project](https://nextjs.org/docs/app/api-reference/next-config-js/distDir#:~:text=should%20not%20leave%20your%20project%20directory)) | `out` or `docs/out/react-three-fiber` |
| `OUTPUT` | Set to `export` for static output | `export` |
| `HOME_REDIRECT` | Where the home should redirect | `/getting-started/introduction` |
| `MDX_BASEURL` | Base URL for inlining relative images | `http://localhost:60141`or `https://github.com/pmndrs/react-three-fiber/raw/master/docs` |
| `SOURCECODE_BASEURL` | Base URL for `sourcecode:` code path | `https://github.com/pmndrs/react-three-fiber/tree/main` |
| `EDIT_BASEURL` | Base URL for displaying "Edit this page" URLs | `https://github.com/pmndrs/react-three-fiber/edit/master/docs` |
| `NEXT_PUBLIC_URL` | Final URL of the published website | `https://pmndrs.github.io/react-three-fiber` |
| `ICON` | Emoji or image to use as (fav)icon (path local to `MDX`) | `🇨🇭` or `/icon.png` or `/favicon.ico` |
| `LOGO` | Logo src/path (either FQURL or local to `MDX` path) | `/logo.png` or `https://worldvectorlogo.com/r3f.png` |
| `GITHUB` | Github URL | `https://github.com/pmndrs/react-three-fiber` |
| `DISCORD` | Discord URL | `https://discord.com/channels/740090768164651008/740093168770613279` |
| `THEME_PRIMARY` | Primary accent color | `#323e48` |
| `THEME_SCHEME` | Theme scheme | `content` or `expressive` or `fidelity` or `monochrome` or `neutral` or `tonalSpot` or `vibrant` |
| `THEME_CONTRAST` | Theme contrast -- value between -1 and 1 | `0` or `-1` or `1` or `-.6` |
| `THEME_NOTE` | "note" color | `#1f6feb` |
| `THEME_TIP` | "tip" color | `#238636` |
| `THEME_IMPORTANT` | "important" color | `#8957e5` |
| `THEME_WARNING` | "warning" color | `#d29922` |
| `THEME_CAUTION` | "caution" color | `#da3633` |
| `CONTRIBUTORS_PAT` | GitHub token for contributors API (see: https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators) | `ghp_1234567890` |
\* Required
`MDX_BASEURL`
Given a `advanced/introduction.mdx` file in the `MDX` folder:
```md
```
becomes (for a `MDX_BASEURL=http://localhost:60141` value):
```md
```
`http://localhost:60141` being the `MDX` folder served.
> [!TIP]
> When deployed on GitHub Pages, `MDX_BASEURL` will typically value something like `https://github.com/pmndrs/uikit/raw/main/docs`, thanks to [`build.yml`](.github/workflows/build.yml) rule.
`THEME_*`
We implement [m3 design system](https://m3.material.io/styles/color/system/overview), using [material-theme-builder](https://github.com/abernier/material-theme-builder).
[](https://github.com/abernier/material-theme-builder)
> [!NOTE]
> - [Material Color](https://www.youtube.com/playlist?list=PLsoLz-E4Os4WWkrvRuQ7BJuVF-WfOyfWT) for more information
> - We currently don't have secondary/tertiary colors (maybe some day).
## Usage
### dev
```sh
$ (
trap 'kill -9 0' SIGINT
export _PORT=60141
export MDX=docs
export NEXT_PUBLIC_LIBNAME="Poimandres"
export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs"
export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs"
export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs"
export BASE_PATH=
export DIST_DIR=
export OUTPUT=
export HOME_REDIRECT=
export MDX_BASEURL=http://localhost:$_PORT
export SOURCECODE_BASEURL="vscode://file$(pwd)"
export EDIT_BASEURL="vscode://file$(pwd)/docs"
export NEXT_PUBLIC_URL=
export ICON=
export LOGO=gutenberg.jpg
export GITHUB=https://github.com/pmndrs/docs
export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
export THEME_PRIMARY="#323e48"
export THEME_SCHEME="tonalSpot"
export THEME_CONTRAST="0"
export THEME_NOTE="#1f6feb"
export THEME_TIP="#238636"
export THEME_IMPORTANT="#8957e5"
export THEME_WARNING="#d29922"
export THEME_CAUTION="#da3633"
export CONTRIBUTORS_PAT=
kill $(lsof -ti:"$_PORT")
npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &
pnpm run dev &
wait
)
```
Then go to: http://localhost:3000
> [!TIP]
> If `HOME_REDIRECT=` empty, `/` will not redirect, and instead displays an index of libraries.
### build
```sh
$ (
trap 'kill -9 0' SIGINT
rm -rf out
export _PORT=60141
export MDX=docs
export NEXT_PUBLIC_LIBNAME="Poimandres"
export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs"
export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs"
export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs"
export BASE_PATH=
export DIST_DIR=
export OUTPUT=export
export HOME_REDIRECT=/getting-started/introduction
export MDX_BASEURL=http://localhost:$_PORT
export SOURCECODE_BASEURL=
export EDIT_BASEURL=
export NEXT_PUBLIC_URL=
export ICON=
export LOGO=gutenberg.jpg
export GITHUB=https://github.com/pmndrs/docs
export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
export THEME_PRIMARY="#323e48"
export THEME_SCHEME="tonalSpot"
export THEME_CONTRAST="0"
export THEME_NOTE="#1f6feb"
export THEME_TIP="#238636"
export THEME_IMPORTANT="#8957e5"
export THEME_WARNING="#d29922"
export THEME_CAUTION="#da3633"
export CONTRIBUTORS_PAT=
pnpm run build
kill $(lsof -ti:"$_PORT")
npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &
npx serve out &
wait
)
```
http://localhost:3000
### CLI
No clone, no install — the published CLI does the same build:
```sh
$ cd ~/code/pmndrs/react-three-fiber
$ (
trap 'kill -9 0' SIGINT
export _PORT=60141
export NEXT_PUBLIC_LIBNAME="React Three Fiber"
export NEXT_PUBLIC_LIBNAME_SHORT="r3f"
export BASE_PATH=/toto
export HOME_REDIRECT=/getting-started/introduction
export MDX_BASEURL=http://localhost:$_PORT
export ICON=🇨🇭
export GITHUB=https://github.com/pmndrs/react-three-fiber
npx -y @pmndrs/docs@latest build docs docs/out --format website
kill $(lsof -ti:"$_PORT")
npx serve docs -p $_PORT --no-port-switching --no-clipboard &
npx -y serve docs/out &
wait
)
```
Then go to: http://localhost:3000
Every option above has a flag too — `npx @pmndrs/docs@latest build --help` lists them.
## Agents
`llms.txt` dumps and the pmndrs MCP server moved to their own page: [Agents](/agents/introduction).