Markdown 渲染效果展示

这篇文章按模块展示本站支持的全部 Markdown 语法与自定义指令。每个模块用「效果 / 语法」一组标签页对照：效果页看渲染出来的样子，语法页给出可直接复制的源码。想给文章加某种效果时，从右侧目录按模块直达即可。

IMPORTANT

数学公式、Mermaid 图表、图片图库与灯箱按文章在 frontmatter 里开关：math: true、mermaid: true、gallery: true、lightbox: true，本篇全部开启。

TIP

「语法」页的源码写在代码块里：被展示的源码自身也含代码块时，外层围栏要比内层多用一根反引号。容器指令嵌套同理——外层冒号多于内层，闭合围栏从最内层逐层递增。

#文本样式

这是一段普通文本，包含粗体、斜体、粗斜体、~~删除线~~、高亮与 Ctrl + K 键盘按键。

上下角标用行内 HTML 写：水的分子式 H₂O，勾股定理 a² + b² = c²。

行内剧透：把鼠标悬停在这句话上——被隐藏的内容就出现了，适合在句子中间藏关键信息。原生 Emoji 字符 😀🚀 直接写就是。

样式之间可以互相嵌套：高亮里的粗体、粗体里的斜体与代码。

1
这是一段普通文本，包含**粗体**、*斜体*、***粗斜体***、~~删除线~~、<mark>高亮</mark> 与 <kbd>Ctrl</kbd> + <kbd>K</kbd> 键盘按键。
2

3
上下角标用行内 HTML 写：水的分子式 H<sub>2</sub>O，勾股定理 a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup>。
4

5
行内剧透：把鼠标悬停在这句话上——:spoiler[被隐藏的内容就出现了]，适合在句子中间藏关键信息。原生 Emoji 字符 😀🚀 直接写就是。
6

7
样式之间可以互相嵌套：<mark>高亮里的**粗体**</mark>、**粗体里的*斜体*与`代码`**。

WARNING

上角标 ^x^、下角标 ~x~ 与 Emoji shortcode（:smile:）均不支持：~x~ 会被解析成删除线，shortcode 原样显示，定义列表（术语 + : 定义）也会渲染成普通段落。角标改用 <sup>/<sub> 行内 HTML，Emoji 直接写原生字符。

#标题与目录

正文从二级标题 ## 开始，一级让给文章题目。每个标题都生成锚点，悬浮可见；右侧目录默认展示二到四级标题，frontmatter 写 toc: false 可整篇关闭。

三级标题

四级标题

五级标题

六级标题

#列表

无序列表多层嵌套时，圆点样式逐层变化（实心 → 空心 → 方块）：

第一项
第二项
- 嵌套子项 A
  - 深层子项 A1
  - 深层子项 A2
- 嵌套子项 B
第三项

有序列表的层级编号自动拼成 2.1.、2.1.1.：

第一步
第二步
1. 子步骤 2.1
2. 子步骤 2.2
第三步

任务列表渲染为勾选框：

已完成的任务
勾选状态与文字建议对应
待完成的任务

1
- 第一项
2
- 第二项
3
  - 嵌套子项 A
4
    - 深层子项 A1
5
  - 嵌套子项 B
6
- 第三项
7

8
1. 第一步
9
2. 第二步
10
   1. 子步骤 2.1
11
   2. 子步骤 2.2
12
3. 第三步
13

14
- [x] 已完成的任务
15
- [ ] 待完成的任务

#引用与告警

这是一个普通的引用块。引用块可以包含多个段落，以及粗体、斜体等行内格式。

VitePress 风格告警按语义选用：注意用 NOTE，操作建议用 TIP，关键依赖用 IMPORTANT，风险提示用 WARNING，危险操作用 CAUTION。

NOTE

这是一条注意告警。用于提供额外的有用信息，帮助读者理解上下文。

TIP

这是一条提示告警。用于给出操作建议或更高效的使用方式。

IMPORTANT

这是一条重要告警。用于强调关键信息，读者不应忽略。

WARNING

这是一条警告告警。提示读者注意潜在风险或需要特别注意的内容。

CAUTION

这是一条危险告警。告知读者可能导致的负面后果或需要避免的操作。

标题后跟 + 表示默认展开，跟 - 表示默认收起：

NOTE

这是一条默认展开的折叠告警，点击标题可将其收起。

TIP

这是一条默认收起的折叠告警，点击标题可展开查看。

1
> 这是一个普通的引用块，可以包含多个段落。
2

3
> [!NOTE]
4
> 这是一条**注意**告警。
5

6
> [!NOTE]+
7
> 标题后跟 `+` 表示默认展开。
8

9
> [!TIP]-
10
> 跟 `-` 表示默认收起。

WARNING

告警只认 > [!NOTE] 这样的引用块写法。写成 :::note 容器指令不会报错，但会静默降级成无样式的普通容器。

#表格

特性	支持情况	说明
对齐	✅	冒号写在左侧、两侧、右侧分别左对齐、居中、右对齐
宽表	✅	列数多时自动横向滚动，不撑破版面
行内样式	✅	粗体、`代码`、链接都可用

左对齐	居中对齐	右对齐
Apple	🍎	红色
Banana	🍌	黄色
Cherry	🍒	红色

1
| 左对齐 | 居中对齐 | 右对齐 |
2
|:-------|:--------:|-------:|
3
| Apple | 🍎 | 红色 |
4
| Banana | 🍌 | 黄色 |

#代码

行内代码用反引号包住：const x = 42;。配置键 siteConfig.name 这类写法也会渲染为行内代码。

带标题与行高亮的代码块

代码块自带行号与文件图标（按 title 的文件名推断）；title 给出标题，{行号} 高亮指定行或区间，支持 python、bash、json 等所有语言：

1
type ColorMode = 'light' | 'dark' | 'auto';
2

3
// 高亮这一行
4
export function setMode(mode: ColorMode) {
5
  // 以下三行被高亮
6
  const isDark = mode === 'dark'
7
    || (mode === 'auto'
8
      && window.matchMedia('(prefers-color-scheme: dark)').matches);
9
  document.documentElement.classList.toggle('dark', isDark);
10
}

1
pnpm install
2
pnpm dev
3
pnpm build

1
```ts title="src/config/site.ts" {3, 6-8}
2
type ColorMode = 'light' | 'dark' | 'auto';
3
```
4

5
```bash title="终端命令"
6
pnpm install
7
```

代码块行级折叠

collapse={起-止} 把区间收成一行「N collapsed lines」摘要，点击展开，适合隐藏长文件里不重要的中间片段；多个区间用逗号分隔，collapseStyle 还可选 collapsible-start / collapsible-end（向下 / 向上展开）：

1
// 第 1 行 — 始终可见
2
const data = {
3
  id: 1001,
4 collapsed lines
4
  name: "demo",
5
  active: true,
6
  tags: ["md"],
7
  version: "2.0.0",
8
};
9
// 最后一行 — 始终可见

1
```ts collapse={4-7}
2
// 第 4-7 行收成一行摘要，点击展开
3
```

#Tabs 标签页

并列内容——多语言示例、多方案对照——用 ::::tabs 包多个 :::tab{title="..."}。标签页默认会生成目录条目（右侧目录里的 TypeScript / Python / Rust 就是它生成的，点击可直达对应标签页）；不想要时加 {notoc} 修饰，本篇所有「效果 / 语法」标签页都是这么关掉的。

1
interface Post {
2
  title: string;
3
  pubDate: Date;
4
  tags: string[];
5
  draft: boolean;
6
}
7

8
const posts: Post[] = await getCollection('posts');
9
const published = posts.filter(p => !p.data.draft);

1
from dataclasses import dataclass
2
from datetime import date
3

4
@dataclass
5
class Post:
6
    title: str
7
    pub_date: date
8
    tags: list[str]
9
    draft: bool = False
10

11
published = [p for p in posts if not p.draft]

1
struct Post {
2
    title: String,
3
    pub_date: String,
4
    tags: Vec<String>,
5
    draft: bool,
6
}
7

8
let published: Vec<&Post> = posts
9
    .iter()
10
    .filter(|p| !p.draft)
11
    .collect();

上面这组的源码（源码内含代码块，外层围栏多用一根反引号）：

1
::::tabs
2
:::tab{title="TypeScript"}
3

4
```ts
5
const posts: Post[] = await getCollection('posts');
6
```
7

8
:::
9

10
:::tab{title="Python"}
11

12
```python
13
published = [p for p in posts if not p.draft]
14
```
15

16
:::
17
::::

#折叠面板

:::folding{title="..."} 折叠任意内容块，加 open 默认展开，摘要右侧自动带展开 / 收起指示。适合放次要内容与长示例：

点击展开 — 查看详细配置说明

这是一段折叠内容。折叠面板适合放置：

详细配置示例
扩展阅读材料
不希望在首屏展示的长篇内容

1
export const advancedConfig = {
2
  enableFeatureX: true,
3
  maxRetries: 3,
4
  timeout: 5000,
5
};

默认展开的折叠面板

这个面板带有 open 属性，默认是展开状态，适合放置希望读者看到的补充信息。

场景	推荐做法
补充说明	折叠面板
关键信息	直接展示

1
:::folding{title="点击展开 — 查看详细配置说明"}
2

3
折叠内容支持列表、代码块、表格等全部块级语法。
4

5
```ts
6
export const advancedConfig = {};
7
```
8
:::
9

10
:::folding{title="默认展开" open}
11

12
带 `open` 属性默认展开。
13
:::

HTML 折叠

<details> + <summary> 是浏览器原生折叠元素，Markdown 里直接写：

这是一段剧透/折叠文字，点击展开

使用 <details> 元素实现，适合隐藏剧透内容或补充说明。

1
<details>
2
<summary>这是一段剧透/折叠文字，点击展开</summary>
3

4
内容前留一个空行，内部才按 Markdown 渲染。
5

6
</details>

折叠里的嵌套

折叠面板可以嵌套任何块级内容——告警、列表、表格、图表乃至另一层折叠。视频是例外：折叠里要用无闭合围栏的叶子指令 ::video（容器写法 :::video 在折叠内会因闭合围栏解析漏出字面 :::）：

嵌套演示：告警、列表与视频

TIP

折叠里的告警正常渲染。

折叠里的列表项
第二项

1
:::folding{title="嵌套演示：告警、列表与视频"}
2

3
> [!TIP]
4
> 折叠里的告警正常渲染。
5

6
- 折叠里的列表项
7

8
::video{type="bilibili" id="BV1GJ411x7h7"}
9
:::

#数学公式

frontmatter 开 math: true 后，行内公式用 $...$ ，块级公式用 $$...$$：

WARNING

块级公式的 $$ 必须各占一行。写成单行 $$x$$ 会被解析成行内公式，引用块里也一样（每行加 > 前缀即可嵌进引用块）。

行内：爱因斯坦质能方程 $E = mc^2$ ，欧拉恒等式 $e^{i\pi} + 1 = 0$ 。

块级，二次方程求根公式：

x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

多行对齐与矩阵：

\begin{aligned} \nabla \times \vec{\mathbf{B}} - \frac{1}{c} \, \frac{\partial\vec{\mathbf{E}}}{\partial t} &= \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} &= 4\pi\rho \end{aligned}

\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} ax + by \\ cx + dy \end{pmatrix}

1
行内：爱因斯坦质能方程 $E = mc^2$。
2

3
$$
4
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
5
$$

#Mermaid 图表

```mermaid 围栏画图表，frontmatter 开 mermaid: true；构建期渲染为浅色 / 深色双主题 SVG，支持拖拽平移、滚轮缩放与全屏查看：

流程图：

时序图：

甘特图：

1
```mermaid
2
flowchart TD
3
  A[开始] --> B{条件判断}
4
  B -->|是| C[执行操作]
5
  B -->|否| D[执行备选]
6
  C --> E[输出结果]
7
  D --> E
8
  E --> F[结束]
9
```

#图片与图库

单图直接 ![说明](地址)；连续多行图片（中间不空行）自动组成图库，点击任意一张开灯箱看大图。frontmatter 用 gallery / lightbox 开关：

上面三张连续图片自动组成图库，点击可开灯箱。

1
![说明文字](图片地址 "悬浮标题")
2

3
![湖泊与山脉](图片地址)
4
![绿色森林中的小路](图片地址)
5
![海边日落](图片地址)

#视频嵌入

:::video{type="..." id="..."} 嵌视频，支持 bilibili、bilibili-nano、youtube、tiktok 与 raw（直链 mp4），ratio 可调宽高比。嵌进折叠面板时改用叶子指令 ::video（见「折叠里的嵌套」）：

Bilibili

YouTube

1
:::video{type="bilibili" id="BV1GJ411x7h7"}
2
:::
3

4
:::video{type="youtube" id="dQw4w9WgXcQ"}
5
:::

Git 从诞生到设计理念

从 Linux 内核开发的危机讲起，理解 Git 的分布式设计哲学、核心优势，以及它与 SVN 等版本控制系统的本质区别

2026-05-13版本控制#Git#版本控制#入门教程

XingHeYuZhuan/shiguangschedule 一款开源、无广告、极简的课程表 APP，支持教务导入

Kotlin941Apache-2.0

1
:::linkcard{url="https://astro.build" title="Astro 官网" icon="https://astro.build/favicon.svg"}
2
:::
3

4
:::linkcard{post="git-introduction"}
5
:::
6

7
:::github{repo="XingHeYuZhuan/shiguangschedule"}
8
:::

三种卡片各司其职：

外链卡 :::linkcard{url=...}：一行放标题，第二行显示链接本身，不放简介；icon 可省略，自动抓站点图标。
站内卡 :::linkcard{post="文章id"}：标题、简介、日期、分类、标签与封面由目标文章 frontmatter 自动填充，不随手动内容漂移。
GitHub 卡 :::github{repo="owner/仓库"}：展示描述、语言、star 与 license；新增仓库后先运行 pnpm github-cards 拉取数据，否则退化为普通链接。

脚注

正文用 [^标签] 引用，定义写在文中任意位置，渲染时统一汇总到文末的「参考资料」卡片——参考链接统一走脚注。这是一个脚注示例 ¹，脚注定义里可以放链接和说明 ²。

1
这是一个脚注示例 [^1]。
2

3
[^1]: 这是一条脚注内容，定义写在文中任意位置。

#语法速查

需求	写法
粗体 / 斜体 / 删除线	`粗体` / `斜体` / `~~删除线~~`
高亮 / 键盘按键	`<mark>高亮</mark>` / `<kbd>Ctrl</kbd>`
上下角标	`x<sup>2</sup>` / `H<sub>2</sub>O`
行内剧透	`:spoiler[文字]`
告警	`> [!NOTE]`，`+` / `-` 控制默认展开收起
折叠面板	`:::folding{title="标题"}`，可加 `open`
标签页	`::::tabs` + `:::tab{title="..."}`，可加 `notoc`
代码块增强	围栏 meta：`title="文件名"`、`{1,3-4}` 高亮、`collapse={5-8}` 行折叠
行内 / 块级公式	$E=mc^2$ / `$$` 各占一行（frontmatter `math: true`）
Mermaid 图表	mermaid 围栏代码块（frontmatter `mermaid: true`）
图片图库	连续多行 `![说明](地址)` 自动成组
视频	`:::video{type="bilibili" id="BV..."}`，折叠内用 `::video`
链接卡片	`:::linkcard{url="..." title="..."}` / `{post="文章id"}`
GitHub 卡片	`:::github{repo="owner/仓库"}`
脚注	`[^1]` 引用 + 文中任意位置 `[^1]: 定义`
分割线	独占一行的 `---`

渲染效果在浅色和深色模式下都能正常展示。写文章时拿不准「这语法支持吗」，先来这页搜一眼。

参考资料

这是一条脚注内容，用于展示脚注渲染效果。 ↩
Pro Git — Git 官方权威书籍，覆盖从入门到内部原理，中文版可在线免费阅读。 ↩

Markdown 渲染效果展示

#文本样式

#标题与目录

三级标题

四级标题

五级标题

六级标题

#列表

#引用与告警

#表格

#代码

带标题与行高亮的代码块

代码块行级折叠

#Tabs 标签页

#折叠面板

HTML 折叠

折叠里的嵌套

#数学公式

#Mermaid 图表

#图片与图库

#视频嵌入

#链接与卡片

行内外链

链接卡片

脚注

#语法速查

参考资料

隐私设置