Poimandres

Full documentation content.

<page path="/getting-started/introduction" title="pmndrs/docs"><![CDATA[URL: /getting-started/introduction
Description: Documentation generator for `pmndrs/*` projects.


<Badge href="https://www.npmjs.com/package/@pmndrs/docs" logo="npm" label="npm">@pmndrs/docs</Badge>
<Badge href="https://main--6977e41687a50b30c4349650.chromatic.com" logo="storybook">storybook</Badge>
<Badge href="https://www.chromatic.com/library?appId=6977e41687a50b30c4349650&branch=main" logo="chromatic" label="chromatic">storybook</Badge>
<Badge href="https://www.chromatic.com/library?appId=696fd126f0e504f96615dec9&branch=main" logo="chromatic" label="chromatic">playwright</Badge>

<Intro>
  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.
</Intro>

![Gutenberg lithography](gutenberg.jpg)

[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` folder<br/>NB: 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`                                                                                            |
| `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 (its star count shows next to the header link)                                                                                                                | `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`                                                                                        |
| `THEME_STORYBOOK`                     | "storybook" color                                                                                                                                                        | `#ff4785`                                                                                        |
| `THEME_NPM`                           | "npm" color                                                                                                                                                              | `#cb3837`                                                                                        |
| `THEME_CHROMATIC`                     | "chromatic" color                                                                                                                                                        | `#fc521f`                                                                                        |
| `CONTRIBUTORS_PAT`                    | GitHub token for contributors API and the header star count (see: https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators) | `ghp_1234567890`                                                                                 |
| `LIB_VERSION`                         | Version label in the sidebar footer (default: `git describe --tags`)                                                                                                     | `v1.2.3`                                                                                         |
| `TAG_MATCH`                           | Tags the version label is read from (`git describe --match`)                                                                                                             | `v*.*.*`                                                                                         |
| `VERSION_URL_TEMPLATE`                | URL of a branch deployment; enables the [version switcher](#version-switcher)                                                                                            | `https://mylib-git-{branch:vercel}-myteam.vercel.app`                                            |
| `VERSION_PRODUCTION_BRANCH`           | Production branch (default: `main`)                                                                                                                                      | `master`                                                                                         |
| `VERSION_PRODUCTION_URL`              | Production branch URL (default: `NEXT_PUBLIC_URL`)                                                                                                                       | `https://docs.pmnd.rs`                                                                           |
| `VERSION_BRANCHES`                    | Regex of the branches the switcher offers                                                                                                                                | `^(main\|next\|v\d+)$`                                                                           |
| `VERSION_BRANCHES_LIST`               | Branches the switcher offers, instead of the remote's                                                                                                                    | `main,next,v9`                                                                                   |

\* Required

<details>
  <summary>`MDX_BASEURL`</summary>

Given a `advanced/introduction.mdx` file in the `MDX` folder:

```md
![](dog.png)
```

becomes (for a `MDX_BASEURL=http://localhost:60141` value):

```md
![](http://localhost:60141/advanced/dog.png)
```

`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.

</details>

<details>
  <summary>`THEME_*`</summary>

We implement [m3 design system](https://m3.material.io/styles/color/system/overview), using [material-theme-builder](https://github.com/abernier/material-theme-builder).

<div className="@container">
  <iframe src="https://main--695eb517cb602e59b4cc045c.chromatic.com/iframe.html?id=mtb--st-1&viewMode=story"
    title="material-theme-builder color scheme"
    className="w-full h-[376px] @3xl:h-[675px] rounded-lg"
  />
  <p className="mt-1 text-xs text-on-surface-variant">This is an embed iframe of [material-theme-builder's `<Mtb>` story](https://main--695eb517cb602e59b4cc045c.chromatic.com/?path=/story/mtb--st-1).</p>
</div>

> [!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).

</details>

<details id="version-switcher">
  <summary>`VERSION_*`, `LIB_VERSION`, `TAG_MATCH`</summary>

- Label: `git describe --tags` (eg. `v10.7.9`, `v10.7.9-3-ga1b2c3d`), or `<branch>@<shortsha>` without tags. `LIB_VERSION` overrides it.
- `TAG_MATCH` narrows the tags:

| repo tags                  | `TAG_MATCH` |
| -------------------------- | ----------- |
| `v10.7.9`, `v10`           | `v*.*.*`    |
| `leva@0.10.1`, `other@1.0` | `leva@*`    |

- `VERSION_URL_TEMPLATE` enables the switcher: the label lists the branches, each leading to the same page on its deployment. Full public URL (base path included), with a placeholder:

| placeholder       | `feat/Dark_mode` becomes | for                    | example                                               |
| ----------------- | ------------------------ | ---------------------- | ----------------------------------------------------- |
| `{branch}`        | `feat-dark-mode`         | URLs you create        | `https://docs-git-{branch}-pmndrs.vercel.app`         |
| `{branch:vercel}` | `feat-darkmode`          | Vercel Git integration | `https://mylib-git-{branch:vercel}-myteam.vercel.app` |
| `{branch:raw}`    | `feat%2FDark_mode`       | a path or query string | `https://example.com/preview?branch={branch:raw}`     |

- `VERSION_PRODUCTION_BRANCH` leads to `VERSION_PRODUCTION_URL`; every other branch shows a banner linking to production.
- Branches: the remote's, minus `dependabot/`, `renovate/`, `changeset-release/`. `VERSION_BRANCHES` replaces that filter, `VERSION_BRANCHES_LIST` the whole list. Read at build time.

> [!IMPORTANT]
>
> - The per-branch URLs are yours to create: Vercel's Git integration does, `vercel deploy` does not (`vercel alias set`, see [`ci.yml`](https://github.com/pmndrs/docs/blob/main/.github/workflows/ci.yml)).
> - Git needs full history and tags (`fetch-depth: 0`).

</details>

## Usage

### dev

This is [`dev.sh`](https://github.com/pmndrs/docs/blob/main/dev.sh). The site listens on `PORT` (default `3000`), the MDX folder on any free port, so several checkouts can run side by side:

```sh
$ (
  trap 'kill -9 0' SIGINT

  export PORT=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="Poimandres"
  export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs"
  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 THEME_STORYBOOK="#ff4785"
  export THEME_NPM="#cb3837"
  export THEME_CHROMATIC="#fc521f"
  export CONTRIBUTORS_PAT=

  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

This is [`start.sh`](https://github.com/pmndrs/docs/blob/main/start.sh), same ports:

```sh
$ (
  trap 'kill -9 0' SIGINT

  # `next dev` leaves types pointing at `src/app/api`, which the export build moves aside
  rm -rf out .next/dev/types

  export PORT=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="Poimandres"
  export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs"
  export BASE_PATH=
  export DIST_DIR=
  export OUTPUT=export
  export HOME_REDIRECT=
  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 THEME_STORYBOOK="#ff4785"
  export THEME_NPM="#cb3837"
  export THEME_CHROMATIC="#fc521f"
  export CONTRIBUTORS_PAT=

  pnpm run build

  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  npx serve out -p $PORT &

  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=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  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

  npx serve docs -p $_PORT --no-port-switching --no-clipboard &

  npx -y serve docs/out -p $PORT &

  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).
]]></page>
<page path="/authoring/introduction" title="Authoring"><![CDATA[URL: /authoring/introduction
Description: How to write documentation


<Intro>
  This is a guide on how to write documentation. We support all [GFM](https://github.github.com/gfm/) syntax, plus some custom components that are described here.
</Intro>

<Keypoints>
  <KeypointsItem>[Front matter](#frontmatter) metadatas</KeypointsItem>
  <KeypointsItem>Custom [markdown](#markdown) components</KeypointsItem>
</Keypoints>

In your `MDX` folder, create any `path/to/my-document.mdx`:

```md
---
title: My Document
description: Lorem ipsum...
nav: 0
image: dog.png
sourcecode: to/my-document.mdx
---

MARKDOWN
```

## Frontmatter

Any key is optional.

- `title`: if not provided, last part of the path is used: `my document`
- `description`
- `sourcecode`: relative path to the source-code file
- `image`:
  - relative (to the md file) or absolute path, eg: `dog.png`, `./dog.png`, `../../dog.png`, `/dog.png` or `https://animals.com/dog.png`
  - will be used as metadata image if provided
- `nav`: order in the navigation (on the same level)

> [!TIP]
>
> `title` and `description` support markdown:
>
> ```yaml
> ---
> title: "`Intro` component"
> description: Introduction component for **documentation** pages with `code` and [links](#test)
> ---
> ```
> ⚠️ If starting with backtick, eg ``title: "`Intro` component"`` wrap in quotes!

## MARKDOWN

Worth mentioning, you can use **standard HTML**, with [tailwind](https://tailwindcss.com) support:

```md
<div>
  <iframe src="https://drei.pmnd.rs/iframe.html?globals=&args=&id=staging-accumulativeshadows--accumulative-shadow-st&viewMode=story" 
    className="w-full h-60 rounded-lg"
  />
  <p className="mt-1 text-xs text-on-surface-variant">This is an embed iframe of [Drei's `<AccumulativeShadows>` story](https://drei.pmnd.rs/?path=/docs/staging-accumulativeshadows--docs).</p>
</div>
```

result:

<div>
  <iframe src="https://drei.pmnd.rs/iframe.html?globals=&args=&id=staging-accumulativeshadows--accumulative-shadow-st&viewMode=story" 
    className="w-full h-60 rounded-lg"
  />
  <p className="mt-1 text-xs text-on-surface-variant">This is an embed iframe of [Drei's `<AccumulativeShadows>` story](https://drei.pmnd.rs/?path=/docs/staging-accumulativeshadows--docs).</p>
</div>

> [!TIP]
>
> We use [material-theme-builder](https://github.com/abernier/material-theme-builder) colors, eg: `text-on-surface-variant` above

Plus:
- any [GitHub Flavored Markdown](https://github.github.com/gfm/) syntax.
- all exported [`components/mdx/index.tsx`](components/mdx/index.tsx) MDX components.

See the following pages for detailed documentation on each custom component.
]]></page>
<page path="/authoring/intro" title="`Intro`"><![CDATA[URL: /authoring/intro
Description: Introduction component for **documentation** pages with `code` and [links](#test)


<Intro>
  Prominent introduction with rich markdown support.
</Intro>

Use at the top of the document, just after the frontmatter.

```md
<Intro>
  This is an intro. Here you can write a long description of the article, longer than the frontmatter `description`, eventually with [links](#), lists, etc.
  
  Multiple paragraphs are also possible, or anything.
</Intro>
```

result:

<Intro>
  This is an intro. Here you can write a long description of the article, longer than the frontmatter `description`, eventually with [links](#), lists, etc.
  
  Multiple paragraphs are also possible, or anything.
</Intro>
]]></page>
<page path="/authoring/keypoints" title="`Keypoints`"><![CDATA[URL: /authoring/keypoints
Description: Keypoints component for highlighting main article topics


<Intro>
  Highlights key takeaways as a visually distinct bulleted list.
</Intro>

Can be used after `Intro`, to list main points the article covers: one bullet per `KeypointsItem`.

```md
<Keypoints title="What you'll learn">
  <KeypointsItem>First item</KeypointsItem>
  <KeypointsItem>Second **item**</KeypointsItem>
</Keypoints>
```

result:

<Keypoints title="What you'll learn">
  <KeypointsItem>First item</KeypointsItem>
  <KeypointsItem>Second **item**</KeypointsItem>
</Keypoints>
]]></page>
<page path="/authoring/img" title="`Img`"><![CDATA[URL: /authoring/img
Description: Using images in documentation


<Intro>
  Display images using markdown or HTML syntax with automatic dimensions and relative path support.
</Intro>

Relative images are supported. Eg, inside your [`MDX`](introduction#configuration:~:text=MDX) folder:
```text {2}
|-- authoring
|   |-- img.mdx  <= relative to this article
|   `-- gutenberg.jpg
```

```md
---
title: Authoring
---

![](gutenberg.jpg)
```

result:

![](gutenberg.jpg)

> [!TIP]
> You are encouraged to use relative images, since dimensions are automatically added as `img[width][height]` attributes.
>
> For others, think about adding them to **prevent layout shift**.

---

It is also possible to specify only one dimension (other is inferred from intrinsic ratio), eg:

```md
<img src="gutenberg.jpg" height="200" />
```

result:

<img src="gutenberg.jpg" height="200" />

---

Although it is probably better to use CSS for this:

```md
<img src="gutenberg.jpg" style={{width: 'auto', height: '10rem'}} />
```

result:

<img src="gutenberg.jpg" style={{width: 'auto', height: '10rem'}} />

> [!NOTE]
> See [`MDX_BASEURL`](/getting-started/introduction#configuration:~:text=MDX_BASEURL) to understand how it is converted to a full URL.
]]></page>
<page path="/authoring/code" title="`Code`"><![CDATA[URL: /authoring/code
Description: Code blocks with syntax highlighting and line numbers


<Intro>
  Code blocks with syntax highlighting.
</Intro>

Line numbers/highlights are supported:

````md
```tsx {1,4-6} showLineNumbers
type Props = {who: string}

function Hi({who}: Props) {
  return (
    <p>Hello, {who}!</p>
  )
}
```
````

result:

```tsx {1,4-6} showLineNumbers
type Props = {who: string}

function Hi({who}: Props) {
  return (
    <p>Hello, {who}!</p>
  )
}
```

---

You can start at a specific `X` line number `showLineNumbers=X`:

````md
```tsx {1,4-6} showLineNumbers=150
type Props = {who: string}

function Hi({who}: Props) {
  return (
    <p>Hello, {who}!</p>
  )
}
```
````

result:

```tsx {1,4-6} showLineNumbers=150
type Props = {who: string}

function Hi({who}: Props) {
  return (
    <p>Hello, {who}!</p>
  )
}
```

---

`diff` format is supported:

````md
```diff
diff --git a/example.txt b/example.txt
index 8c3317a..47ea956 100644
--- a/example.txt
+++ b/example.txt
@@ -1,4 +1,4 @@
-Hello, World!
+Hello, GitHub World!
 Here are some changes:
-This line will be modified.
+This line has been modified.
 This line will stay the same.
```
````

result:

```diff
diff --git a/example.txt b/example.txt
index 8c3317a..47ea956 100644
--- a/example.txt
+++ b/example.txt
@@ -1,4 +1,4 @@
-Hello, World!
+Hello, GitHub World!
 Here are some changes:
-This line will be modified.
+This line has been modified.
 This line will stay the same.
```
]]></page>
<page path="/authoring/mermaid" title="Mermaid"><![CDATA[URL: /authoring/mermaid
Description: Creating diagrams with Mermaid


<Intro>
  [Mermaid](https://mermaid.js.org/) text-based diagrams. Automatically adapt to light/dark theme.
</Intro>

````md
```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
    C --> E[End]
```
````

result:

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
    C --> E[End]
```

---

````md
```mermaid
sequenceDiagram
    participant User
    participant Browser
    User->>Browser: Click button
    Browser-->>User: Display result
```
````

result:

```mermaid
sequenceDiagram
    participant User
    participant Browser
    User->>Browser: Click button
    Browser-->>User: Display result
```

---

[KaTeX support](https://github.com/mermaid-js/mermaid/pull/2885):

````md
```mermaid
graph LR
    A["$$f(\relax{x}) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2 \pi i \xi x}\,d\xi$$"] -->|"$$\Bigg(\bigg(\Big(\big((\frac{-b\pm\sqrt{b^2-4ac}}{2a})\big)\Big)\bigg)\Bigg)$$"| B("$$1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots}}}}$$")
    A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\phase{-78^\circ}$$")
    B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$")
    C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$")
```
````

result:

```mermaid
graph LR
    A["$$f(\relax{x}) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2 \pi i \xi x}\,d\xi$$"] -->|"$$\Bigg(\bigg(\Big(\big((\frac{-b\pm\sqrt{b^2-4ac}}{2a})\big)\Big)\bigg)\Bigg)$$"| B("$$1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots}}}}$$")
    A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\phase{-78^\circ}$$")
    B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$")
    C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$")
```]]></page>
<page path="/authoring/grid" title="`Grid` (Deprecated)"><![CDATA[URL: /authoring/grid
Description: Responsive grid layout component


> [!CAUTION]
>
> Deprecated, use [tailwind `grid-cols-*`](https://tailwindcss.com/docs/grid-template-columns) instead.

<Intro>
  Responsive grid layout.
</Intro>

```md
<Grid cols={2}>
  <li>A</li>
  <li>B</li>
  <li>C</li>
  <li>D</li>
  <li>E</li>
  <li>F</li>
  <li>G</li>
</Grid>
```

result:

<Grid cols={2}>
  <li>A</li>
  <li>B</li>
  <li>C</li>
  <li>D</li>
  <li>E</li>
  <li>F</li>
  <li>G</li>
</Grid>]]></page>
<page path="/authoring/sandpack" title="`Sandpack`"><![CDATA[URL: /authoring/sandpack
Description: Inline sandboxes for interactive code examples


<Intro>
  Interactive code sandboxes powered by CodeSandbox.
</Intro>

> [!NOTE]
> See Sandpack [official documentation](https://sandpack.codesandbox.io/docs/getting-started/usage) for full usage.

> [!WARNING]
> Pin `three` to `0.185.1` or lower: since `0.186.0`, its CommonJS entry calls `process.emitWarning`, which Sandpack's in-browser bundler does not provide (the preview fails with `process.emitWarning is not a function`).

```tsx
<Sandpack
  template="react-ts"
  customSetup={{
    dependencies: {
      'three': '0.185.1',
      '@react-three/fiber': 'latest',
      '@react-three/drei': 'latest'
    },
  }}
  files={{
    '/styles.css': `html,body,#root {height:100%;margin:unset;}`,
    '/App.tsx': `import { Canvas } from '@react-three/fiber'
import { Cloud, CameraControls } from '@react-three/drei'

export default function App() {
  return (
    <Canvas camera={{position: [0,-13,0]}}>
      <Cloud speed={.4} growth={6} />
      <ambientLight intensity={Math.PI} />
      <CameraControls />
    </Canvas>
  )
}`,
  }}
/>
```

result:

<Sandpack
  template="react-ts"
  customSetup={{
    dependencies: {
      'three': '0.185.1',
      '@react-three/fiber': 'latest',
      '@react-three/drei': 'latest'
    },
  }}
  files={{
    '/styles.css': `html,body,#root {height:100%;margin:unset;}`,
    '/App.tsx': `import { Canvas } from '@react-three/fiber'
import { Cloud, CameraControls } from '@react-three/drei'

export default function App() {
  return (
    <Canvas camera={{position: [0,-13,0]}}>
      <Cloud speed={.4} growth={6} />
      <ambientLight intensity={Math.PI} />
      <CameraControls />
    </Canvas>
  )
}`,
  }}
/>

> [!TIP]
> Sandpack UI SSR-rendering[^1] is also supported (out of the box).

[^1]: https://sandpack.codesandbox.io/docs/guides/ssr#nextjs-app-dir  

#### `Sandpack[folder]`

Instead of `files`, a `folder` prop allows you to pass a folder containing all the files:

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
/>
```

`folder` path is relative to the `.mdx` file:

```text
|-- getting-started
|   |-- authoring.mdx             <= relative to this article
|   `-- authoring-sandpack-cloud     <= the folder
```

> [!TIP]
> It will simply:
> - build the `files` prop for you (including all `.{js|ts|jsx|tsx|css}` it finds)
> - build `customSetup.dependencies` from `package.json` if it exists

result:

<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
/>

---

It is also possible to pass some individual [file format](https://sandpack.codesandbox.io/docs/getting-started/usage#file-format) configuration:

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  files={{
    '/App.tsx': {
      readOnly: true,
      active: true,
    },
    '/styles.css': {
      hidden: true
    }
  }}
/>
```

result:

<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  files={{
    '/App.tsx': {
      readOnly: true,
      active: true,
    },
    '/styles.css': {
      hidden: true
    }
  }}
/>

#### `Sandpack[fileExplorer]`

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  fileExplorer
/>
```

result:

<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  fileExplorer
/>

> [!TIP]
> Conveniently, enabling `fileExplorer` will by default `[codeEditor={showTabs: false}]`.
> You can override it with [`[codeEditor]` options](#sandpack[codeeditor])

---

You can also pass [any `fileExplorer={options: ComponentProps<SandpackFileExplorer>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#file-explorer:~:text=Preview-,Options,-If%20you%27re%20looking).

#### `Sandpack[codeEditor]`

You can pass [any `codeEditor={options: ComponentProps<SandpackCodeEditor>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-editor:~:text=Preview-,Options,-Extensions).

#### `Sandpack[codeViewer]`

It will render the [`SandpackCodeViewer`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-viewer) instead of the default [`SandpackCodeEditor`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-editor).

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  codeViewer
/>
```

result:

<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  codeViewer
/>

You can also pass [any `codeViewer={options: ComponentProps<SandpackCodeViewer>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-viewer:~:text=Preview-,Options,-CodeMirror%20decorations).

##### `Sandpack[codeViewer][filesDecorators]`

You can define per-file [decorators](https://sandpack.codesandbox.io/docs/advanced-usage/components#codemirror-decorations) through `filesDecorators` prop:

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  codeViewer={{
    filesDecorators: {
      '/App.tsx': [
        { className: "highlight", line: 1 },
        { className: "highlight", line: 7 },
        {
          className: "widget",
          elementAttributes: { "data-id": "1" },
          line: 7,
          startColumn: 13,
          endColumn: 24,
        },
        {
          className: "widget",
          elementAttributes: { "data-id": "2" },
          line: 7,
          startColumn: 25,
          endColumn: 35,
        },
        
      ],
      '/styles.css': [
        { className: "highlight", line: 4 },
      ]
    }
  }}
/>
```

result:

<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  codeViewer={{
    filesDecorators: {
      '/App.tsx': [
        { className: "highlight", line: 1 },
        { className: "highlight", line: 7 },
        {
          className: "widget",
          elementAttributes: { "data-id": "1" },
          line: 7,
          startColumn: 13,
          endColumn: 24,
        },
        {
          className: "widget",
          elementAttributes: { "data-id": "2" },
          line: 7,
          startColumn: 25,
          endColumn: 35,
        },
        
      ],
      '/styles.css': [
        { className: "highlight", line: 4 },
      ]
    }
  }}
/>

#### `Sandpack[preview]`

You can pass [any `preview={options: ComponentProps<SandpackPreview>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#preview:~:text=Preview-,Options,-Additional%20buttons).
]]></page>
<page path="/authoring/codesandbox" title="`Codesandbox`"><![CDATA[URL: /authoring/codesandbox
Description: Embed Codesandbox examples


<Intro>
  Embed live CodeSandbox examples.
</Intro>

Give the sandbox a preview image with `img`. Like an [`<img src>`](img), it can be relative to
the article:

```text {2}
|-- authoring
|   |-- codesandbox.mdx  <= relative to this article
|   `-- cell-fracture.webp
```

```md
<Codesandbox id="3rjsl" title="Cell fracture" img="cell-fracture.webp" />
```

result:

<Codesandbox id="3rjsl" title="Cell fracture" img="cell-fracture.webp" />

> [!TIP]
> A relative `img` gets its dimensions added automatically, just as a relative [`Img`](img) does.
> A full URL (`img="https://…"`) works too, as is.

The same image is the page's thumb in the [`Entries`](entries) listing.

## Without `img`

CodeSandbox no longer serves screenshots of sandboxes, so without `img` a placeholder stands in,
still linking to the sandbox:

```md
<Codesandbox id="3rjsl" title="Cell fracture" />
```

result:

<Codesandbox id="3rjsl" title="Cell fracture" />

> [!NOTE]
> `screenshot_url` is the former name of `img`. It still works, but is deprecated.

## Props

| Prop          | Type       | Description                                                             |
| ------------- | ---------- | ----------------------------------------------------------------------- |
| `id`          | `string`   | Sandbox id, e.g. `3rjsl` for `https://codesandbox.io/s/3rjsl`           |
| `title`       | `string`   | Caption under the preview                                               |
| `img`         | `string`   | Preview image: relative to the article, or a full URL                   |
| `description` | `string`   | Text under the title                                                    |
| `tags`        | `string[]` | Tags under the title, e.g. `tags={["physics", "rapier"]}`               |
| `embed`       | `boolean`  | Embeds the live sandbox in an `iframe` instead of linking to it         |
]]></page>
<page path="/authoring/gha" title="`Gha`"><![CDATA[URL: /authoring/gha
Description: GitHub-style alerts and callouts


<Intro>
  GitHub-style alerts with multiple severity levels.
</Intro>

Aka. ["GitHub alerts"](https://github.com/orgs/community/discussions/16925)

```md
<Gha keyword="NOTE">Highlights information that users should take into account, even when skimming.</Gha>
```

or better:

```md
> [!NOTE]
> Highlights information that users should take into account, even when skimming.
```

result:

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

---

We also support: `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`

result:

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

---

The `title` prop overrides the label derived from `keyword` (icon and background still follow the keyword). Only available via the JSX form:

```md
<Gha keyword="TIP" title="MCP-server">Browse these docs from your MCP-compatible client.</Gha>
```

result:

<Gha keyword="TIP" title="MCP-server">Browse these docs from your MCP-compatible client.</Gha>
]]></page>
<page path="/authoring/badge" title="`Badge`"><![CDATA[URL: /authoring/badge
Description: Small tags, like "storybook" or "suspense"


<Intro>
  Small tags, usually right under the page title.
</Intro>

```md
<Badge href="https://drei.pmnd.rs/?path=/story/abstractions-positionalaudio--positional-audio-scene-st">storybook</Badge>
<Badge href="https://r3f.docs.pmnd.rs/api/hooks#useloader">suspense</Badge>
<Badge>Dom only</Badge>
```

result:

<Badge href="https://drei.pmnd.rs/?path=/story/abstractions-positionalaudio--positional-audio-scene-st">storybook</Badge>
<Badge href="https://r3f.docs.pmnd.rs/api/hooks#useloader">suspense</Badge>
<Badge>Dom only</Badge>

A badge is inline, like a link: badges on consecutive lines make one row, and a badge sits in a sentence too, as in "works with <Badge>suspense</Badge>".

---

`color` takes a color role of the theme: `primary`, `secondary`, `tertiary`, `error`, or one of the custom colors `note`, `tip`, `important`, `warning`, `caution`; or a brand color, `storybook`, `npm`, `chromatic`, shown as is, with white text, in light and dark alike (see `THEME_*` in [configuration](/getting-started/introduction#configuration)):

```md
<Badge color="primary">primary</Badge>
<Badge color="secondary">secondary</Badge>
<Badge color="tertiary">tertiary</Badge>
<Badge color="error">error</Badge>
<Badge color="note">note</Badge>
<Badge color="tip">tip</Badge>
<Badge color="important">important</Badge>
<Badge color="warning">warning</Badge>
<Badge color="caution">caution</Badge>
<Badge color="storybook" logo="storybook">storybook</Badge>
<Badge color="npm" logo="npm">npm</Badge>
<Badge color="chromatic" logo="chromatic">chromatic</Badge>
<Badge color="tip" href="https://r3f.docs.pmnd.rs/api/hooks#useloader">suspense</Badge>
```

result:

<Badge color="primary">primary</Badge>
<Badge color="secondary">secondary</Badge>
<Badge color="tertiary">tertiary</Badge>
<Badge color="error">error</Badge>
<Badge color="note">note</Badge>
<Badge color="tip">tip</Badge>
<Badge color="important">important</Badge>
<Badge color="warning">warning</Badge>
<Badge color="caution">caution</Badge>
<Badge color="storybook" logo="storybook">storybook</Badge>
<Badge color="npm" logo="npm">npm</Badge>
<Badge color="chromatic" logo="chromatic">chromatic</Badge>
<Badge color="tip" href="https://r3f.docs.pmnd.rs/api/hooks#useloader">suspense</Badge>

---

`label` adds a de-emphasized label before the text, and `logo` a brand logo, by its [simple-icons](https://simpleicons.org) slug — for now `storybook`, `chromatic`, `discord`, `github` or `npm`; any other shows none:

```md
<Badge href="https://github.com/codespaces/new?template_repository=pmndrs%2Fdrei" label="GitHub" logo="github">Open in Codespaces</Badge>
```

result:

<Badge href="https://github.com/codespaces/new?template_repository=pmndrs%2Fdrei" label="GitHub" logo="github">Open in Codespaces</Badge>

---

A [shields.io](https://shields.io) image is an image like any other: it is not turned into a `Badge`. For a badge that follows the theme, write `<Badge>`.
]]></page>
<page path="/authoring/hint" title="`Hint` (Deprecated)"><![CDATA[URL: /authoring/hint
Description: Deprecated hint component


> [!CAUTION]
> Deprecated, use [`Gha[keyword="NOTE"]`](gha) instead.

```md
<Hint>
  I'm a deprecated hint. Use `Gha` instead.
</Hint>
```

result:

<Hint>I'm a deprecated hint. Use `Gha` instead.</Hint>
]]></page>
<page path="/authoring/contributors" title="`Contributors`"><![CDATA[URL: /authoring/contributors
Description: Display repository contributors


<Intro>
  Display GitHub repository contributors.
</Intro>

```md
<Contributors owner="pmndrs" repo="docs" />
```

> [!WARNING]
> [`CONTRIBUTORS_PAT`](introduction#configuration:~:text=CONTRIBUTORS_PAT) needs to be set. Otherwise, it will display John Doe.

result:

<Contributors owner="pmndrs" repo="docs" />
]]></page>
<page path="/authoring/backers" title="`Backers`"><![CDATA[URL: /authoring/backers
Description: Display project backers


<Intro>
  Display Open Collective backers.
</Intro>

```md
<Backers repo="react-three-fiber" />
```

result:

<Backers repo="react-three-fiber" />
]]></page>
<page path="/authoring/entries" title="`Entries`"><![CDATA[URL: /authoring/entries
Description: Display a grouped directory listing of documentation pages


<Intro>
  Displays all documentation entries in a multi-column layout, grouped by category.
</Intro>

The `Entries` component automatically generates a directory listing of all documentation pages in the site, organized by their top-level category (first segment of the slug).

```md
<Entries />
```

result:

<Entries />

> [!TIP]
> When a page includes a [`<Codesandbox>`](codesandbox) component, the Entries listing will automatically display its [`img`](codesandbox) as a thumb next to that page's link, or a CodeSandbox icon when it has none.]]></page>
<page path="/github-actions/introduction" title="Reusable GitHub Actions workflow"><![CDATA[URL: /github-actions/introduction
Description: Call from your CI


<Intro>
  This project provides a [`build.yml` reusable workflow](https://docs.github.com/en/actions/sharing-automations/reusing-workflows#calling-a-reusable-workflow) you can easily call from your own project workflow.
</Intro>

In your `.github/workflows` folder, create a eg. `docs.yml` file:

```yml
uses: pmndrs/docs/.github/workflows/build.yml@v3
  with:
    mdx: 'docs'
    libname: 'React Three Fiber'
    libname_short: 'r3f'
    home_redirect: '/getting-started/introduction'
    icon: '🇨🇭'
    logo: '/logo.png'
    github: 'https://github.com/pmndrs/react-three-fiber'
    discord: 'https://discord.com/channels/740090768164651008/740093168770613279'
    theme_primary: '#323e48'
    theme_scheme: 'tonalSpot'
    theme_contrast: '0'
    theme_note: '#1f6feb'
    theme_tip: '#238636'
    theme_important: '#8957e5'
    theme_warning: '#d29922'
    theme_caution: '#da3633'
```

See [`pmndrs/react-three-fiber/.github/workflows/docs.yml`](https://github.com/pmndrs/react-three-fiber/blob/master/.github/workflows/docs.yml) for an example implementation.

## Version switcher

Optional inputs for the [version switcher](/getting-started/introduction#version-switcher); `version_production_branch` defaults to the repository's default branch.

| input                       | env                         |
| --------------------------- | --------------------------- |
| `lib_version`               | `LIB_VERSION`               |
| `tag_match`                 | `TAG_MATCH`                 |
| `version_url_template`      | `VERSION_URL_TEMPLATE`      |
| `version_production_branch` | `VERSION_PRODUCTION_BRANCH` |
| `version_production_url`    | `VERSION_PRODUCTION_URL`    |
| `version_branches`          | `VERSION_BRANCHES`          |
| `version_branches_list`     | `VERSION_BRANCHES_LIST`     |

eg. for a monorepo package whose branches are deployed by Vercel's Git integration:

```yml
uses: pmndrs/docs/.github/workflows/build.yml@v4
  with:
    # ...
    tag_match: 'leva@*'
    version_url_template: 'https://leva-git-{branch:vercel}-pmndrs.vercel.app'
```
]]></page>
<page path="/agents/introduction" title="Agents"><![CDATA[URL: /agents/introduction
Description: llms.txt dumps, and the pmndrs MCP server


<Intro>
  Every site built with this generator also publishes machine-readable dumps of its content — and [docs.pmnd.rs](https://docs.pmnd.rs) serves them to agents over MCP.
</Intro>

## llms.txt

As alternate content, we provide you [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt).

These URLs are linked in the HTML header as:

```html
<link rel="alternate" type="text/plain" href="/llms.txt" />
<link rel="alternate" type="text/plain" href="/llms-full.txt" />
```

## MCP Server

`llms-full.txt` is a whole documentation site in one file — too big to paste into an agent for a one-line question. So [docs.pmnd.rs](https://docs.pmnd.rs) also exposes it as an [MCP](https://modelcontextprotocol.io) server, which lets an agent read a table of contents first, then fetch the one page it needs.

One endpoint for all libraries, over streamable HTTP: `https://docs.pmnd.rs/api/mcp`. It exposes:

| kind     | name                     | what it gives                                                      |
| -------- | ------------------------ | ------------------------------------------------------------------ |
| resource | `docs://pmndrs/manifest` | which libraries are served, and how to query them                  |
| resource | `docs://{lib}/index`     | that library's pages, one `{path} - {title}` per line              |
| tool     | `get_page_content`       | the markdown of a single page, given a `lib` + a `path` from the index |
| resource | `examples://index`       | the [example gallery](https://pmndrs.github.io/examples), one line per demo |
| tool     | `get_example`            | one demo in full, given a `name` from that index                   |

A typical round-trip — *"how do I use TypeScript with Zustand?"*:

```txt
read  docs://zustand/index
      → [...] /learn/guides/beginner-typescript - Beginner TypeScript Guide [...]

call  get_page_content(lib="zustand", path="/learn/guides/beginner-typescript")
      → the page, as markdown
```

Two pages transferred instead of the whole site.

### Examples

The docs say what an API takes. Most three.js questions are *how is this put together*, and the [gallery](https://pmndrs.github.io/examples) has 167 demos that answer it — so the same endpoint serves them, on the same read-the-index-then-fetch shape.

```txt
read  examples://index
      → [...] caustics · #transmission [...]
        diamond-refraction · Diamon refraction material · +postprocessing,leva · #refraction,bvh

call  get_example(name="caustics")
      → the demo: its source, its live URL, its asset attribution, and the exact
        dependency versions the code is written against
```

An index line drops whatever the demo does not carry, so it costs what it is worth. `+` lists only what a demo uses on top of `@react-three/fiber` and `@react-three/drei`, which all of them use. A trailing `~23k` is what `get_example` will cost in tokens — only eight demos carry one, and its absence means the demo is small enough to open without weighing it.

An example is a snapshot, not a spec: it pins its own versions, `get_example` reports them, and an answer that turns on a current signature still belongs in the docs above.

> [!NOTE]
>
> These documents are published, not rendered here — `pmndrs/examples` writes them at build time, at the page URL with an extension on the end:
>
> | | |
> | --- | --- |
> | `/examples/caustics` | the page |
> | `/examples/caustics.md` | the same example, as `get_example` returns it |
> | `/llms.txt` | the whole gallery, as `examples://index` returns it |
>
> Each page links its own, so it is found either by looking or by guessing:
>
> ```html
> <link rel="alternate" type="text/markdown" href="/examples/caustics.md" />
> ```
>
> The demos themselves — `/caustics`, which is what the READMEs' badges point at — carry the same links plus a `canonical` back to the page.
>
> There is no `llms-full.txt`: concatenated, the gallery is ~378k tokens, against ~50k for a documentation site. The index and one example is the whole point.

> [!TIP]
>
> [`pmndrs/claude-code-plugin`](https://github.com/pmndrs/claude-code-plugin) supports it natively
>
> ```sh
> /plugin marketplace add pmndrs/claude-code-plugin
> /plugin install pmndrs@pmndrs
> ```

For other clients, see the JSON config in the [MCP-server](https://docs.pmnd.rs) box on the home page. To poke at it by hand — see the resources, call the tool, read the raw JSON-RPC — run the official inspector:

```sh
$ HOST=127.0.0.1 npx -y @modelcontextprotocol/inspector
```

In the web UI it opens: **Add Servers** › **Add manually**, transport `streamable-http`, URL `https://docs.pmnd.rs/api/mcp` (or your own `http://localhost:3000/api/mcp`), and flip the server's toggle to connect.

![MCP Inspector connected to docs.pmnd.rs, previewing the react-three-fiber index resource](mcp-inspector.png)

### Getting your library served

Only libraries publishing a `/llms-full.txt` dump are served — the ones badged `MCP` on [docs.pmnd.rs](https://docs.pmnd.rs). The examples gallery is not one of them; it publishes its own catalog, and the two resources above are wired to it directly. To join the libraries:

1. **Publish the dump.** If your site is already built with this generator, bump it to a version shipping `/llms-full.txt` and redeploy. Otherwise, either migrate to this generator, or emit that file yourself with the same XML shape (`<page path="…" title="…">…</page>`).

   > [!TIP]
   >
   > With the [reusable workflow](/github-actions/introduction), pin the major tag — it always resolves to the latest `v3.x`:
   >
   > ```yml
   > uses: pmndrs/docs/.github/workflows/build.yml@v3
   > ```
   >
   > `/llms-full.txt` ships since [`v3.2.0`](https://github.com/pmndrs/docs/releases/tag/v3.2.0), in its MCP-ready shape since [`v3.4.1`](https://github.com/pmndrs/docs/releases/tag/v3.4.1).
2. **Check it.** `curl -sI <NEXT_PUBLIC_URL>/llms-full.txt` must return `200`, and the body must contain `<page …>` entries. A missing dump makes the library's index resource fail loudly, on purpose.
3. **Flip the flag.** Open a PR on [pmndrs/docs](https://github.com/pmndrs/docs) setting `llms_full: true` on your entry in `libs` ([`src/app/page.tsx`](https://github.com/pmndrs/docs/blob/main/src/app/page.tsx)). That single flag drives the `MCP` badge, the `docs://{lib}/index` resource and the `get_page_content` enum. It takes effect once [docs.pmnd.rs](https://docs.pmnd.rs) is redeployed — every push to `main` does that.

> [!NOTE]
>
> This is a one-off. Once served, **content** updates need no redeploy on either side: pages are fetched at request time and revalidated every 5 minutes.
]]></page>