Documentation Index
Fetch the complete documentation index at: https://mintlify.com/facebook/docusaurus/llms.txt
Use this file to discover all available pages before exploring further.
Docusaurus compiles Markdown to React using the MDX compiler, which means every .md and .mdx file in your site can embed React components, import modules, and use JSX expressions. This guide covers the most commonly used Markdown features you will encounter when writing documentation.
MDX and CommonMark
By default, Docusaurus uses the MDX format for all files. MDX extends CommonMark with JSX support, enabling you to embed interactive React components in your prose.
To use CommonMark automatically based on file extension, set this in your config:
export default {
markdown: {
format: 'detect', // .md → CommonMark, .mdx → MDX
},
};
The MDX playground at https://mdxjs.com/playground/ is an excellent debugging tool. Select the right format and enable the remark-gfm, remark-directive, and rehype-raw plugins to match Docusaurus’s behavior.
Admonitions
Docusaurus provides five built-in admonition types using triple-colon syntax. Leave blank lines around the content to avoid formatting issues with Prettier.
:::note
Supplementary information that is safe to skip.
:::
:::tip
A best practice or recommendation.
:::
:::info
Helpful context such as prerequisites or permissions.
:::
:::warning
An important caveat or potentially destructive action.
:::
:::danger
Critical warning about data loss or breaking changes.
:::
:::note[Your Custom Title **with** _Markdown_ `syntax`!]
Custom title admonition content.
:::
:::::info Parent
Parent content
::::danger Child
Child content
:::tip Deep Child
Deep child content
:::
::::
:::::
Code blocks with syntax highlighting
Docusaurus uses Prism React Renderer for syntax highlighting. Always include a language tag after the opening fence:
```js title="src/utils/greet.js"
function greet(name) {
return `Hello, ${name}!`;
}
```
Changing the highlight theme
import {themes as prismThemes} from 'prism-react-renderer';
export default {
themeConfig: {
prism: {
theme: prismThemes.dracula,
darkTheme: prismThemes.dracula,
},
},
};
Adding languages
Some languages (Java, C#, PHP) are not enabled by default. Add them via additionalLanguages:
export default {
themeConfig: {
prism: {
additionalLanguages: ['powershell', 'csharp', 'java'],
},
},
};
Line highlighting
Use magic comments inside the code to highlight specific lines:
function HighlightSomeText(highlight) {
if (highlight) {
// highlight-next-line
return 'This text is highlighted!';
}
return 'Nothing highlighted';
}
function HighlightMoreText(highlight) {
// highlight-start
if (highlight) {
return 'This range is highlighted!';
}
// highlight-end
return 'Nothing highlighted';
}
```jsx {1,4-6,11} to highlight lines 1, 4 through 6, and 11.
Line numbers
Add showLineNumbers to the language meta string:
```jsx showLineNumbers
import React from 'react';
export default function MyComponent() {
return <div>Hello</div>;
}
```
Tabs in content
Import and use the Tabs and TabItem components from the classic theme:
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="js" label="JavaScript" default>
```js
function helloWorld() {
console.log('Hello, world!');
}
```
</TabItem>
<TabItem value="py" label="Python">
```python
def hello_world():
print("Hello, world!")
```
</TabItem>
<TabItem value="java" label="Java">
```java
class HelloWorld {
public static void main(String args[]) {
System.out.println("Hello, World");
}
}
```
</TabItem>
</Tabs>
groupId prop:
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac" label="macOS">Use Command + C to copy.</TabItem>
</Tabs>
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">Use Ctrl + V to paste.</TabItem>
<TabItem value="mac" label="macOS">Use Command + V to paste.</TabItem>
</Tabs>
localStorage so it survives page navigation.
Table of contents
Headings at levels H2 and H3 are included in the right-side table of contents by default. Customize the range globally or per-document:
---
toc_min_heading_level: 2
toc_max_heading_level: 4
---
### Hello World {/* #my-stable-id */}
{/* #my-stable-id */} comment is stripped from the rendered output and becomes the heading’s id attribute.
Math equations with KaTeX
Install dependencies
npm install --save remark-math@6 rehype-katex@7
Configure plugins
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
remarkPlugins: [remarkMath],
rehypePlugins: [rehypeKatex],
},
},
],
],
stylesheets: [
{
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
type: 'text/css',
integrity:
'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
crossorigin: 'anonymous',
},
],
};
Write equations
Use $...$ for inline math and a fenced math code block for display mode:Let $f\colon[a,b]\to\R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be
$F(x)=\int_{a}^{x} f(t)\,dt$. Then $F$ is differentiable at $x$ with $F'(x)=f(x)$.
```math
I = \int_0^{2\pi} \sin(x)\,dx
```
Use remark-math@6 and rehype-katex@7 specifically for Docusaurus v3 (MDX v3). Other version combinations are not guaranteed to work.
Mermaid diagrams
Install the theme
npm install --save @docusaurus/theme-mermaid
Enable in config
export default {
markdown: {
mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],
};
Write diagrams
Use a fenced code block with the mermaid language tag:```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
export default {
themeConfig: {
mermaid: {
theme: {light: 'neutral', dark: 'forest'},
},
},
};
Front matter
Front matter is YAML metadata placed at the top of a Markdown file between triple-dash delimiters. Every content plugin defines its own supported fields:
---
title: My Document Title
description: A short description used for SEO meta tags.
keywords: [docusaurus, documentation, mdx]
sidebar_label: Short Label
sidebar_position: 3
tags: [guide, markdown]
---