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`. Working on the generator
itself is the one case that needs a checkout:

```sh
$ git clone https://github.com/pmndrs/docs.git
$ cd docs
$ nvm use && pnpm install
```

## Configuration

Every option is a flag, the environment variable it falls back to, or a line of a `.env` read
from the folder the command runs in — a flag beats the environment, which beats the file, and
everything defaults to empty. `pmndrs-docs dev --help` prints these same rows, which is where
they are declared:

<WebsiteOptions />

`MDX` is the folder itself, the `IN` argument of every command. `CONTRIBUTORS_PAT` has no flag:
it is a [GitHub token](https://docs.github.com/en/rest/collaborators/collaborators) for the
contributors API, and belongs in CI rather than in a file.

```sh
# .env
MDX=docs                                    # the folder of *.mdx, relative or absolute
NEXT_PUBLIC_LIBNAME=React Three Fiber       # the name in the header
NEXT_PUBLIC_LIBNAME_SHORT=r3f
BASE_PATH=/react-three-fiber
HOME_REDIRECT=/getting-started/introduction
MDX_BASEURL=https://github.com/pmndrs/react-three-fiber/raw/master/docs
SOURCECODE_BASEURL=https://github.com/pmndrs/react-three-fiber/tree/main
EDIT_BASEURL=https://github.com/pmndrs/react-three-fiber/edit/master/docs
ICON=🇨🇭
LOGO=/logo.png
GITHUB=https://github.com/pmndrs/react-three-fiber
THEME_PRIMARY="#323e48"                     # quoted, or `#` starts a comment
THEME_SCHEME=tonalSpot
```

`MDX` and `NEXT_PUBLIC_LIBNAME` are the two required ones.

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

Relative images are resolved against it, so `![](dog.png)` in `advanced/introduction.mdx`
becomes `![](https://…/advanced/dog.png)`. `build.yml` points it at the raw files of the branch
being built; `dev` points it at the MDX folder it serves itself.

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

Both formats use the same Next.js build and static export. `--format website` exports the
whole site into `out` — what [`build.yml`](./github-actions.mdx) publishes to GitHub Pages.
`--format fragment` (the default) extracts one `.html` per `.mdx` from that export: the
compiled MDX and nothing else, no layout, no stylesheet, no script. Assets are copied
alongside the fragments. Mermaid diagrams stay fenced blocks, and Sandpack shows its code
without the editor.

You can also pass a single file or pipe MDX to stdin:

```sh
$ npx -y @pmndrs/docs@latest build page.mdx
$ cat page.mdx | npx -y @pmndrs/docs@latest build
```

Both write only the HTML fragment to stdout, with build logs on stderr. Every invocation
runs `next build`, even for a single file or stdin.

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