Markdown 渲染效果展示

这页把站点的正文渲染能力逐项排开：先看效果，再抄写法。

#行内样式

标准行内标记

行内高亮 :mark

行内下划线 :ul

剧透隐藏 :spoiler

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

气泡注解 :tip

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

行内复制 :copy

整行命令条 ::copy

混排与嵌套

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

#引用与告警

引用块

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

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

五种告警框

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

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

可折叠的告警框

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

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

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

#块级内容

标题层级与目录

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

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

列表

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

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

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

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

表格

冒号写在分隔行的左侧、两侧、右侧，分别左对齐、居中、右对齐；列数多时表格自动横向滚动，不撑破版面，单元格里的粗体、代码、链接与行内指令照常生效。

三线表与表格编号 ::table

表格默认是带外框的面板卡。在表格紧邻处写一行 ::table{style="three-line"}，就退成学术风格的三线表：只留顶线、栏目线、底线，竖线、格线和表头底色全部去掉，数字列自动等宽对齐：

1
::table{style="three-line"}
2

3
| 元素 | 符号 | 标准原子量 |
4
|:-----|:----:|-----------:|
5
| 氢 | H | 1.008 |
6
| 碳 | C | 12.011 |
7
| 氧 | O | 15.999 |

标记独占一行，写在表格的上面或下面都行，折叠与标签页里照常可用。再加一个 title，表格升级为带号的表：题注落在表格上方，号按节自动编；key 给它起个名字，正文里用 :tab[名字] 回指，中途增删表格也不用回头改：

1
::table{style="three-line" title="前三周期元素的标准原子量与电负性" key="elements"}
2

3
| 序 | 元素 | 符号 | 标准原子量 | 电负性 |
4
|:--:|:-----|:----:|-----------:|-------:|
5
| 1 | 氢 | H | 1.008 | 2.20 |
6
| 2 | 氦 | He | 4.0026 | — |
7

8
如 :tab[elements] 所示，电负性随原子序数周期性变化。

上面这张表就是 表 3.1，号是构建时填好的真实文字，能选中、能复制。不带 title 的表格整张铺开，不编号也不能回指。

多层表头

Markdown 表格只有一行表头。论文里那种多层表头、分组短线、合计行，要改用手写 HTML 表格：外层套 <div class="table-scroll" data-table-style="three-line">，就吃到同一个三线表档位，colspan、rowspan、align 照常写；组间的占位列和合计行的线怎么画，看下面折叠里的源码：

表 3.2 正文令牌浅深两档的 oklch 分解（令牌名省略 --color- 前缀）

1
<p style="text-align:center;margin:1.5rem 0 .4rem"><strong>表 3.2 标题</strong></p>
2
<div class="table-scroll" data-table-style="three-line" style="margin-top:0">
3
<table>
4
<thead>
5
<tr><th rowspan="3">令牌</th><th colspan="2">亮度 L</th><th style="width:1.4rem;padding:0;border-bottom:0"></th><th colspan="2">色度 C</th>…</tr>
6
<tr><th align="center">浅色</th><th align="center">深色</th><th style="width:1.4rem;padding:0;border-bottom:0"></th>…</tr>
7
<tr><th align="center">(1)</th><th align="center">(2)</th>…</tr>
8
</thead>
9
<tbody>
10
<tr><td><code>foreground</code></td><td align="center">0.20</td><td align="center">0.92</td><td style="width:1.4rem;padding:0;border:0"></td>…</tr>
11
<tr><td>均值</td><td align="center" style="border-top:1px solid var(--color-foreground)">0.651</td>…</tr>
12
</tbody>
13
</table>
14
</div>

两处要留意：单元格里的公式不会被 KaTeX 处理，下标改用 <sub>；线色写 var(--color-foreground) 而不是 #000，深色模式才不会翻车。

分割线

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

折叠面板 :::folding

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。

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$。

块级公式

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

多行对齐：

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

单位与常量宏

几个高频记号已经注册好，行内和块级公式里直接写：

燃烧焓 $\Delta H_\mathrm{c} = -68.5\ \kcal\,mol^{-1}$，速率式 $\frac{\dd c}{\dd t} = -kc$。

1
燃烧焓 $\Delta H_\mathrm{c} = -68.5\ \kcal\,mol^{-1}$，速率式 $\frac{\dd c}{\dd t} = -kc$。

公式编号与回指 :eq

块级公式自动编「(节.序)」，号落在公式右侧，是真实文字，能选中、能复制。

起个名字更好引用：\label{标签} 写在公式里，正文用 :eq[标签] 回指，显示的号由构建期填好，中途增删公式也不用回头改。

把 (5.3) 两边取对数，就能从等温速率数据线性回归出活化能 $E_a$。

配分函数 (5.4) 归一化之后，(5.3) 里的指前因子 $A$ 才有统计意义。

号也可以手写：\tag{...} 换掉这一条的号，\notag 让它彻底不编号，两者都不占自动编号的计数。

1
$$
2
k = A e^{-\frac{E_a}{RT}} \label{arrhenius}
3
$$
4

5
活化能见 :eq[arrhenius]。
6

7
$$
8
\Delta G = \Delta H - T\Delta S \tag{6-1}
9
$$
10

11
$$
12
c = \lambda \nu \notag
13
$$

懒得起名也可以直接抄号：:eq[5.1] 与 :eq[(5.1)] 都认。

化学式与反应方程 \ce

化学式写在 \ce{} 里，箭头、电荷、相态都认：甲烷完全燃烧 $\ce{CH4 + 2O2 -> CO2 + 2H2O}$，铁离子 $\ce{Fe^3+}$；条件写在箭头上，中文要包进 \text{}——$\ce{2H2(g) + O2(g) ->[\text{点燃}] 2H2O(l)}$。

行内公式不折行，式子一长会把窄屏顶出横向滚动条，长反应方程换成块级：

单位换算写 \pu：$\pu{4.3 s-1}$。正文句子里裸写的 $ 要转义成 \$，否则会和公式定界符配对吞句。

1
$\ce{CH4 + 2O2 -> CO2 + 2H2O}$ 写在句子里，长式改块级：
2

3
$$
4
\ce{CH3COOH + C2H5OH <=> CH3COOC2H5 + H2O}
5
$$
6

7
一级速率常数 $\pu{4.3 s-1}$。

Mermaid 图表

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

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

#富媒体

正文图片与图库

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

带图注的图自动编号「图 节.序」；::figure{key="…"} 紧贴在图前起个名字，正文就能用 :fig[名字] 回指——这张图就是 图 6.1。

上面的图库不带键、不编号；多图段落紧贴 ::figure{key="…" title="总题注"} 时升级成编号面板，每格左下角自动配 a/b/c 角标，组图 图 6.3 的 图 6.3(b) 就是森林那格。

a

b

c

1
::figure{key="quiet"}
2

3
![说明文字](图片地址 "图注")
4

5
如 :fig[quiet] 所示，……
6

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

9
![第一张](图片地址)
10
![第二张](图片地址)
11
![第三张](图片地址)
12

13
::figure{key="panels" title="总题注"}
14

15
![面板 a 的说明](图片地址)
16
![面板 b 的说明](图片地址)
17

18
回指组图 :fig[panels]，指到单格用 :fig[panels-b]，显示「图 N(b)」。

视频嵌入 :::video

Bilibili

抖音竖屏

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

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

分子结构嵌入 :::structure

实验结构

预测模型

结构式

阿司匹林结构式

SMILES 直写

咖啡因结构式

1
:::structure{id="4HHB"}
2
:::
3

4
:::structure{type="alphafold" id="P04637" title="p53 人源预测模型"}
5
:::
6

7
:::structure{type="pubchem" id="2244" title="阿司匹林结构式"}
8
:::
9

10
:::structure{type="smiles" id="CN1C=NC2=C1C(=O)N(C)C(=O)N2C" title="咖啡因结构式"}
11
:::

ratio / width 与视频一致，折叠里用叶子形态 ::structure{...}；id 写错时整块不渲染，加载失败就点结构下方的标题，跳到对应库的原页面。结构式图片底色恒白，深色模式下是一块浅色底板。

音频嵌入 :::audio

站内文件

带说明的站内文件

网易云音乐

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 官网。

数据库 ID 直链 :db

文献和数据的编号写成 :db[ID]{type="库"}，构建期拼成落地页链接，不用手抄一长串 URL。

血红蛋白的结构 4HHB、β 亚基 P69905、Perutz 的协同性综述 9646860；阿司匹林 2244，糖酵解通路 hsa00010。

1
结构 :db[4HHB]{type="pdb"}，蛋白 :db[P69905]{type="uniprot"}。
2
文献 :db[10.1186/gb-2004-5-2-r12]{type="doi"}，全文 :db[PMC395750]{type="pmcid"}。
3
化合物 :db[2244]{type="pubchem"}，通路 :db[hsa00010]{type="kegg"}。

[...] 里的 ID 就是显示出来的文字，链接地址由 type 决定；形状写错（比如 PDB 号不足四位）会退回纯文本，页面上不会留死链。

链接卡片 :::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) — 中文版可在线免费阅读。

#语法速查