Authoring

How to write documentation

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

---
title: My Document
description: Lorem ipsum...
nav: 0
image: dog.png
---

MARKDOWN

Frontmatter

Any key is optional.

  • title: if not provided, last part of the path is used: my document
  • 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

All exported components/mdx/index.tsx React components will have MDX treatment.

Img

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

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

<img src="gutenberg.jpg" />
Result
Important

To avoid layout-shifts, always provides [width]/[height] img's attributes:

<img src='gutenberg.jpg' width="1100" height="685" />
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
  • A
  • B
  • C
  • D
  • E
  • F
  • G

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

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

Codesandbox

<Codesandbox id="3rjsl" />
ResultCell 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.

Footnotes

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