Poimandres

Full documentation content.

---

pmndrs/docs
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

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`                                                                                            |
| `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL` | Text for the ".docs" suffix link inside the header                                                                                                                       | `docs`                                                                                           |
| `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF`  | Href for the ".docs" suffix link inside the header                                                                                                                       | `https://docs.pmnd.rs`                                                                          |
| `BASE_PATH`                           | Base path for the final URL                                                                                                                                              | `/react-three-fiber`                                                                             |
| `DIST_DIR`                            | Path to the output folder ([within project](https://nextjs.org/docs/app/api-reference/next-config-js/distDir#:~:text=should%20not%20leave%20your%20project%20directory)) | `out` or `docs/out/react-three-fiber`                                                            |
| `OUTPUT`                              | Set to `export` for static output                                                                                                                                        | `export`                                                                                         |
| `HOME_REDIRECT`                       | Where the home should redirect                                                                                                                                           | `/getting-started/introduction`                                                                  |
| `MDX_BASEURL`                         | Base URL for inlining relative images                                                                                                                                    | `http://localhost:60141`or `https://github.com/pmndrs/react-three-fiber/raw/master/docs`         |
| `SOURCECODE_BASEURL`                  | Base URL for `sourcecode:` code path                                                                                                                                     | `https://github.com/pmndrs/react-three-fiber/tree/main`                                          |
| `EDIT_BASEURL`                        | Base URL for displaying "Edit this page" URLs                                                                                                                            | `https://github.com/pmndrs/react-three-fiber/edit/master/docs`                                   |
| `NEXT_PUBLIC_URL`                     | Final URL of the published website                                                                                                                                       | `https://pmndrs.github.io/react-three-fiber`                                                     |
| `ICON`                                | Emoji or image to use as (fav)icon (path local to `MDX`)                                                                                                                 | `🇨🇭` or `/icon.png` or `/favicon.ico`                                                            |
| `LOGO`                                | Logo src/path (either FQURL or local to `MDX` path)                                                                                                                      | `/logo.png` or `https://worldvectorlogo.com/r3f.png`                                             |
| `GITHUB`                              | Github URL                                                                                                                                                               | `https://github.com/pmndrs/react-three-fiber`                                                    |
| `DISCORD`                             | Discord URL                                                                                                                                                              | `https://discord.com/channels/740090768164651008/740093168770613279`                             |
| `THEME_PRIMARY`                       | Primary accent color                                                                                                                                                     | `#323e48`                                                                                        |
| `THEME_SCHEME`                        | Theme scheme                                                                                                                                                             | `content` or `expressive` or `fidelity` or `monochrome` or `neutral` or `tonalSpot` or `vibrant` |
| `THEME_CONTRAST`                      | Theme contrast -- value between -1 and 1                                                                                                                                 | `0` or `-1` or `1` or `-.6`                                                                      |
| `THEME_NOTE`                          | "note" color                                                                                                                                                             | `#1f6feb`                                                                                        |
| `THEME_TIP`                           | "tip" color                                                                                                                                                              | `#238636`                                                                                        |
| `THEME_IMPORTANT`                     | "important" color                                                                                                                                                        | `#8957e5`                                                                                        |
| `THEME_WARNING`                       | "warning" color                                                                                                                                                          | `#d29922`                                                                                        |
| `THEME_CAUTION`                       | "caution" color                                                                                                                                                          | `#da3633`                                                                                        |
| `CONTRIBUTORS_PAT`                    | GitHub token for contributors API (see: https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators)                 | `ghp_1234567890`                                                                                 |

\* Required

<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 [react-mcu](https://github.com/abernier/react-mcu).

[![color scheme](color-scheme.png)](https://github.com/abernier/react-mcu)

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

## dev

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

  export _PORT=60141

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="Poimandres"
  export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs"
  export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs"
  export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs"
  export BASE_PATH=
  export DIST_DIR=
  export OUTPUT=export
  export HOME_REDIRECT=
  export MDX_BASEURL=http://localhost:$_PORT
  export SOURCECODE_BASEURL="vscode://file$(pwd)"
  export EDIT_BASEURL="vscode://file$(pwd)/docs"
  export NEXT_PUBLIC_URL=
  export ICON=
  export LOGO=gutenberg.jpg
  export GITHUB=https://github.com/pmndrs/docs
  export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
  export THEME_PRIMARY="#323e48"
  export THEME_SCHEME="tonalSpot"
  export THEME_CONTRAST="0"
  export THEME_NOTE="#1f6feb"
  export THEME_TIP="#238636"
  export THEME_IMPORTANT="#8957e5"
  export THEME_WARNING="#d29922"
  export THEME_CAUTION="#da3633"
  export CONTRIBUTORS_PAT=

  kill $(lsof -ti:"$_PORT")
  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  pnpm run dev &

  wait
)
```

Then go to: http://localhost:3000

> [!TIP]
> If `HOME_REDIRECT=` empty, `/` will not redirect, and instead displays an index of libraries.

## build

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

  rm -rf out

  export _PORT=60141

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="Poimandres"
  export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs"
  export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs"
  export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs"
  export BASE_PATH=
  export DIST_DIR=
  export OUTPUT=export
  export HOME_REDIRECT=/getting-started/introduction
  export MDX_BASEURL=http://localhost:$_PORT
  export SOURCECODE_BASEURL=
  export EDIT_BASEURL=
  export NEXT_PUBLIC_URL=
  export ICON=
  export LOGO=gutenberg.jpg
  export GITHUB=https://github.com/pmndrs/docs
  export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
  export THEME_PRIMARY="#323e48"
  export THEME_SCHEME="tonalSpot"
  export THEME_CONTRAST="0"
  export THEME_NOTE="#1f6feb"
  export THEME_TIP="#238636"
  export THEME_IMPORTANT="#8957e5"
  export THEME_WARNING="#d29922"
  export THEME_CAUTION="#da3633"
  export CONTRIBUTORS_PAT=

  pnpm run build

  kill $(lsof -ti:"$_PORT")
  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  npx serve out &

  wait
)
```

http://localhost:3000

## Docker

```sh
$ docker build -t pmndrs-docs .
```

```sh
$ cd ~/code/pmndrs/react-three-fiber
$ (
  trap 'kill -9 0' SIGINT

  export _PORT=60141

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="React Three Fiber"
  export NEXT_PUBLIC_LIBNAME_SHORT="r3f"
  export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs"
  export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs"
  export BASE_PATH=
  export OUTPUT=export
  export HOME_REDIRECT=/getting-started/introduction
  export MDX_BASEURL=http://localhost:$_PORT
  export SOURCECODE_BASEURL=
  export EDIT_BASEURL=
  export NEXT_PUBLIC_URL=
  export ICON=🇨🇭
  export LOGO=/logo.png
  export GITHUB=https://github.com/pmndrs/react-three-fiber
  export DISCORD=https://discord.com/channels/740090768164651008/740093168770613279
  export THEME_PRIMARY="#323e48"
  export THEME_SCHEME="tonalSpot"
  export THEME_CONTRAST="0"
  export THEME_NOTE="#1f6feb"
  export THEME_TIP="#238636"
  export THEME_IMPORTANT="#8957e5"
  export THEME_WARNING="#d29922"
  export THEME_CAUTION="#da3633"
  export CONTRIBUTORS_PAT=

  rm -rf "$MDX/out"

  docker run --rm --init -it \
    -v "./$MDX":/app/docs \
    -e MDX \
    -e NEXT_PUBLIC_LIBNAME \
    -e NEXT_PUBLIC_LIBNAME_SHORT \
    -e NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL \
    -e NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF \
    -e BASE_PATH \
    -e DIST_DIR="$MDX/out$BASE_PATH" \
    -e OUTPUT \
    -e HOME_REDIRECT \
    -e MDX_BASEURL \
    -e SOURCECODE_BASEURL \
    -e EDIT_BASEURL \
    -e NEXT_PUBLIC_URL \
    -e ICON \
    -e LOGO \
    -e GITHUB \
    -e DISCORD \
    -e THEME_PRIMARY \
    -e THEME_SCHEME \
    -e THEME_CONTRAST \
    -e THEME_NOTE \
    -e THEME_TIP \
    -e THEME_IMPORTANT \
    -e THEME_WARNING \
    -e THEME_CAUTION \
    -e CONTRIBUTORS_PAT \
    pmndrs-docs pnpm run build

  kill $(lsof -ti:"$_PORT")
  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  npx -y serve "$MDX/out" &

  wait
)
```

Then go to: http://localhost:3000

---

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

## 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 [react-mcu](https://github.com/abernier/react-mcu) 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.

---

Intro
URL: /authoring/intro
Description: Introduction component for documentation pages

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

---

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

---

Img
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`](introduction#configuration:~:text=MDX_BASEURL) to understand how it is converted to a full URL.

---

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

---

Mermaid
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}$$")
```

---

Grid
URL: /authoring/grid
Description: Responsive grid layout component

<Intro>
  Responsive grid layout.
</Intro>

```md
<Grid cols={2}>
  <li>A</li>
  <li>B</li>
  <li>C</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>

---

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

---

Codesandbox
URL: /authoring/codesandbox
Description: Embed Codesandbox examples

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

```md
<Codesandbox id="3rjsl" />
```

result:

<Codesandbox id="3rjsl" />

---

or `[embed]`

```md
<Codesandbox id="3rjsl" embed />
```

result:

<Codesandbox id="3rjsl" embed />

---

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

---

Hint (Deprecated)
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>

---

Contributors
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" />

---

Backers
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" />

---

Reusable GitHub Actions workflow
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@v2
  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'
    docker_tag: '2.20.1'
```

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.