语法高亮

语法高亮让代码一眼就能读出结构：字符串是绿的、注释是灰的、关键字是蓝的。但要先澄清一个误解——语法高亮不是 Markdown 语法的一部分。规范只规定「围栏后面可以跟一段信息字符串」，这段信息怎么变成颜色，是渲染器的自由。同一份源码在 GitHub 和你的博客里高亮成不同样子，差别全在渲染器。这一页把「谁来决定颜色」讲透，再给出挑选语言标识的规则。

指定语言

在代码块反引号后写语言名：

```python
def hello():
    print("hi")
```

<pre><code class="language-python">def hello():
    print("hi")
</code></pre>

注意渲染结果里多出来的 class="language-python"。Markdown 解析器做的全部工作就是这一个：把信息字符串里的第一个词取出来，拼成 language- 前缀的类名贴到 code 上。真正把 def 和 print 涂成不同颜色的，是拿到类名后接手的高亮器——常见的有 Shiki、Prism 和 highlight.js。解析器不知道 Python 是什么，也不负责上色。

这也解释了「标识写对了却没高亮」：标识只写给渲染器看，写错或写成了高亮器不认的名字，类名照样生成，但没人按它上色。

常见语言标识

标识的取值是高亮器定义的，不是标准规定的，各家略有出入。下面这些最通用：

内容类型	常用标识
JavaScript / TypeScript	`js` / `ts`
Shell 脚本	`bash` 或 `sh`
Python	`python`
JSON / YAML	`json` / `yaml`
HTML / CSS	`html` / `css`
Markdown 本身	`markdown` 或 `md`
纯文本	`text` 或 `plaintext`

拿不准时，用 text 明确表示「这段不需要高亮」比留空更安全：留空时高亮器可能按默认语言猜测，猜错了就把普通文字染成奇怪的颜色。

常见扩展

多数渲染器和文档主题还会提供一批额外能力，但它们不属于 Markdown 语法，是否可用取决于站点配置：

行号：部分渲染器支持（如 GitHub 不显示行号，VitePress/Docs 主题可开启）。
高亮行：许多渲染器支持 {1,3-4} 语法（视站点配置）。
复制按钮：部分主题/插件提供。

还有一类是差异对比（diff）标记，用 + 和 - 开头表示新增和删除行，需要主题装了转换器才生效：

- pnpm install
+ pnpm install --frozen-lockfile

这些扩展靠的是信息字符串里的附加信息，而不是正文里的标记。所以同一份 Markdown 换到别的站点，行号没了、高亮行没了，都是正常现象。

提示

如果语言不识别，会按纯文本显示。
对特殊格式可用 text/plaintext 关闭高亮。

这两条说的是同一件事的两面：语言标识是给渲染器的建议，不是强制声明。标识写错或干脆不写，最坏只是少了点颜色；标识写成一个高亮器不认识的词，有的渲染器退回纯文本，有的直接报错中断构建。

常见坑

写法	实际结果	原因
```python	`language-python`	标识生效，等高亮器接手
```Python	`language-Python`	标识通常区分大小写
```js title="a.js"	仍是 `language-js`	只取第一个词当语言
留空不写标识	无类名	没写标识就没有语言

别把高亮当成内容的一部分。 高亮是渲染器的赠品，规范不保证它。读者可能在纯文本编辑器里打开，可能在邮件客户端里看，可能被复制进工单系统——这些地方只剩一行行等宽文字。代码必须靠代码块而非截图呈现，原因就在这里。

练习

把下面这段内容改写成 Markdown，要求：命令行部分和 JSON 部分各自用带正确语言标识的围栏代码块表示；目录输出那并不是代码，请用 text 标识明确关闭高亮。

先运行 pnpm install，然后执行下面这条命令：

pnpm build --filter @kuaiyizhi/kit-ui-astro

输出的目录结构如下：

dist/
  index.mjs
  index.d.ts

最后确认一下 package.json 里的 scripts 字段：

{
  "scripts": {
    "build": "astro build"
  }
}

参考答案

围栏代码块

解题思路：每段都用围栏代码块，按内容类型挑语言标识。命令行用 bash，JSON 用 json，目录输出不是任何语言，用 text 明确关闭高亮，比留空更可控。

详细步骤：

三个代码块都用三个反引号起止，闭合围栏独占一行，语言标识写在开围栏后面。
pnpm install 和 pnpm build --filter @kuaiyizhi/kit-ui-astro 都是 shell 命令，属于第一段代码块，标识写 bash。两行放在同一个块里，它们是连续执行的两条命令。
目录输出那段标识写 text。它没有语法可言，若留空，渲染器可能按默认语言猜测，把 dist/ 之类染成奇怪颜色。
package.json 片段标识写 json，读者一眼能看到 scripts 下挂着 build。
检验：三块代码各自带正确的 class="language-..."，目录输出那块不带语言类名。

最终答案：

先运行 `pnpm install`，然后执行下面这条命令：

```bash
pnpm build --filter @kuaiyizhi/kit-ui-astro
```

输出的目录结构如下：

```text
dist/
  index.mjs
  index.d.ts
```

最后确认一下 `package.json` 里的 `scripts` 字段：

```json
{
  "scripts": {
    "build": "astro build"
  }
}
```