Poimandres

Full documentation content.

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


<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

Nothing to install to use it: every command below runs through `npx`. What follows is for
working on the generator itself.

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]
>
> Every flag falls back to the variable next to it, and every default is `""` (think *empty*).

Those variables can be written down in a `.env`, in the folder the command runs from — a flag,
or a variable already in the environment, wins over the file:

```sh
# .env
MDX=docs
NEXT_PUBLIC_LIBNAME=React Three Fiber
ICON=🇨🇭
```

| flag                             | var                                   | description                                                                                                                                             | example                                                                                          |
| -------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `IN` argument\*                  | `MDX`                                 | Path to `*.mdx` folder<br/>NB: can be relative or absolute                                                                                              | `docs` or `~/code/myproject/documentation`                                                       |
| `--libname`\*                    | `NEXT_PUBLIC_LIBNAME`                 | Library name                                                                                                                                            | `React Three Fiber`                                                                              |
| `--libname-short`                | `NEXT_PUBLIC_LIBNAME_SHORT`           | Library short name                                                                                                                                      | `r3f`                                                                                            |
| `--libname-dotsuffix-label`      | `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL` | Text for the ".docs" suffix link inside the header                                                                                                      | `docs`                                                                                           |
| `--libname-dotsuffix-href`       | `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF`  | Href for the ".docs" suffix link inside the header                                                                                                      | `https://docs.pmnd.rs`                                                                           |
| `--base-path`                    | `BASE_PATH`                           | Base path for the final URL                                                                                                                             | `/react-three-fiber`                                                                             |
| `--home-redirect`                | `HOME_REDIRECT`                       | Where the home should redirect                                                                                                                          | `/getting-started/introduction`                                                                  |
| `--mdx-baseurl`                  | `MDX_BASEURL`                         | Base URL for inlining relative images                                                                                                                   | `https://github.com/pmndrs/react-three-fiber/raw/master/docs`                                    |
| `--sourcecode-baseurl`           | `SOURCECODE_BASEURL`                  | Base URL for `sourcecode:` code path                                                                                                                    | `https://github.com/pmndrs/react-three-fiber/tree/main`                                          |
| `--edit-baseurl`                 | `EDIT_BASEURL`                        | Base URL for displaying "Edit this page" URLs                                                                                                           | `https://github.com/pmndrs/react-three-fiber/edit/master/docs`                                   |
| `--url`                          | `NEXT_PUBLIC_URL`                     | Final URL of the published website                                                                                                                      | `https://pmndrs.github.io/react-three-fiber`                                                     |
| `--icon`                         | `ICON`                                | Emoji or image to use as (fav)icon (path local to `MDX`)                                                                                                | `🇨🇭` or `/icon.png` or `/favicon.ico`                                                            |
| `--logo`                         | `LOGO`                                | Logo src/path (either FQURL or local to `MDX` path)                                                                                                     | `/logo.png` or `https://worldvectorlogo.com/r3f.png`                                             |
| `--github`                       | `GITHUB`                              | Github URL                                                                                                                                              | `https://github.com/pmndrs/react-three-fiber`                                                    |
| `--discord`                      | `DISCORD`                             | Discord URL                                                                                                                                             | `https://discord.com/channels/740090768164651008/740093168770613279`                             |
| `--theme-primary`                | `THEME_PRIMARY`                       | Primary accent color                                                                                                                                    | `#323e48`                                                                                        |
| `--theme-scheme`                 | `THEME_SCHEME`                        | Theme scheme                                                                                                                                            | `content` or `expressive` or `fidelity` or `monochrome` or `neutral` or `tonalSpot` or `vibrant` |
| `--theme-contrast`               | `THEME_CONTRAST`                      | Theme contrast -- value between -1 and 1                                                                                                                | `0` or `-1` or `1` or `-.6`                                                                      |
| `--theme-note`                   | `THEME_NOTE`                          | "note" color                                                                                                                                            | `#1f6feb`                                                                                        |
| `--theme-tip`                    | `THEME_TIP`                           | "tip" color                                                                                                                                             | `#238636`                                                                                        |
| `--theme-important`              | `THEME_IMPORTANT`                     | "important" color                                                                                                                                       | `#8957e5`                                                                                        |
| `--theme-warning`                | `THEME_WARNING`                       | "warning" color                                                                                                                                         | `#d29922`                                                                                        |
| `--theme-caution`                | `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

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

[![color scheme](color-scheme.png)](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).

</details>

## Usage

### dev

```sh
$ npx -y @pmndrs/docs@latest dev docs \
  --libname "React Three Fiber" \
  --libname-short "r3f" \
  --home-redirect /getting-started/introduction \
  --icon 🇨🇭 \
  --github https://github.com/pmndrs/react-three-fiber
```

Then go to: http://localhost:3000

Pages are read on every request — edit one, reload. The `MDX` folder is served alongside, so
relative images resolve as you write them, and `--port` moves the server.

> [!TIP]
> If `--home-redirect` is left empty, `/` will not redirect, and instead displays an index of libraries.

With the options in a [`.env`](#Configuration), there is nothing left to pass:

```sh
$ npx -y @pmndrs/docs@latest dev
```

### build

```sh
$ npx -y @pmndrs/docs@latest build docs out --format website \
  --libname "React Three Fiber" \
  --icon 🇨🇭
$ npx -y serve out
```

`--format website` statically exports the whole site into `out` — what
[`build.yml`](./github-actions.mdx) publishes to GitHub Pages. `--format fragment` (the default)
compiles one `.html` per `.mdx` instead: the compiled MDX and nothing else, no layout, no
stylesheet, no script.

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

```tsx
<Sandpack
  template="react-ts"
  customSetup={{
    dependencies: {
      'three': 'latest',
      '@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': 'latest',
      '@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>

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

result:

<Codesandbox id="3rjsl" title="Cell fracture" />]]></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/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>` component, the Entries listing will automatically display its thumb next to that page's link.]]></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'
    libname_dotsuffix_label: "docs"
    libname_dotsuffix_href: "https://docs.pmnd.rs"
    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.
]]></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>