本站 Markdown 语法规范

本文是站点 markdown 渲染长期 fixture + 语法参考:每节展示一种语法的 .md 源码与渲染效果。新增任何语法支持都会在此追加章节,作者写文章前查一眼即可。

1. 标题层级

源码:

# 一级章节（源码 H1，渲染为 H2，自动编号 "1 "）

## 二级小节（源码 H2，渲染为 H3，自动编号 "1.1 "）

### 不编号的子标题（渲染为 H4）

#### 更深一档（渲染为 H5）

效果:本节标题"标题层级"就是源码 # 渲染出来的 H2,带"1 "前缀;下一段紧跟的"## 段落与内联强调"是 H3,带"1.1 "前缀。

1.1 段落与内联强调

源码:

普通段落。**粗体**、_斜体_、~~删除线~~、`inline code` 都能正常解析。

效果:

普通段落。粗体、斜体、~~删除线~~、inline code 都能正常解析。

1.2 链接

源码:

内联外链:[Vue 3 官网](https://vuejs.org)
内联内链:[博客列表](/blogs)
自动链接(GFM):<https://github.com>

效果:

内联外链:Vue 3 官网

内联内链:博客列表

自动链接:https://github.com

外链会被 rehype-external-link 插件自动加 target="_blank" + rel="noopener noreferrer",内链保持站内跳转。

2. 列表

2.1 无序列表

四档 marker:圆形 filled (L1) / 圆圈 outline (L2) / 方块 filled (L3) / 方框 outline (L4),filled-outline 配对,颜色继承正文主色。

源码:

- 第一层(圆形)
  - 第二层(圆圈)
    - 第三层(方块)
      - 第四层(方框)
- 平级项

效果:

第一层(圆形)
- 第二层(圆圈)
  - 第三层(方块)
    - 第四层(方框)
平级项

2.2 有序列表

CSS counters 自绘多级嵌套编号 1. / 1.1. / 1.1.1.,跟 heading 编号风格统一,inline marker 不占 padding。

源码:

1. 步骤一
2. 步骤二
   1. 嵌套(显示 2.1.)
   2. 嵌套(显示 2.2.)
      1. 深嵌套(显示 2.2.1.)
      2. 深嵌套(显示 2.2.2.)
3. 步骤三

效果:

步骤一
步骤二
1. 嵌套(显示 2.1.)
2. 嵌套(显示 2.2.)
  1. 深嵌套(显示 2.2.1.)
  2. 深嵌套(显示 2.2.2.)
步骤三

2.3 任务列表

GFM 扩展。checkbox 自绘:未勾选 = glass 底 + 细边,勾选 = primary 实底 + 白色 check 图标。

源码:

- [x] 已完成项
- [x] 另一个已完成项
- [ ] 未完成项
- [ ] 另一个未完成项

效果:

已完成项
另一个已完成项
未完成项
另一个未完成项

3. 表格

GFM pipe table。视觉:卡片化外框(border + radius)、表头深一档 surface、行 hover 浅染色。

3.1 默认表格

源码:

| 字段          | 类型     | 说明                            |
| ------------- | -------- | ------------------------------- |
| `slug`        | string   | URL 路径段,需在 `_index.json` 注册 |
| `title`       | string   | 文章主标题,渲染时不出现 H1     |
| `tags`        | string[] | 标签数组,建议 ≤4 个            |
| `published`   | boolean  | 是否上线,默认 false            |

效果:

字段	类型	说明
`slug`	string	URL 路径段,需在 `_index.json` 注册
`title`	string	文章主标题,渲染时不出现 H1
`tags`	string[]	标签数组,建议 ≤4 个
`published`	boolean	是否上线,默认 false

3.2 列对齐

源码:

| 左对齐 | 居中 | 右对齐 |
| :----- | :--: | -----: |
| a      |  b   |      c |
| 文本   | 较长 |   数字 |
| short  | mid  | 999.99 |

效果:

左对齐	居中	右对齐
a	b	c
文本	较长	数字
short	mid	999.99

4. 引用 Blockquote

视觉:左侧 3px primary 色条 + glass 底 + 斜体次级文字,与 Callout 的"实色边 + 强语义"刻意区分——blockquote 表达"引述",callout 表达"提示语义"。

源码:

> 单行引用:站点博客与系列教程走同一条 unified 管线。
>
> 多段落引用:
>
> 第一段。
>
> 第二段。
>
> > 嵌套引用:第二层视觉自然递增。

效果:

单行引用:站点博客与系列教程走同一条 unified 管线。

多段落引用:

第一段。

第二段。

嵌套引用:第二层视觉自然递增。

5. 代码

5.1 行内代码

源码:

配置文件 `vite.config.ts` 在仓库根目录。

效果:

配置文件 vite.config.ts 在仓库根目录。

5.2 代码块(无文件名)

Shiki 双主题:github-light / github-dark,跟随站点主题切换。无 filename 时复制按钮浮动在右上角,hover 时显形。

源码:

```ts
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [],
})
```

效果:

import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [],
})

5.3 代码块(带标题)

推荐用 title="...",顶部出现标题栏(title + lang badge + copy)。filename="..." 同义。

源码:

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
})
```

效果:

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
})

向后兼容:历史写法 ```ts vite.config.ts 把第二段裸 xxx.ext 当 title,继续可用。

5.4 行号

meta 加 lineNumbers(showLineNumbers 同义)开启。

```ts lineNumbers
const a = 1
const b = 2
const c = a + b
```

const a = 1
const b = 2
const c = a + b

5.5 行高亮

meta 里写 {n} / {n-m} / 组合 —— Shiki transformerMetaHighlight 自动给对应行打 .highlighted。

```ts lineNumbers {2,4-5}
const total = (xs: number[]) => {
  let acc = 0
  for (const x of xs) {
    acc += x
  }
  return acc
}
```

const total = (xs: number[]) => {
  let acc = 0
  for (const x of xs) {
    acc += x
  }
  return acc
}

5.6 Notation transformers

行尾注释 // [!code xxx] 形式,Shiki 在编译期擦掉标记并打类。

5.6.1 Highlight

```ts
const a = 1
const b = 2
const c = a + b
```

const a = 1
const b = 2
const c = a + b

// [!code highlight:N] 高亮接下来 N 行:

const a = 1
const b = 2
const c = 3
const d = 4

5.6.2 Diff

```ts
function greet(name: string) {
  console.log('hi ' + name) 
  console.log(`hi ${name}`) 
}
```

function greet(name: string) {
  console.log('hi ' + name) 
  console.log(`hi ${name}`) 
}

5.6.3 Error / Warning

const danger = JSON.parse(input) 
const risky = eval('1+1')

5.6.4 Focus

非聚焦行被淡化 + 模糊;hover 整块恢复。

function calc() {
  const a = 1
  const b = 2
  return a + b
}

5.7 软换行

meta 加 wrapCode(wrap 同义),长行不再横向滚动而是回行。

const veryLongVariableName = 'this is a deliberately long string that would otherwise force a horizontal scrollbar to appear inside the code block'

5.8 多语言切换

:::[code-group] 围栏内若干 fence,每个 fence 的 title 自动成为 tab 标签。


:::[code-group]

```bash title="npm"
npm install
```

```bash title="pnpm"
pnpm install
```

```bash title="yarn"
yarn
```

:::

效果:

npm

bash

npm install

pnpm

bash

pnpm install

yarn

bash

yarn

5.9 多语言示范

白名单分组:前端 / 后端 / 运维 / 配置 / 通用。编辑入口在 src/content/code/shiki-config.ts。

bash

pnpm dev
pnpm build

css

.markdown {
  color: var(--text-primary);
  font-size: var(--font-size-body);
}

python

def hello(name: str) -> str:
    return f"hello, {name}"

package main

import "fmt"

func main() {
    fmt.Println("hello")
}

json

{
  "blogs": ["site-markdown-syntax"]
}

yaml

server:
  port: 8080
  host: 0.0.0.0

dockerfile

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]

sql

SELECT slug, title FROM blogs WHERE published = true ORDER BY published_at DESC;

diff

- const old = 'magic value'
+ const next = var(--token)

6. 终端 / 命令行

用 ```cmd 围栏写终端会话,渲染复用首页「关于我」的终端组件(mac 窗口 + 同款配色),整站观感统一。以提示符开头的行是命令(输入),其后到下一条命令之间的行都是输出,二者样式自动区分。

提示符默认 $,用 meta prompt="…" 改(支持 ❯ / > / PS> 等);
meta title="…" 给窗口标题栏加文字;
默认自适应铺满正文宽度;要约束就传 meta width="…"(任意 CSS 长度,如 width="32rem",会限宽并水平居中);
输出若是一段合法 JSON 对象,自动按 JSON 着色(和首页 cat profile.json 一致);
文章里是静态展示,不打字、无 Last login 时间戳,无需任何时间配置。
别名:```terminal 与 ```cmd 等价。

源码:

```cmd prompt="❯" title="albert@dev: ~"
❯ whoami
albert
❯ uname -s
Darwin
❯ cat profile.json
{ "name": "Albert", "role": "Frontend", "years": 6 }
```

效果:

albert@dev: ~

7. Callout(5 档语义提示)

语法::::[<type> <可选标题>] / 正文 / :::。type 白名单:tip / info / warning / danger / success。内部支持完整 markdown(粗体、code、列表、链接等)。

源码:


:::[tip 小提示]

内容支持 markdown 内嵌:**粗体**、_斜体_、`inline code` 都能用。

:::

5 档效果:

8. 数学公式

KaTeX 编译期渲染:remark-math 把 TeX 源码解成 mdast math 节点,rehype-katex 在 hast 阶段直接产出  HTML,运行时零开销;字体走 katex/dist/katex.min.css 全局引入,按需懒加载 woff2。

8.1 行内公式

源码:

质能方程 $E = mc^2$ 是相对论核心结论;欧拉等式 $e^{i\pi} + 1 = 0$ 串联五大常数。

效果:

质能方程 $E = m c^{2}$ 是相对论核心结论;欧拉等式 $e^{iπ} + 1 = 0$ 串联五大常数。

8.2 块状公式

源码($$ 单独成块,独占段落):

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

效果:

i = 1 \sum n i = \frac{n ( n + 1 )}{2}

更复杂一点的多行对齐(使用 aligned 环境):

f (x) a_{n} b_{n} = a_{0} + n = 1 \sum \infty (a_{n} cos \frac{nπ x}{L} + b_{n} sin \frac{nπ x}{L}) = \frac{1}{L} \int_{- L}^{L} f (x) cos \frac{nπ x}{L} d x = \frac{1}{L} \int_{- L}^{L} f (x) sin \frac{nπ x}{L} d x

矩阵也支持:

A = 147258369

9. 图片

源码:

![占位图](https://placehold.co/600x300/png?text=Markdown+Image)

效果:

独占一段的图片会被 rehype-figure 包成 <figure>:alt(或 title)自动成为居中题注,图片可点击放大(lightbox 预览,Esc / 点遮罩关闭),并默认 loading="lazy"。上图的题注就是 alt「占位图」。行内夹在文字里的图保持原样 <img>。

9.1 自定义宽高

在 alt 文本尾部追加 =<宽>x<高> 指令即可控制图片尺寸,指令会自动从 alt 里剥离,不会污染题注:

写法	效果
`![图 =600x300](url)`	宽 600px、高 300px
`![图 =600x](url)` 或 `![图 =600](url)`	宽 600px,高按比例自适应
`![图 =x300](url)`	高 300px,宽按比例自适应
`![图 =50%x](url)`	宽为容器的 50%

纯数字默认单位 px,也可显式写 px / %。尺寸落到 img 的 inline style 上,块级图与行内图都生效;受 .markdown img { max-width: 100% } 约束,设定的宽度在窄屏下仍会自动收缩,不会溢出。

源码:

![占位图 =320x](https://placehold.co/600x300/png?text=320px+wide)

效果(题注仍是干净的「占位图」,宽度被限制成 320px):

10. 分隔线

单独一行写 ---(或 *** / ___)渲染为一条细分割线 <hr>。

源码:

上一段。

---

下一段。

效果:

上一段。

下一段。

11. 标题锚点

H1 ~ H6(经 demote 后即 H2 ~ H6)由 rehype-slug 自动注入 id,再由 rehype-autolink-headings 包成 <a class="heading-anchor">——hover 标题时左侧浮出 # 字符提示"可点",点击即跳转该锚点。本文每个标题都有锚点,刷新 URL 带上 #xxx 即可定位。

12. 行内高亮

==文字== 渲染成 ,首尾空格自动忽略(== 文字 == 与 ==文字== 等价)。行内代码里的 == 不受影响。

源码:

这是一段含有 ==重点高亮== 的文字,而 `a == b` 在行内代码里原样保留。

效果:

这是一段含有重点高亮的文字,而 a == b 在行内代码里原样保留。

13. 键位 kbd

++按键++ 渲染成 <kbd>,适合写快捷键。要求 ++ 紧贴内容(C++、++i 这类孤立写法不会被误识别),组合键里的内部 + 原样保留。

源码:

保存用 ++Ctrl+S++,命令面板 ++Cmd+K++;退出按 ++Esc++。

效果:

保存用 Ctrl+S,命令面板 Cmd+K;退出按 Esc。

14. 角标 Badge

{{文字 <变体>}} 把一段文字包起来,在其右上角加一个语义色小圆点(类似表单「必填」标记),鼠标悬停时文字显示同色下划线。文字本身保持正文色,只有圆点 / 下划线带语义色 —— 用来在句子里轻量标注某个词,而不是做成彩色标签(那是卡片上的 tag)。

变体写在末尾:primary / info / success / warning / error / tip / default,决定圆点和下划线颜色。变体是必填关键字,同时是防误伤护栏:末尾不是白名单变体的 {{ ... }}(如正文里的 {{ "k": "v" }})不会被当成角标。
末尾变体后可加 .pulse,让圆点「呼吸 + 水波脉冲」(进行中 / 需关注);prefers-reduced-motion 下自动停动画。
被包的文字可以含空格。

源码:

项目产物:需求文件、{{概要设计文件 success}}、{{详细设计文件 warning.pulse}}、{{接口文档 error}},其余待补。

效果:

项目产物:需求文件、概要设计文件、详细设计文件、接口文档,其余待补。

15. 上标 / 下标

^文字^ 渲染成 (上标),~文字~ 渲染成 (下标),适合写公式、单位、化学式。要求 ^ / ~ 紧贴内容(a ^ b、a ~ b 这类带空格的不会被误识别),行内代码里的 ^ / ~ 原样保留。

~ 与删除线共用符号,但二者不冲突:单 ~ 是下标,双 ~~ 仍是删除线(~~删除线~~)。

源码:

水分子 H~2~O,二氧化碳 CO~2~;质能方程 E = mc^2^,面积 r^2^ π。删除线 ~~旧公式~~ 照常。

效果:

水分子 H₂O,二氧化碳 CO₂;质能方程 E = mc²,面积 r² π。删除线 ~~旧公式~~ 照常。

16. 内容标签页 Tabs

:::[tabs] 围栏内用独占一行的 @tab 标签 切分面板,适合分平台 / 分方案的并列内容(代码分组请用上面的 :::[code-group])。

源码:


:::[tabs]

@tab macOS

用 Homebrew 安装:`brew install xxx`。

@tab Windows

用 winget 安装:`winget install xxx`。

@tab Linux

用包管理器,如 `apt install xxx`。

:::

效果:

用 Homebrew 安装:brew install xxx。

用 winget 安装:winget install xxx。

用包管理器,如 apt install xxx。

17. 折叠块 Details

:::[details 标题] 渲染成原生 <details> 折叠块,默认收起,点标题展开。标题可省略(默认「详情」)。适合藏长附录、答案、可选阅读。

源码:


:::[details 点击查看完整推导]

这里是默认折叠的内容,支持 **markdown**、`code`、列表等。

- 第一步
- 第二步

:::

效果:

点击查看完整推导

这里是默认折叠的内容,支持 markdown、code、列表等。

第一步
第二步

18. 步骤条 Steps

:::[steps] 围栏内写普通有序列表,会被改造成带序号圆点 + 连接线的竖向步骤条,适合教程的操作流程。

源码:


:::[steps]

1. 准备环境:安装 Node 与 pnpm。
2. 拉取代码并 `pnpm install`。
3. 运行 `pnpm dev`,打开 localhost 预览。

:::

效果:

准备环境:安装 Node 与 pnpm。
拉取代码并 pnpm install。
运行 pnpm dev,打开 localhost 预览。

19. 题目

考题专用容器 :::[questions(<模式>) <标题>],模式为 single(单选)或 multiple(多选)。固定四个字段:题目: / 选项:(下接 A. B. C. D.)/ 答案:(单选一个字母,多选连写如 ABD)/ 解析:。题干、选项、解析里都能用行内 code、 $math$ 、粗体。

交互:单选点选项即判定;多选勾选后点「提交答案」。判定后高亮正确 / 错误项并展开解析,可「重做」。

源码:


:::[questions(single) 题 1]

题目: 计算机硬件五大部件中,负责算术运算和逻辑运算的是:
选项:
A. 控制器
B. 运算器
C. 存储器
D. 输入设备
答案:B
解析: 运算器负责数据加工(算术 + 逻辑),核心是 ALU。

:::

效果:

20. 脚注

remark-gfm 脚注:正文用 [^id] 引用,文末用 [^id]: 内容 定义,自动汇总到底部并带跳转 / 回跳锚点。

源码:

这是一句需要补充说明的话[^note]。

[^note]: 这里是脚注内容,会渲染在文章末尾。

效果:

这是一句需要补充说明的话¹。

21. 不支持 / 未启用

以下语法目前没有渲染,写了也不会出效果(留作后续按需开):

Mermaid 图表(流程图走 SVG 图片方案,见上方「图片」)
HTML 标签直写(原生 <div> /  / <kbd> 等)——管线未挂 rehype-raw,raw HTML 会被忽略。常用的请改用专门语法:上标 ^x^、下标 ~x~、键位 ++按键++、高亮 ==文字==

这里是脚注内容,会渲染在文章末尾。 ↩