---
title: MDX 基础
description: 使用嵌入 Card、Tabs 和 Accordion 等 React 组件的 Markdown 编写文档。这是每个 Jamdesk 页面的底层语法。
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

每个 Jamdesk 页面都是一个 `.mdx` 文件：使用 `<Card>`、`<Tabs>` 和 `<Accordion>` 等 JSX 组件的标准 Markdown。

## 什么是 MDX？

MDX 允许你在同一文件中编写标准 Markdown 并嵌入 JSX 组件。使用 Markdown 编写标题、列表和代码块，然后根据交互需求插入 `<Card>` 或 `<Tabs>` 等组件。

MDX 也非常适合 AI 工具需要读取的文档：它是纯文本（因此 AI 工具可以原生读写），可在 Git 中进行版本控制，并且结构足够支持组件，而无需使用专有格式。

```mdx
# Welcome to My Docs

This is regular **Markdown** with a component below:

<Card title="Quickstart" icon="rocket" href="/quickstart">
  Jump right in with our quickstart guide.
</Card>
```

<Tip>
  两个免费的浏览器工具可以帮助你编写： [MDX Validator](https://jamdesk.com/utilities/mdx-validator)
  可在构建前捕获语法错误，[MDX Formatter](https://jamdesk.com/utilities/mdx-formatter)
  可整理空格和缩进。粘贴页面即可检查或整理，无需运行 CLI。
</Tip>

## 页面结构

每个 MDX 页面都以 frontmatter 开头，即位于三个短横线之间的元数据：

```mdx
---
title: My Page Title
description: A brief description for search and previews
---

Your content starts here...
```

<Note>
`title` 和 `description` 会显示在搜索结果、浏览器标签页和社交媒体预览中。请认真编写。
</Note>

## Markdown 基础

### 标题

使用 `##` 表示主要章节，使用 `###` 表示子章节。Jamdesk 会根据标题自动生成目录。

```markdown
## Main Section
Content under the main section.

### Subsection
More detailed content here.
```

<Tip>
第一个标题从 `##`（h2）开始。frontmatter 中的页面标题会作为 h1。
</Tip>

### 文本格式

| 语法 | 结果 |
|--------|--------|
| `**bold**` | **粗体** |
| `*italic*` | *斜体* |
| `~~strikethrough~~` | ~~删除线~~ |
| `` `inline code` `` | `inline code` |

### 列表

```markdown
Unordered list:
- First item
- Second item
  - Nested item

Ordered list:
1. First step
2. Second step
3. Third step
```

### 引用块

```markdown
> This is a blockquote. Use it for callouts or
> highlighting important information.
```

> 这是一个引用块。用于添加提示或突出显示重要信息。

## 添加组件

组件是可以在 MDX 中任意位置使用的 JSX 元素。它们可以是自闭合元素，也可以包裹内容：

```mdx
{/* Self-closing component */}
<Card title="Example" icon="star" href="/introduction" />

{/* Component wrapping content */}
<Accordion title="Click to expand">
  This content is inside the accordion.
</Accordion>
```

### 可用组件

Jamdesk 提供以下内置组件：

<Columns cols={2}>
  <Card title="卡片" icon="square" href="/cn/components/card">
    突出显示功能并创建导航
  </Card>
  <Card title="选项卡" icon="table-columns" href="/cn/components/tabs">
    将内容整理到可切换的面板中
  </Card>
  <Card title="折叠面板" icon="chevron-down" href="/cn/components/accordion">
    用于可选内容的可折叠章节
  </Card>
  <Card title="步骤" icon="list-ol" href="/cn/components/steps">
    编号流程和教程
  </Card>
</Columns>

## 表格

标准 Markdown 表格开箱即用：

```markdown
| Feature | Free | Pro |
|---------|------|-----|
| Pages | 10 | Unlimited |
| Custom domain | No | Yes |
```

| 功能 | 免费版 | Pro 版 |
|---------|------|-----|
| 页面 | 10 | 不限 |
| 自定义域名 | 否 | 是 |

如需行突出显示、单元格对齐和跨列等高级功能，请使用 Table 组件：

<Table striped>
  <Row header>
    <Cell>功能</Cell>
    <Cell align="center">免费版</Cell>
    <Cell align="center">Pro 版</Cell>
  </Row>
  <Row>
    <Cell>页面</Cell>
    <Cell align="center">10</Cell>
    <Cell align="center" highlight highlightColor="success">不限</Cell>
  </Row>
  <Row>
    <Cell>自定义域名</Cell>
    <Cell align="center">否</Cell>
    <Cell align="center" highlight highlightColor="success">是</Cell>
  </Row>
</Table>

<Note>
请参阅 [表格](/cn/components/tables)，了解完整的组件文档，包括行/单元格突出显示、跨列和样式选项。
</Note>

## 注释

添加不会出现在渲染结果中的注释：

```mdx
{/* This is a comment - it won't be visible to readers */}
```

## 接下来做什么？

<Columns cols={2}>
  <Card title="SEO 优化" icon="magnifying-glass-chart" href="/cn/content/seo">
    提升内容发现率并优化元数据
  </Card>
  <Card title="Frontmatter" icon="file-lines" href="/cn/content/frontmatter">
    定义标题、描述和 SEO 字段
  </Card>
</Columns>