Markdown 渲染效果展示

这页把站点的正文渲染能力逐项排开：先看效果，再抄写法。指令的形态约定、降级行为与写法陷阱以 README「Markdown 扩展」为唯一出处，这里只放效果和最小写法。

NOTE

数学公式、Mermaid、图库与灯箱由站点统一启用，不用逐篇开关，浅深两档渲染一致。

#行内样式

标准行内标记

效果	写法
粗体	`粗体`
斜体	`斜体`
粗斜体	`*粗斜体*`
~~删除线~~	`~~删除线~~`
`行内代码`	`行内代码`
原生高亮	`<mark>高亮</mark>`
`Ctrl` + `K`	`<kbd>Ctrl</kbd> + <kbd>K</kbd>`
H₂O 与 a²	`H<sub>2</sub>O`、`a<sup>2</sup>`
😀🚀	Emoji 直接写原生字符

行内高亮 `:mark`

色名	压行底一笔（默认档）	胶囊（`{style="block"}`）
默认	品牌绿	品牌绿
`yellow`	黄	黄
`blue`	蓝	蓝
`purple`	紫	紫
`orange`	橙	橙
`red`	红	红

行内下划线 `:ul`

写法	效果
`:ul[文字]`	细实线
`:ul[文字]{style="dashed"}`	虚线
`:ul[文字]{style="dotted"}`	点线
`:ul[文字]{style="double"}`	双实线
`:ul[文字]{style="wavy"}`	波浪线

剧透隐藏 `:spoiler`

把鼠标悬停在这句话上——被隐藏的内容就出现了。换模糊皮肤：遮盖物从绿条换成模糊。

气泡注解 `:tip`

把鼠标停在 Twikoo 上会浮出说明，键盘聚焦同样触发，触屏点按不弹。

行内复制 `:copy`

效果	写法
`pnpm check`	`pnpm check`
`pnpm check && pnpm build`	`:copy[pnpm check && pnpm build]`

整行命令条 `::copy`

ffmpeg -i cover.avif -c:v libwebp -quality 90 cover.webp

pnpm exec astro build --force

CF_DEPLOY_HOOK_URL

写法	左侧提示格
`::copy[命令]`	默认一个 `$`
`::copy[命令]{title="bash$"}`	换成给的文案
`::copy[命令]{title=""}`	整格去掉

混排与嵌套

样式之间可以套：高亮里的粗体、粗体里的斜体与代码、指令套粗体、下划线套斜体。自定义指令和标准标记混排在同一句里照常渲染。

#引用与告警

引用块

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

1
> 这是一个普通的引用块。
2
>
3
> 空行分段，行内格式照常可用。

五种告警框

按语义选用：补充信息用 NOTE，操作建议用 TIP，关键依赖用 IMPORTANT，风险提示用 WARNING，危险操作用 CAUTION。

NOTE

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

TIP

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

IMPORTANT

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

WARNING

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

CAUTION

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

1
> [!NOTE]
2
> 标题写成 `> [!型别]`，内容逐行加 `> `。

可折叠的告警框

标题后跟 + 默认展开，跟 - 默认收起，点击标题切换。

NOTE

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

TIP

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

1
> [!NOTE]+
2
> 默认展开。
3

4
> [!TIP]-
5
> 默认收起。

#块级内容

标题层级与目录

正文从 ## 开始，# 让给文章标题。你正在看的这页就是演示：## 是分组，### 是能力小节。

层级	进目录	说明
`#`	否	让给文章标题
`##`–`###`	是	本页的分组与能力小节
`####`	是	需要再分层时用
`#####`–`######`	否	目录只取二到四级

每个标题自动生成锚点，悬停可见锚链；toc: false 整篇关掉目录。

列表

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

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

已完成的任务
待完成的任务

1
- 第一项
2
- 第二项
3
  - 嵌套子项 A
4
1. 第一步
5
2. 第二步
6
   1. 子步骤 2.1
7
- [x] 已完成
8
- [ ] 待完成

表格

冒号写在分隔行的左侧、两侧、右侧，分别左对齐、居中、右对齐；列数多时表格自动横向滚动，不撑破版面。行内样式写在单元格里照常生效：

特性	支持情况	说明
对齐	✅	冒号位置决定对齐方式
行内样式	✅	粗体、`代码`、链接、下划线、高亮都可用

分割线

独占一行的 --- 渲染成分割线，前后留一个空行最稳：

折叠面板 `:::folding`

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

折叠面板适合放次要内容：

详细配置示例
不希望出现在首屏的长内容

默认展开的折叠面板

这个面板带 open，默认是展开状态。

1
:::folding{title="点击展开 — 查看详细配置说明"}
2
折叠内容支持列表、代码块、表格等全部块级语法。
3
:::
4

5
:::folding{title="默认展开" open}
6
带 `open` 属性默认展开。
7
:::

标签页 `::::tabs`

并列内容——多语言示例、多方案对照——用 ::::tabs 包多个 :::tab{title="..."}。这组没加 notoc，右侧目录里会出现 TypeScript、Python 两个条目，点目录项会先激活对应标签页再滚动过去：

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

8
const published = posts.filter(p => !p.data.draft);

1
from dataclasses import dataclass
2

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

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
::::

不想要目录条目时给 ::::tabs 加 {notoc}。

折叠里的嵌套

折叠面板可以嵌任何块级内容。视频和音频是例外：折叠里要用无闭合围栏的叶子形态 ::video / ::audio。

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

TIP

折叠里的告警正常渲染。

折叠里的列表项
第二项

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

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

6
- 折叠里的列表项
7

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

#代码

代码块由 Expressive Code 渲染，行号默认打开。

代码块标题与行高亮

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
```ts title="src/config/site.ts" {3, 6-8}
2
type ColorMode = 'light' | 'dark' | 'auto';
3
```

区间用逗号分隔，6-8 是范围；不写 title 时标题栏也可以从代码内容里推断文件名。

代码块行级折叠

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
```

collapseStyle 还可选 collapsible-start / collapsible-end，决定摘要向哪个方向展开。

#公式与图表

行内公式

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

块级公式

块级用 $$...$$，两个 $$ 必须各占一行：

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

多行对齐：

\begin{aligned} a &= b \\ c &= d \end{aligned}

1
行内公式 $E = mc^2$。
2

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

7
$$
8
\begin{aligned}
9
a &= b \\
10
c &= d
11
\end{aligned}
12
$$

Mermaid 图表

```mermaid 围栏画图，构建期渲染成静态 SVG，浅深两套主题，支持拖拽平移、缩放与全屏：

1
```mermaid
2
flowchart TD
3
  A[开始] --> B{条件判断}
4
  B -->|是| C[执行操作]
5
```

#富媒体

正文图片与图库

引号里写图注（也是悬停提示）；写成 "width=420" 改成逐图限宽；连续多行图片（中间不空行）自动组成图库，点任意一张开灯箱：

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

3
![限宽示例](图片地址 "width=420")
4

5
![第一张](图片地址)
6
![第二张](图片地址)
7
![第三张](图片地址)

视频嵌入 `:::video`

`type`	`id` 写什么	默认宽高比	说明
`bilibili`	`BV...`	`16 / 9`	外链播放器
`bilibili-nano`	`BV...`	`16 / 9`	精简播放器
`youtube`	视频 ID	`16 / 9`	国内可达性差
`douyin`	数字 ID	`27 / 56`	竖屏，内部视口锁 322px
`douyin-wide`	数字 ID	`1198 / 731`	横屏档
`tiktok`	视频 ID	`27 / 56`	竖屏
`raw`	视频直链	`16 / 9`	站内相对路径自动补 base

Bilibili

抖音竖屏

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

ratio="4 / 3" 改宽高比，width="320" 逐条收窄；折叠里改用叶子形态 ::video{...}。

音频嵌入 `:::audio`

`type`	`id` 写什么	渲染成
`raw`	站内路径，如 `/audio/demo-tone.mp3`	浏览器原生 `<audio controls>`
`netease`	歌曲 ID，如 `31066544`	网易云外链播放器 iframe

站内文件

带说明的站内文件

440Hz 标准音

网易云音乐

网易云音乐

1
:::audio{type="raw" id="/audio/demo-tone.mp3"}
2
:::
3

4
:::audio{type="raw" id="/audio/demo-tone.mp3" title="440Hz 标准音"}
5
:::
6

7
:::audio{type="netease" id="31066544"}
8
:::

聊天记录 `:::chat`

块内每个空行分隔的段落都是一条消息，{…} 只有独占一整段时才是说话人控制行：

控制行	作用
`{名}`	名字靠左，随后的消息进对方气泡
`{.名}`	名字靠右，随后的消息进自己气泡
`{.}`	只切到自己一侧，不显示名字
`{:文本}`	输出一条居中的系统行，不改变左右归属

小明: 这个聊天气泡是要装个组件吗？
我: 不用，构建期就转成了 dl，样式全在 CSS 里，浏览器不额外跑脚本。
昨天 21:40
小明: 那我中间插一行时间，右边会不会串到左边去？
我: 不会，左右是逐条标出来的，跟上一条是谁没关系。

1
:::chat
2
{小明}
3

4
这个聊天气泡是要装个组件吗？
5

6
{.我}
7

8
不用，构建期就转成了 `dl`。
9

10
{:昨天 21:40}
11

12
{小明}
13

14
那我中间插一行时间，右边会不会串到左边去？
15

16
{.我}
17

18
不会，左右是逐条标出来的。
19
:::

#链接与卡片

行内链接与域名图标

外部链接 — Astro 官网、GitHub、微软文档按域名自动带上站点图标，站外链接在新标签页打开，悬浮时气泡给出主机名。站内链接（比如 Git 从诞生到设计理念）不弹气泡。外链整条被包进 :tip 时，域名让位给作者那句注解——Astro 官网。

链接卡片 `:::linkcard`

Astro 官网

https://astro.build

Git 从诞生到设计理念

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

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

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

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

url 是外链卡，post 写文章 id——标题、简介、封面都由目标文章的 frontmatter 自动填充，post 优先于 url。

GitHub 仓库卡片 `:::github`

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

Kotlin1.0kApache-2.0

1
:::github{repo="XingHeYuZhuan/shiguangschedule"}
2
:::

脚注

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

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

3
[^1]: 定义写在文中任意位置。
4
[^progit]: [Pro Git](https://git-scm.com/book/zh/v2) — 中文版可在线免费阅读。

#语法速查

需求	写法
粗体 / 斜体 / 删除线	`粗体` / `斜体` / `~~删除线~~`
高亮 / 键盘按键	`<mark>高亮</mark>` / `<kbd>Ctrl</kbd>`
上下角标	`x<sup>2</sup>` / `H<sub>2</sub>O`
行内剧透	`:spoiler[文字]`，加 `{blur}` 换成模糊遮盖
气泡注解	`:tip[词]{tip="注解"}`，注解文字必须非空且用双引号包住
行内下划线	`:ul[文字]`，`{style="wavy"}` 换波浪线（另有 `dashed` / `dotted` / `double`）
行内高亮	`:mark[文字]` 品牌绿荧光笔（默认压行底一笔），`{color="yellow"}` 换色、`{style="block"}` 换整块胶囊
行内复制	`:copy[要复制的命令]`（长得和普通行内代码一样，只是尾部多一个按钮）
整行命令条	`::copy[命令]`（独占一行），`{title="bash$"}` 换提示格、`{title=""}` 去掉
引用块	`> 引用`，空行分段
告警	`> [!NOTE]`，`+` / `-` 控制默认展开收起
折叠面板	`:::folding{title="标题"}`，可加 `open`
标签页	`::::tabs` + `:::tab{title="..."}`，可加 `notoc`
代码块增强	围栏 meta：`title="文件名"`、`{1,3-4}` 高亮、`collapse={5-8}` 行折叠
行内 / 块级公式	$E=mc^2$ / `$$` 各占一行
Mermaid 图表	```mermaid 围栏代码块
图片图注与限宽	`![说明](地址 "图注")` / `![说明](地址 "width=640")`
图片图库	连续多行 `![说明](地址)` 自动成组
视频	`:::video{type="bilibili" id="BV..."}`，折叠内用 `::video`
音频	`:::audio{type="raw" id="/audio/a.mp3"}` / `{type="netease" id="歌曲ID"}`
聊天记录	`:::chat` 包一段对话，块内 `{名}` 对方、`{.名}` 自己、`{:文本}` 系统行
链接卡片	`:::linkcard{url="..." title="..."}` / `{post="文章id"}`
GitHub 卡片	`:::github{repo="owner/仓库"}`
脚注	`[^1]` 引用 + 文中任意位置 `[^1]: 定义`
分割线	独占一行的 `---`

写法细节、降级行为与完整的写法陷阱表都在 README「Markdown 扩展」一节。

参考资料

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