MkSaaS DocsMarkdown
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
| Table | Description |
| ----- | ----------- |
| Hello | World |Auto Links
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>Title
Specify a callout title.
<Callout title="Title">Hello World</Callout>Title
Types
You can specify the type of callout.
info(default)warnerror
<Callout title="Title" type="error">
Hello World
</Callout>Title
Hello World
Customise Components
See all MDX components and available options.
Headings
An anchor is automatically applied to each heading, it sanitizes invalid characters like spaces. (e.g. Hello World to hello-world)
# Hello `World`TOC Settings
The table of contents (TOC) will be generated based on headings, you can also customise the effects of headings:
# Heading [!toc]
This heading will be hidden from TOC.
# Another Heading [toc]
This heading will **only** be visible in TOC, you can use it to add additional TOC items.
Like headings rendered in a React component:
<MyComp />Custom Anchor
You can add [#slug] to customise heading anchors.
# heading [#my-heading-id]You can also chain it with TOC settings like:
# heading [toc] [#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
---
## TitleSee 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'); Tab Groups
You can use code blocks with the <Tab /> component.
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
<Tabs items={['Tab 1', 'Tab 2']}>
<Tab value='Tab 1'>
```ts
console.log('A');
```
</Tab>
<Tab value='Tab 2'>
```ts
console.log('B');
```
</Tab>
</Tabs>Note that you can add MDX components instead of importing them in MDX files.
console.log('A');console.log('B');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.
Optional
Some optional plugins you can enable.
Math Equations
Write math equations with TeX.
```mdx
f(x) = x * e^{2 pi i \xi x}
```f(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).
```mdx
npm i next -D
```npm i next -DTo enable, see Remark Install.
More
You can see a list of plugins supported by Fumadocs.