VuePress Plume 主题 Markdown 语法完全指南

约 2588 字大约 9 分钟

2026-07-16

本文档汇总了 VuePress 2 + vuepress-theme-plume 支持的全部 Markdown 语法，涵盖基础语法、扩展语法、属性支持以及各类容器和组件。

一、Frontmatter（文章头部配置）

每篇 Markdown 文件可以通过 YAML frontmatter 设置元信息：

---
title: 文章标题
tags:
  - 标签1
  - 标签2
createTime: 2026/07/16 12:00:00
permalink: /custom/url/
---

主题可配置 autoFrontmatter 自动生成 permalink、createTime、title。

二、基础语法

2.1 标题

使用 # 号标记，支持 H1 ~ H6：

# 标题 H1
## 标题 H2
### 标题 H3
#### 标题 H4
##### 标题 H5
###### 标题 H6

2.2 文本样式

语法	效果
`加粗`	加粗
`斜体` 或 `_斜体_`	斜体
`~~删除线~~`	~~删除线~~
`==高亮==`	马克笔高亮（见下文）
`X^2^` (上标)	X²
`H~2~O` (下标)	H₂O
`行内代码`	`行内代码`

2.3 链接

# 行内链接
[链接文字](https://example.com "可选标题")

# 外部链接（自动添加 target="_blank"）
[VuePress](https://v2.vuepress.vuejs.org/)

# 内部链接（使用 permalink）
[某篇文章](/guide/markdown/)

# 内部链接（使用文件相对路径）
[基础语法](./basic.md)

# 自动链接
<https://example.com>
<email@example.com>

2.4 图片

# 行内图片
![替代文字](/path/to/image.png)
![替代文字](/path/to/image.png "可选标题")

# 可点击图片
[![替代文字](/path/to/image.png)](https://example.com)

2.5 列表

# 无序列表（支持 -、*、+）
- 项目1
- 项目2
  - 嵌套项目2.1
  - 嵌套项目2.2

# 有序列表
1. 第一项
2. 第二项
3. 第三项

# 任务列表
- [ ] 待办任务
- [x] 已完成任务

2.6 引用块

> 这是一段引用
>
> 可以多段落
>
> > 支持嵌套引用

2.7 分隔线

---
***

2.8 表格

| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 内容1  |  内容2   |  内容3 |
| 内容4  |  内容5   |  内容6 |

三、扩展语法

3.1 自定义锚点

为标题指定自定义锚点：

## 我的标题 {#my-custom-anchor}

链接跳转：[跳转](#my-custom-anchor)

3.2 目录表

[[TOC]]

自动生成当前页面的大纲目录。

3.3 脚注

这是一段需要说明的文字[^1]。

[^1]: 这是脚注的详细说明，支持 **Markdown** 语法。

3.4 自定义对齐

::: left
左对齐内容
:::

::: center
居中对齐内容
:::

::: right
右对齐内容
:::

3.5 Emoji

通过 :emoji: 语法插入表情：

:smile: :tada: :rocket: :heart: :+1:

完整列表参见 Emoji 列表

3.6 行内 HTML

可在 Markdown 中直接使用 HTML 标签：

<div style="color: red;">红色文字</div>

四、属性支持（Attrs）

在任意 Markdown 元素后添加 {...} 设置属性：

# 添加 class
**加粗文字**{.highlight}

# 添加 ID
## 标题 {#custom-id}

# 设置属性
[链接](https://example.com){target="_blank" rel="noopener"}

# 组合使用
[链接](https://example.com){.link-class #link-id target="_blank"}

# 块级元素（在下一行添加）
- 列表项目1
- 列表项目2
{.custom-list}

五、代码块增强

5.1 基础代码块

```js
const hello = 'world'
console.log(hello)
```

5.2 代码高亮行

```js
function foo() {
  const a = 1    // [!code highlight]  高亮当前行
  const b = 2    // [!code ++]         标记为新增
  const c = 3    // [!code --]         标记为删除
  const d = 4    // [!code error]      标记为错误
  const e = 5    // [!code warning]    标记为警告
  const f = 6    // [!code focus]      聚焦当前行
}


### 5.3 代码词高亮

```md
```js whitespace          // whitespace 启用空格/Tab 可见
//     高亮代码中的某个词
const obj = {
  key: 'value'
}


### 5.4 代码组（Code Tabs）

```md
::: code-tabs
@tab JavaScript
```js
const msg = 'Hello'

@tab TypeScript

const msg: string = 'Hello'

@tab Python

msg = 'Hello'

:::


### 5.5 代码行号

在主题配置中启用：

```ts
// .vuepress/config.ts
theme: plumeTheme({
  codeHighlighter: {
    lineNumbers: true,    // 显示行号
    whitespace: true,     // 空格/Tab 高亮
    twoslash: true,       // TypeScript 类型增强
  },
})

六、数学公式（KaTeX / MathJax）

6.1 内联公式

$e^{i\pi} + 1 = 0$

$\frac{\partial r}{\partial \omega}$

6.2 块级公式

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

6.3 块级（独立行）

$$
\frac {\partial^r} {\partial \omega^r}
\left(\frac {y^{\omega}} {\omega}\right)
= \left(\frac {y^{\omega}} {\omega}\right)
\left\{(\log y)^r + \sum_{i=1}^r \cdots \right\}
$$

主题默认使用 KaTeX 渲染，可选 MathJax。参考 KaTeX 支持列表。

七、提示容器（Container）

7.1 默认样式

::: note
这是一个注释框
:::

::: info
这是一个信息框
:::

::: tip
这是一个提示框
:::

::: warning
这是一个警告框
:::

::: caution
这是一个危险警告框
:::

::: details
这是一个详情折叠框
:::

7.2 自定义标题

::: danger 危险区域
请勿随意操作！
:::

::: details 点击查看代码
```js
console.log('Hello')

:::


---

## 八、GitHub 警报（GitHub Alerts）

```md
> [!NOTE]
> 这是注释信息

> [!TIP]
> 这是提示信息

> [!IMPORTANT]
> 这是重要信息

> [!WARNING]
> 这是警告信息

> [!CAUTION]
> 这是危险警告

九、马克笔（文本高亮）

9.1 基础用法

这是一个 ==重点标记== 的文本

9.2 配色方案

==默认高亮==
==信息=={.info}
==注释=={.note}
==提示=={.tip}
==警告=={.warning}
==危险=={.danger}
==注意=={.caution}
==重要=={.important}

9.3 动画模式

在主题配置中设置：

theme: plumeTheme({
  markdown: {
    mark: 'lazy',  // 滚动到可视区域再播放动画（默认：立即播放）
  },
})

十、Badge（徽章）

<Badge type="info" text="信息" />
<Badge type="tip" text="提示" />
<Badge type="warning" text="警告" />
<Badge type="danger" text="危险" />

十一、Icon（图标）

<Icon name="material-symbols:home" color="currentColor" size="1em" />
<Icon name="skill-icons:vscode-dark" size="2em" />

图标名称来自 Iconify，支持 Material Design Icons、Skill Icons 等数千个图标集。

十二、步骤（Steps）

::: steps
1. 第一步
   这是第一步的详细说明

2. 第二步
   这是第二步的详细说明

3. 第三步
   这是第三步的详细说明
:::

十三、文件树（File Tree）

::: file-tree
- package.json
- docs/
  - .vuepress/
    - config.ts
    - plume.config.ts
  - guide/
    - README.md
    - getting-started.md
  - blog/
    - hello.md
:::

十四、代码树（Code Tree）

::: code-tree
- src/
  - components/
    - Button.vue
      ```vue
      <template>
        <button>Click</button>
      </template>
      ```
    - Modal.vue
  - utils/
    - helpers.ts
:::

十五、选项组（Tabs）

::: tabs
@tab 选项1
第一个选项的内容

@tab 选项2
第二个选项的内容

@tab 选项3
第三个选项的内容
:::

十六、时间线（Timeline）

::: timeline
- 2024年
  - 1月：项目启动
  - 6月：v1.0 发布
- 2025年
  - 3月：重大重构
  - 12月：v2.0 发布
:::

十七、卡片（Card）

# 卡片容器
::: card title="卡片标题" icon="material-symbols:star"
卡片内容
:::

# 链接卡片
<LinkCard title="标题" link="/path" desc="描述" />

# 图片卡片
<ImageCard title="标题" image="/path/to/img.png" />

# 卡片网格
::: card-grid
<LinkCard title="卡片1" link="/p1" />
<LinkCard title="卡片2" link="/p2" />
<LinkCard title="卡片3" link="/p3" />
:::

# 瀑布流布局
::: card-masonry
<ImageCard title="图片1" image="/img1.png" />
<ImageCard title="图片2" image="/img2.png" />
:::

十八、折叠面板（Collapse）

::: collapse 点击展开
这里是被隐藏的内容，点击标题后展开显示。

支持 **Markdown** 语法和代码块：

```js
console.log('Hello')

:::


---

## 十九、示例容器（Window）

模拟一个带标题栏的浏览器窗口：

```md
::: window title="示例窗口" height="200px"
<style scoped>
.demo { color: red; }
</style>
<div class="demo">窗口内的内容</div>
:::

二十、Flex 容器

::: flex
<div>左侧内容</div>
<div>右侧内容</div>
:::

二十一、字段容器（Field）

::: field
字段名：字段值
:::

二十二、对话记录（Chat）

::: chat
@A
这是 A 的消息

@B
这是 B 的回复

@A 时间
这是带时间的消息
:::

二十三、npmTo 容器

::: npm-to
express
:::

二十四、Can I Use 容器

::: caniuse
css-grid
:::

显示来自 Can I Use 的浏览器兼容性数据。

二十五、二维码（QRCode）

<QRCode value="https://example.com" />

根据传入的值自动生成二维码。

二十六、隐秘文本（Plot）

<Plot>一些需要隐藏的剧透内容</Plot>

二十七、缩写词（Abbreviation）

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

二十八、内容注释（Annotation）

::: annotation
这是对正文内容的补充注释
:::

二十九、导入文件（Include）

<!-- 导入另一个 Markdown 文件的内容 -->
@include ./path/to/file.md

被导入文件的内容会被直接嵌入到当前位置。

三十、环境预设（Env）

::: env
可以使用 {{ variable }} 语法引用环境变量
:::

三十一、Obsidian 兼容

Plume 主题兼容 Obsidian 的部分语法：

# Wiki 链接风格
[[页面名称]]
[[页面名称|显示文字]]

# 图片调整
![[image.png|300]]

# Callout 语法
> [!note] 标题
> 内容

> [!danger] 警告
> 内容

三十二、Vue 组件

32.1 自定义组件

在 .vuepress/components/ 目录下创建 Vue 组件，然后在 Markdown 中直接使用：

<CustomComponent />

32.2 Repo 卡片

<RepoCard repo="vuejs/vue" />

32.3 Npm 徽章

<NpmBadge name="vuepress-theme-plume" />

32.4 轮播图（Swiper）

<Swiper :items="swiperItems" />

32.5 首页布局容器

<HomeBox>
<HomeBoxItem title="标题" desc="描述" link="/path" />
</HomeBox>

三十三、表格增强

33.1 合并单元格

| A                       | B   | C   | D                |
| ----------------------- | --- | --- | ---------------- |
| 1                       | 11  | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22  | 222 | 2222             |
| 3                       | 33  | 333 | 3333             |

在单元格内容后使用 {rowspan=n} 或 {colspan=n} 合并单元格。

三十四、高级链接功能

34.1 图片预览

主题内置图片预览功能，点击图片即可放大查看。

34.2 资源链接替换

可在配置中将特定链接前缀替换为其他地址：

theme: plumeTheme({
  replaceAssets: {
    '@alias/': '/path/to/',
  },
})

三十五、快速参考总结

类别	功能	语法
标题	H1-H6	`# ~ ######`
文本	加粗/斜体/删除线	`bold` / `italic` / `~~del~~`
文本	上标/下标	`X^2^` / `H~2~O`
文本	马克笔高亮	`==text==`
文本	配色马克笔	`==text=={.tip}`
列表	任务列表	`- [ ]` / `- [x]`
链接	内外部链接	`[text](url)`
链接	自动链接	`<url>`
图片	图片	`![alt](url)`
表格	基础表格	`\| col \| col \|`
表格	合并单元格	`{rowspan=n colspan=n}`
代码	行内代码	`code`
代码	围栏代码块	```lang ```
代码	代码行高亮	`// [!code highlight]`
代码	代码组	`::: code-tabs`
代码	词高亮	`// [!code word:xxx]`
引用	引用块	`> quote`
引用	GitHub 警报	`> [!NOTE]`
容器	提示容器	`::: note/info/tip/warning/caution/details`
容器	步骤	`::: steps`
容器	文件树	`::: file-tree`
容器	代码树	`::: code-tree`
容器	选项组	`::: tabs`
容器	时间线	`::: timeline`
容器	卡片	`::: card`
容器	折叠面板	`::: collapse`
容器	示例窗口	`::: window`
容器	Flex 布局	`::: flex`
容器	对话框	`::: chat`
容器	对齐容器	`::: left/center/right`
组件	徽章	`<Badge type="tip" text="xxx" />`
组件	图标	`<Icon name="xxx" />`
组件	隐秘文本	`<Plot>`
组件	二维码	`<QRCode>`
组件	链接卡片	`<LinkCard>`
组件	Repo 卡片	`<RepoCard>`
数学	内联/块级公式	$...$ / `$$...$$`
表情	Emoji	`:smile:`
目录	目录表	`[[TOC]]`
脚注	脚注	`[^1]`
属性	元素属性	`{.class #id attr=val}`
锚点	自定义锚点	`{#my-anchor}`
缩写	缩写词	`*[HTML]: 定义`
导入	文件导入	`@include ./file.md`
兼容	Obsidian Wiki	`[[page]]`