如何撰写文档
使用 Markdown 和 MDX 撰写文档的指南
介绍
这里简单介绍一下默认的 MDX 语法。
MDX 并非是唯一支持的格式。事实上，可以使用任何渲染器。
MDX 语法
MDX 是 Markdown 的超集，支持所有 Markdown 语法，允许你导入自定义组件，并在文档中使用它们。 甚至可以使用 JS 语法来编写交互式组件。
参考资料：
关于链接
内部链接使用
<Link />
React框架的组件（例如next/link）来允许预取并避免硬重新加载。
外部链接将获得默认rel="noreferrer noopener" target="_blank"属性以确保安全。
常用语法
# 一级标题
## 二级标题
### 三级标题
#### 四级标题页面头部参数
可以在 MDX 文件的开头使用 YAML 语法定义页面的元数据，例如标题、描述和图标：
---
title: 页面标题
description: 页面描述
icon: CircleQuestionMark
---链接到其他文档
[前往 程序设计的语言和分类](../python/1/1-1)也可以链接到其他文档的锚点：
[`前往 高级语言`](../python/1/1-1/#高级语言)卡片组块
适用于添加链接的卡片组块。
<Cards>
<Card
title="可链接的卡片示例"
href="/docs/sudynotes/"
description="返回文档首页"
/>
<Card title="不添加链接的卡片示例" description="了解不同的编程语言及其分类" />
<Card icon={<HomeIcon />} href="/" title="首页">
当然，也可添加图标。
</Card>
</Cards>提示块
提示块用于显示信息、成功、警告和错误消息。
默认提示块为信息类型。
<Callout title="信息" type="info">
这是信息提示块。
</Callout>信息
这是信息提示块。
成功
这是成功提示块。
警告
这是警告提示块。
错误
这是错误提示块。
代码块进阶使用
代码块默认支持语法高亮，可以指定代码语言：
js/python/java/bash/ts/mdx等
```ts
const a = 'Hello World';
console.log(a);
```代码块行号
可以为代码块添加行号：
```python lineNumbers
def hello_world():
print("lineNumbers为添加行号")
```当然，也可以设置从特定行号开始：
```python lineNumbers=5
def hello_world():
print("lineNumbers从5开始")
```@shikijs/transformers支持
可以使用@shikijs/transformers来增强代码块功能，例如添加类型检查、错误提示等。
详细信息可参阅：shikijs/transformers。
下面是一个例子：
```tsx
// highlight a line
<div>单行高亮</div> // [!code highlight]
// highlight a word
// [!code word:NextDocs]
<div>NextDocs</div>
// diff styles
console.log('提示删除了此行'); // [!code --]
console.log('提示添加了此行'); // [!code ++]
// focus
return new ResizeObserver(() => {}) // [!code focus]
```选项卡组块
可以添加选项卡组块，使用 ```mdx tab="选项卡标题" ``` 来添加选项卡。
```python tab="选项卡标题一"
def hello_world():
print("A")
```
```python tab="选项卡标题二"
def hello_world():
print("B")
```def hello_world():
print("A")可配置文件使选项卡中使用MDX语法：
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkCodeTabOptions: {
parseMdx: true,
},
},
});提示
启用parseMdx选项后，选项卡内可以使用MDX语法，但请注意，这可能会影响编译性能。
```ts tab="<Building /> 选项卡标题一"
console.log('A');
```
```ts tab="<Rocket /> 选项卡标题二"
console.log('B');
```console.log('A');引用
可以引用本站内的文件（可以是 Markdown/MDX 文档）。在标签中指定目标文件路径<include>（需使用绝对路径）。
<include>../mdx/page.mdx</include>npm 命令
生成不同的包管理器命令
```npm
npm run build
```这篇文章怎么样？
Last updated on