📄 Extendable Features

Docusaurus supports standard Markdown along with several enhanced features. While all native Markdown syntax is compatible, Docusaurus provides unique extensions to improve your documentation's functionality. It introduces powerful custom additions—such as Admonitions, MDX components, and Tabs—to help you build more interactive and expressive documentation.

Below are several extensible features to enhance your documentation. While this list covers the most common enhancements, you can explore the Docusaurus documentation for a full suite of advanced customization options.

Front Matter

Markdown documents use frontMatter metadata :

my-doc.md or my-doc.mdx

---
id: my-doc-id
title: My document title
description: My document description
slug: /my-url-path
sidebar_position: 2
---

# {frontMatter.title}

Markdown content usually starts here.

Headings

Markdown headings are supported using the standard “#” syntax and are automatically added to the table of contents. The number of # corresponds to the heading level.

Docusaurus automatically generates anchors based on a heading's label. Hover over the above Heading to see the anchor.

## Headings

My text

Heading Ids

While Docusaurus automatically generates anchors based on a heading's label, relying on these defaults can be risky. If the heading text changes, the anchor changes with it, breaking any existing links. Using custom Heading IDs creates a permanent anchor that remains stable even if you rename the section.

Add {/* #my-custom-id */} after the heading text to assign it an explicit anchor id, used for linking. Note the use of <prettier-ignore/> as prettier will change the syntax of the anchor and cause a build issue.

<prettier-ignore/>
### Heading Ids {/* #my-custom-id */}

Links

Regular Markdown Links are supported, using url paths or relative file paths.

Let's see how to [Create a page](/create-a-page).

Let's see how to [Create a page](./create-a-page.mdx).

Sometimes it is tempting to use an <a> element and in this case consider using the Docusaurus <Link> element if your document is of type .mdx.

<Link>

While Docusaurus supports standard Markdown links, the specialized <Link> component for MDX is the superior choice for performance. It enhances the user experience through automatic preloading and protects your site with built-in broken link detection. Built as a wrapper around react-router, the component intelligently manages both internal and external paths. When working in .mdx files, prefer <Link> over the standard <a> tag to leverage these native optimizations.

<Link>

import Link from '@docusaurus/Link';

// Internal link
<Link to="/blog">Blog</Link>

// External link (automatically opens in new tab)
<Link to="https://x.com/docusaurus">X</Link>

See Docusaurus on X

Images

Regular Markdown images are supported.

You can use absolute paths to reference images in the static directory:

![Docusaurus logo](static/img/docusaurus.png)

You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:

![Docusaurus logo](./img/docusaurus.png)

Code Blocks

Markdown code blocks are supported with Syntax highlighting and titles.

Example code block

```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
  return <h1>Hello, Docusaurus!</h1>;
}
```

Yields:

src/components/HelloDocusaurus.js

function HelloDocusaurus() {
  return <h1>Hello, Docusaurus!</h1>;
}

Admonitions

Docusaurus has a special syntax to create Admonitions and callouts:

<prettier-ignore/>
:::tip[My tip]
Use this awesome feature option
:::

My tip

Use this awesome feature option

Note the use of <prettier-ignore/> as prettier will change the syntax of the admonitions and cause a build issue.

MDX and React Components

MDX can make your documentation more interactive and allows using any React components inside Markdown:

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '20px',
      color: '#fff',
      padding: '10px',
      cursor: 'pointer',
    }}
    onClick={() => {
      alert(`You clicked the color ${color} with label ${children}`)
    }}>
    {children}
  </span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !

This is Docusaurus green !

This is Facebook blue !

Tabs

Docusaurus provides the Tabs component that you can use in Markdown thanks to MDX:

Apple

This is an apple 🍎

Orange

This is an orange 🍊

Banana

This is a banana 🍌

---

Owner: Warren