Authoring

How to write documentation

Summary

This is a guide on how to write documentation. We support all GFM syntax, plus some custom components that are described here.

Keypoints

Front matter metadatas
Custom markdown components

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

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

You can use any GitHub Flavored Markdown syntax.

Plus, all exported components/mdx/index.tsx MDX components.

`Intro`

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

<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

Summary

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.

`Keypoints`

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

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

Result

What you'll learn

First item
Second item

`Img`

Relative images are supported. Eg, inside your MDX folder:

|-- getting-started
|   |-- authoring.mdx  <= relative to this article
|   `-- gutenberg.jpg

---
title: Authoring
---

![](gutenberg.jpg)

Result

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 instrisic ratio), eg:

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

Result

Although it is probably better to use CSS for this:

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

Result

Note

See MDX_BASEURL to understand how it is converted to a full URL.

Code

Line numbers/highlights are supported:

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

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

Result

type Props = {who: string}

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

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

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

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

Result

type Props = {who: string}

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

diff format is supported:

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

`Grid`

Responsive grid.

<Grid cols={2}>
  <li>A</li>
  <li>B</li>
  <li>C</li>
  ...
</Grid>

Result

`Sandpack`

Inline sandboxes.

Note

See Sandpack official documentation for full usage.

<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

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

Open Sandbox

Tip

Sandpack UI SSR-rendering¹ is also supported (out of the box).

`Sandpack[folder]`

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

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

folder path is relative to the .mdx file:

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

import { CameraControls, Cloud } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'

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

Open Sandbox

It is also possible to pass some individual file format configuration:

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

Result

import { CameraControls, Cloud } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'

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

Open Sandbox

`Sandpack[fileExplorer]`

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

Result

import { CameraControls, Cloud } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'

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

Open Sandbox

Tip

Conveniently, enabling fileExplorer will by default [codeEditor={showTabs: false}]. You can override it with [codeEditor] options

You can also pass any fileExplorer={options: ComponentProps<SandpackFileExplorer>}.

`Sandpack[codeEditor]`

You can pass any codeEditor={options: ComponentProps<SandpackCodeEditor>}.

`Sandpack[codeViewer]`

It will render the SandpackCodeViewer instead of the default SandpackCodeEditor.

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

Result

import { CameraControls, Cloud } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'

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

Open Sandbox

You can also pass any codeViewer={options: ComponentProps<SandpackCodeViewer>}.

`Sandpack[codeViewer][filesDecorators]`

You can define per-file decorators through filesDecorators prop:

<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

import { CameraControls, Cloud } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'

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

Open Sandbox

`Sandpack[preview]`

You can pass any preview={options: ComponentProps<SandpackPreview>}.

`Codesandbox`

<Codesandbox id="3rjsl" />

Result

$Cell fracture$

Cell fracture

`Gha`

Aka. "GitHub alerts"

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

or better:

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

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`

Caution

Deprecated, use Gha[keyword="NOTE"] instead.

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

Result

Note

I'm a deprecated hint. Use Gha instead.

`Contributors`

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

Warning

CONTRIBUTORS_PAT needs to be set. Otherwise, it will display John Doe.

Result

Backers

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

Result

https://sandpack.codesandbox.io/docs/guides/ssr#nextjs-app-dir ↩

docs/getting-started/authoring.mdx

Edit this page

Summary

Keypoints

Frontmatter

MARKDOWN

Intro

Summary

Keypoints

What you'll learn

Img

Code

Grid

Sandpack

Sandpack[folder]

Sandpack[fileExplorer]

Sandpack[codeEditor]

Sandpack[codeViewer]

Sandpack[codeViewer][filesDecorators]

Sandpack[preview]

Codesandbox

Cell fracture

Gha

Hint

Contributors

Backers

Footnotes

`Intro`

`Keypoints`

`Img`

`Grid`

`Sandpack`

`Sandpack[folder]`

`Sandpack[fileExplorer]`

`Sandpack[codeEditor]`

`Sandpack[codeViewer]`

`Sandpack[codeViewer][filesDecorators]`

`Sandpack[preview]`

`Codesandbox`

`Gha`

`Hint`

`Contributors`