Authoring
How to write documentation
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 fileimage
:- relative (to the md file) or absolute path, eg:
dog.png
,./dog.png
,../../dog.png
,/dog.png
orhttps://animals.com/dog.png
- will be used as metadata image if provided
- relative (to the md file) or absolute path, eg:
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
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
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
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.
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>
)
}`,
}}
/>
Codesandbox
<Codesandbox id="3rjsl" />
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
Highlights information that users should take into account, even when skimming.
We also support: [!TIP]
, [!IMPORTANT]
, [!WARNING]
, [!CAUTION]
Optional information to help a user be more successful.
Crucial information necessary for users to succeed.
Critical content demanding immediate user attention due to potential risks.
Negative potential consequences of an action.
Hint
Deprecated, use Gha[keyword="NOTE"]
instead.
<Hint>
I'm a deprecated hint. Use `Gha` instead.
</Hint>
Result
Gha
instead.Contributors
<Contributors owner="pmndrs" repo="docs" />
CONTRIBUTORS_PAT
needs to be set. Otherwise, it will display John Doe.
Backers
<Backers repo="react-three-fiber" />