343 lines
5.9 KiB
Plaintext
343 lines
5.9 KiB
Plaintext
---
|
||
title: Markdown
|
||
description: 如何撰写文档
|
||
---
|
||
|
||
## 介绍
|
||
|
||
Fumadocs 为 MDX（一种标记语言）提供了许多有用的扩展。以下是 Fumadocs UI 默认 MDX 语法的简要介绍。
|
||
|
||
> MDX 不是 Fumadocs 唯一支持的格式。实际上，您可以使用任何渲染器，如 `next-mdx-remote` 或 CMS。
|
||
|
||
## Markdown
|
||
|
||
我们使用 GFM（GitHub 风格的 Markdown），这是 Markdown（CommonMark）的超集。
|
||
参见 [GFM 规范](https://github.github.com/gfm)。
|
||
|
||
````md
|
||
# 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 |
|
||
````
|
||
|
||
### 自动链接
|
||
|
||
内部链接使用 `next/link` 组件，允许预取并避免硬重载。
|
||
|
||
外部链接将获得默认的 `rel="noreferrer noopener" target="_blank"` 属性以增强安全性。
|
||
|
||
```mdx
|
||
[My Link](https://github.github.com/gfm)
|
||
|
||
This also works: https://github.github.com/gfm.
|
||
```
|
||
|
||
## MDX
|
||
|
||
MDX 是 Markdown 的超集，支持 JSX 语法。
|
||
它允许您导入组件，并直接在文档中使用它们，甚至导出值。
|
||
|
||
```mdx
|
||
import { Component } from './component';
|
||
|
||
<Component name="Hello" />
|
||
```
|
||
|
||
参见 [MDX 语法](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) 了解更多信息。
|
||
|
||
### 卡片
|
||
|
||
对于添加链接很有用，默认包含。
|
||
|
||
```mdx
|
||
<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>
|
||
```
|
||
|
||
<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>
|
||
|
||
#### 图标
|
||
|
||
您可以为卡片指定图标。
|
||
|
||
```mdx
|
||
import { HomeIcon } from 'lucide-react';
|
||
|
||
<Cards>
|
||
<Card icon={<HomeIcon />} href="/" title="Home">
|
||
Go back to home
|
||
</Card>
|
||
</Cards>
|
||
```
|
||
|
||
<Cards>
|
||
<Card icon={<HomeIcon />} href="/" title="Go back to home">
|
||
The home page of Fumadocs.
|
||
</Card>
|
||
</Cards>
|
||
|
||
#### 无 href
|
||
|
||
```mdx
|
||
<Cards>
|
||
<Card title="Fetching, Caching, and Revalidating">
|
||
Learn more about `fetch` in Next.js.
|
||
</Card>
|
||
</Cards>
|
||
```
|
||
|
||
<Cards>
|
||
<Card title="Fetching, Caching, and Revalidating">
|
||
Learn more about `fetch` in Next.js.
|
||
</Card>
|
||
</Cards>
|
||
|
||
### 提示框
|
||
|
||
对于添加提示/警告很有用，默认包含。
|
||
|
||
```mdx
|
||
<Callout>Hello World</Callout>
|
||
```
|
||
|
||
<Callout>Hello World</Callout>
|
||
|
||
#### 标题
|
||
|
||
指定提示框标题。
|
||
|
||
```mdx
|
||
<Callout title="Title">Hello World</Callout>
|
||
```
|
||
|
||
<Callout title="Title">Hello World</Callout>
|
||
|
||
#### 类型
|
||
|
||
您可以指定提示框的类型。
|
||
|
||
- `info`（默认）
|
||
- `warn`
|
||
- `error`
|
||
|
||
```mdx
|
||
<Callout title="Title" type="error">
|
||
Hello World
|
||
</Callout>
|
||
```
|
||
|
||
<Callout title="Title" type="error">
|
||
Hello World
|
||
</Callout>
|
||
|
||
### 自定义组件
|
||
|
||
参见[所有 MDX 组件和可用选项](/docs/mdx)。
|
||
|
||
## 标题
|
||
|
||
每个标题会自动应用锚点，它会清理空格等无效字符。（例如，`Hello World` 变为 `hello-world`）
|
||
|
||
```md
|
||
# Hello `World`
|
||
```
|
||
|
||
### 目录设置
|
||
|
||
目录 (TOC) 将基于标题生成，您还可以自定义标题的效果：
|
||
|
||
```md
|
||
# 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 />
|
||
```
|
||
|
||
### 自定义锚点
|
||
|
||
您可以添加 `[#slug]` 来自定义标题锚点。
|
||
|
||
```md
|
||
# heading [#my-heading-id]
|
||
```
|
||
|
||
您也可以将其与目录设置链接起来，例如：
|
||
|
||
```md
|
||
# heading [toc] [#my-heading-id]
|
||
```
|
||
|
||
要将人们链接到特定标题，请将标题 ID 添加到哈希片段：`/page#my-heading-id`。
|
||
|
||
## 前言
|
||
|
||
我们支持 YAML 前言。这是一种指定文档常见信息（例如标题）的方式。
|
||
将其放在文档顶部。
|
||
|
||
```mdx
|
||
---
|
||
title: Hello World
|
||
---
|
||
|
||
## Title
|
||
```
|
||
|
||
有关前言可用属性的列表，请参见[页面约定](/docs/page-conventions#frontmatter)。
|
||
|
||
## 代码块
|
||
|
||
默认使用 [Rehype Code](/docs/headless/mdx/rehype-code) 支持语法高亮。
|
||
|
||
````mdx
|
||
```js
|
||
console.log('Hello World');
|
||
```
|
||
````
|
||
|
||
您可以为代码块添加标题。
|
||
|
||
````mdx
|
||
```js title="My Title"
|
||
console.log('Hello World');
|
||
```
|
||
````
|
||
|
||
### 高亮行
|
||
|
||
````md
|
||
```tsx
|
||
<div>Hello World</div> // [\!code highlight]
|
||
<div>Hello World</div>
|
||
<div>Goodbye</div>
|
||
<div>Hello World</div>
|
||
```
|
||
````
|
||
|
||
### 高亮单词
|
||
|
||
您可以通过添加 `[!code word:<match>]` 来高亮特定单词。
|
||
|
||
````md
|
||
```js
|
||
// [\!code word:config]
|
||
const config = {
|
||
reactStrictMode: true,
|
||
};
|
||
```
|
||
````
|
||
|
||
### 差异
|
||
|
||
````mdx
|
||
```ts
|
||
console.log('hewwo'); // [\!code --]
|
||
console.log('hello'); // [\!code ++]
|
||
```
|
||
````
|
||
|
||
```ts
|
||
console.log('hewwo'); // [!code --]
|
||
console.log('hello'); // [!code ++]
|
||
```
|
||
|
||
### 标签组
|
||
|
||
您可以使用 `<Tab />` 组件与代码块一起使用。
|
||
|
||
````mdx
|
||
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>
|
||
````
|
||
|
||
> 注意，您可以在 MDX 文件中添加 MDX 组件，而不必导入它们。
|
||
|
||
<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>
|
||
|
||
### 使用 Typescript Twoslash
|
||
|
||
编写带有悬停类型信息和检测到类型错误的 Typescript 代码块。
|
||
|
||
默认情况下未启用。参见 [Twoslash](/docs/twoslash)。
|
||
|
||
## 图片
|
||
|
||
所有内置内容源都能正确处理图片。
|
||
图片会自动为 `next/image` 优化。
|
||
|
||
```mdx
|
||
|
||
```
|
||
|
||
|
||
|
||
## 可选功能
|
||
|
||
一些您可以启用的可选插件。
|