---
title: "Markdown 语法"
description: "文档页面使用标准 Markdown 编写：标题决定目录与锚点，配合强调、链接、列表、表格与引用组织内容。本页列出常用语法及其在 Movk Nuxt Docs 中的渲染效果。"
canonical_url: "https://docs.mhaibaraai.cn/docs/writing/markdown-syntax"
---
# Markdown 语法

> 文档页面使用标准 Markdown 编写：标题决定目录与锚点，配合强调、链接、列表、表格与引用组织内容。本页列出常用语法及其在 Movk Nuxt Docs 中的渲染效果。

`content/docs/` 下的每个 `.md` 文件就是一个页面。正文使用标准 Markdown，需要更丰富的版式时再引入 [MDC 组件](https://docs.mhaibaraai.cn/docs/writing/mdc-components)。

## 标题

页面标题来自 frontmatter 的 `title`，正文从二级标题开始：

```mdc
## 二级标题

### 三级标题
```

- 二级与三级标题自动生成锚点，并出现在右侧目录中
- 二级标题前显示 `01`、`02` 这样的编号，与目录的一级条目一一对应
- 不要跳级，也不要在正文中再写一级标题

## 文本格式

| 样式 | 语法 | 效果 |
| --- | --- | --- |
| 粗体 | `**粗体**` | **粗体** |
| 斜体 | `*斜体*` | *斜体* |
| 删除线 | `~~删除线~~` | ~~删除线~~ |
| 粗斜体 | `***粗斜体***` | ***粗斜体*** |
| 行内代码 | `` `code` `` | `code` |

## 链接

外部链接写完整 URL：

```mdc
[Nuxt UI](https://ui.nuxt.com)
```

站内链接写从站点根开始的路径，不带文件序号前缀与 `.md` 扩展名。启用多语言时，其他语言的页面需带上语言前缀（如 `/en/docs/...`）：

```mdc
[安装](/docs/getting-started/installation)
```

> [!TIP]
> 
> 构建时会预渲染全部站内链接，指向不存在页面的链接会在构建日志中输出 
> 
> [request error]
> 
> 。

## 列表

### 无序列表

```mdc
- 安装依赖
- 编写内容
- 部署站点
```

### 有序列表

```mdc
1. 创建 `content/docs` 目录
2. 添加第一个页面
3. 运行开发服务器
```

### 嵌套列表

子项缩进两个空格：

```mdc
- 开始
  - 安装
  - 项目结构
- 指南
```

## 表格

表格适合列出属性与对比数据。单元格中的类型可以加 `{lang="ts-type"}` 获得 TypeScript 高亮：

```mdc
| Prop | Default | Type |
| --- | --- | --- |
| `name` | | `string`{lang="ts-type"} |
| `size` | `md` | `'sm' \| 'md' \| 'lg'`{lang="ts-type"} |
```

## 引用

```mdc
> 文档的价值在于读者能否按它完成任务。
>
> 每一页只解决一个问题。
```

## Frontmatter

每个页面顶部的 YAML 块描述页面元数据：

```md [content/docs/1.getting-started/2.installation.md]
---
title: 安装
description: 一句话说明本页解决什么问题，同时用作 SEO 描述与页面导语。
seo:
  title: Installation
---
```

| 字段 | 说明 |
| --- | --- |
| `title` | 页面标题，同时用于侧栏与浏览器标题 |
| `description` | 页面导语与默认 SEO 描述 |
| `seo` | 覆盖 `title` / `description` 的 SEO 版本 |
| `navigation` | 侧栏配置：`title` 覆盖侧栏中的标题，`badge` 在标题旁显示徽标 |
| `links` | 显示在导语下方元信息行的链接 |
| `category` | 在侧栏中归入的分类，见 [导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation) |
| `requires` | 版本要求，自由文本（如 `Nuxt 4.1+`），显示在导语下方的元信息行 |
| `difficulty` | 难度：`beginner`、`intermediate` 或 `advanced`，显示在元信息行 |

文件名前的数字（如 `2.installation.md`）只用于排序，不出现在 URL 中。


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
