MDX and Components
MDX is a superset of Markdown that understands JSX. A file written in MDX is compiled into a React component, so anything you can render in React you can also write inside a documentation page: a live chart, a pricing matrix, a callout, a tab switcher, a button that opens a modal. The current 3.x line of Docusaurus parses content with MDX 3, which is strict about a few details that ordinary Markdown never had to care about. Those details are the reason a page that looks like plain prose can fail to build, so they are worth learning early rather than debugging under pressure.
Using a component in a document takes two steps. Import it at the top of the file, then use it in the body:
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Chart from '@site/src/components/Chart';
# Installing the CLI
<Tabs groupId="install">
<TabItem value="npm" label="npm">
```bash
npm install -g acme-cli
```
</TabItem>
<TabItem value="pnpm" label="pnpm">
```bash
pnpm add -g acme-cli
```
</TabItem>
</Tabs>
<Chart data={latencyByRegion} />
The @theme prefix resolves to the theme’s own components, and @site resolves to the root of your project, so src/components/Chart becomes @site/src/components/Chart. Imports are resolved at build time, so a missing file is a build error rather than a blank spot on the page. Docusaurus also ships a set of components that are useful in almost any documentation set: Tabs and TabItem for alternatives, CodeBlock for rendering a snippet with the same chrome as a fenced block, and BrowserWindow for a framed screenshot placeholder.
If a component appears in many documents, mapping it once is better than importing it everywhere. The theme exposes an MDXComponents file, and swizzling it creates a local copy that you can edit:
// src/theme/MDXComponents.js
import MDXComponents from '@theme-original/MDXComponents';
import Chart from '@site/src/components/Chart';
import Callout from '@site/src/components/Callout';
export default {
...MDXComponents,
Chart,
Callout,
};
After that, every MDX file in the site can use Chart and Callout without an import. The spread of the original mapping matters: it keeps the built-in components such as Admonition and the table of contents working. This file is also the place to override a built-in component wholesale, which is how you would change how links or code blocks render across the whole documentation set.
Docusaurus adds a small number of Markdown extensions on top of MDX. Admonitions are the most commonly used, and they are written as a fenced block whose opening line names the type:
:::tip
Admonitions are fenced blocks. The type controls the colour and the icon.
:::
:::warning[Read this before upgrading]
Custom titles go in square brackets right after the type.
:::
Other built-in Markdown extensions include content tabs, which are just the Tabs components written in MDX, and heading anchors, which are generated automatically so you can link to any section. Code fences carry extra metadata as well: a title suffix after the language names the file, and a brace suffix highlights specific lines.
```js title="src/hooks/useAuth.js" {4,7-9}
export function useAuth() {
const user = useContext(AuthContext);
if (!user) {
throw new Error('useAuth must be used inside AuthProvider');
}
return user;
}
```
Languages that Prism does not know by default are registered in the theme configuration rather than in the document:
// docusaurus.config.js
module.exports = {
themeConfig: {
prism: {
additionalLanguages: ['bash', 'diff', 'rust'],
},
},
};
Escaping is the other MDX detail that surprises people. A curly brace in prose is not text, it opens a JavaScript expression, so a sentence like “pass an object like { id }” must escape the braces. The same is true of a bare angle bracket, which would otherwise be read as the start of a tag. Inside a fenced code block no escaping is needed, because the fence is not parsed as JSX.
Pass an object like \{ id \} to the function.
Use the less-than sign < to compare values.
A few other things are worth knowing. MDX files placed in src/pages/ become standalone pages, and there you control the whole document including its layout:
import Layout from '@theme/Layout';
<Layout title="Changelog" description="Every release we have shipped.">
<ChangelogFeed />
</Layout>
Pages that must touch the browser directly, such as a component that reads window, need the BrowserOnly wrapper from @docusaurus/BrowserOnly, because the server render has no window to offer. And for anything that has to react to the light and dark theme, useColorMode from @docusaurus/theme-common returns the current mode and a setter.
The practical takeaway is that MDX removes the ceiling that separates “documentation” from “product surface”, but it also removes the guarantee that a document is inert text. A page can now break the build, depend on a component that someone has to maintain, or render differently depending on the browser. The habit worth keeping is to keep the majority of pages plain Markdown, reach for a component only when it earns its place, and keep shared components in the theme file so there is exactly one place to fix when a dependency changes.
