Markdown

How to write documents

Introduction

Fumadocs provides many useful extensions to MDX, a markup language. Here is a brief introduction to the default MDX syntax of Fumadocs UI.

MDX is not the only supported format of Fumadocs. In fact, you can use any renderers such as next-mdx-remote or CMS.

Markdown

We use GFM (GitHub Flavored Markdown), a superset of Markdown (CommonMark). See GFM Specification.

# Heading
 
## Heading
 
### Heading
 
#### Heading
 
Hello World, **Bold**, _Italic_, ~~Hidden~~
 
```js
console.log('Hello World');
```
 
1. First
2. Second
3. Third
 
- Item 1
- Item 2
 
> Quote here
 
![alt](/image.png)
 
| Table | Description |
| ----- | ----------- |
| Hello | World       |

Internal links use the next/link component to allow prefetching and avoid hard-reload.

External links will get the default rel="noreferrer noopener" target="_blank" attributes for security.

[My Link](https://github.github.com/gfm)
 
This also works: https://github.github.com/gfm.

MDX

MDX is a superset of Markdown, with support of JSX syntax. It allows you to import components, and use them right in the document, or even export values.

import { Component } from './component';
 
<Component name="Hello" />

see MDX Syntax to learn more.

Cards

Useful for adding links, it is included by default.

<Cards>
  <Card
    href="https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating"
    title="Fetching, Caching, and Revalidating"
  >
    Learn more about caching in Next.js
  </Card>
</Cards>

Icon

You can specify an icon to cards.

import { HomeIcon } from 'lucide-react';
 
<Cards>
  <Card icon={<HomeIcon />} href="/" title="Home">
    Go back to home
  </Card>
</Cards>

Without href

<Cards>
  <Card title="Fetching, Caching, and Revalidating">
    Learn more about `fetch` in Next.js.
  </Card>
</Cards>

Fetching, Caching, and Revalidating

Learn more about fetch in Next.js.

Callouts

Useful for adding tips/warnings, it is included by default.

<Callout>Hello World</Callout>
Hello World

Title

Specify a callout title.

<Callout title="Title">Hello World</Callout>

Title

Hello World

Types

You can specify the type of callout.

  • info (default)
  • warn
  • error
<Callout title="Title" type="error">
  Hello World
</Callout>

Title

Hello World

Customisation

See all MDX components and available options.

Heading Anchors

An anchor is automatically applied to all headings, it sanitizes invalid characters like spaces. (e.g. Hello World to hello-world)

Custom Anchor

You can add [#slug] to customise heading anchors.

# heading [#my-heading-id]

To link people to a specific heading, add the heading id to hash fragment: /page#my-heading-id.

Frontmatter

We support YAML frontmatter. It is a way to specify common information of the document (e.g. title). Place it at the top of document.

---
title: Hello World
---
 
## Title

See Page Conventions for a list of properties available for frontmatter.

Codeblock

Syntax Highlighting is supported by default using Rehype Code.

```js
console.log('Hello World');
```

You can add a title to the codeblock.

```js title="My Title"
console.log('Hello World');
```

Highlight Lines

You can highlight specific lines by adding [!code highlight].

```tsx
<div>Hello World</div>  // [!code highlight]
<div>Hello World</div>
<div>Goodbye</div>
<div>Hello World</div>
```

Highlight Words

You can highlight a specific word by adding [!code word:<match>].

```js
// [!code word:config]
const config = {
  reactStrictMode: true,
};
```

Diffs

```ts
console.log('hewwo'); // [!code --]
console.log('hello'); // [!code ++]
```
console.log('hewwo');
console.log('hello');

As Tab

You can use code block as a <Tab /> component.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 
<Tabs items={["Tab 1", "Tab 2"]}>
 
```ts tab="Tab 1"
console.log('A');
```
 
```ts tab="Tab 2"
console.log('B');
```
 
</Tabs>
console.log('A');

Using Typescript Twoslash

Write Typescript codeblocks with hover type information and detected types errors.

Not enabled by default. See Twoslash.

Images

All built-in content sources handle images properly. Images are automatically optimized for next/image.

![Image](/image.png)

Optional

Some optional plugins you can enable.

Math Equations

Write math equations with TeX.

```math
f(x) = x * e^{2 pi i \xi x}
```
f(x)=xe2piiξxf(x) = x * e^{2 pi i \xi x}

To enable, see Math Integration.

Package Install

Generate code blocks for installing packages via package managers (JS/Node.js).

```package-install
npm i next -D
```
npm i next -D

To enable, see Remark Install.

More

You can see a list of plugins supported by Fumadocs.

Edit on GitHub

Last updated on

On this page