行内代码
行内代码是 Markdown 里最小的代码单元:一对反引号包住几个字符,渲染器就把它变成一段等宽文字。它几乎总是用来标记命令、文件名、变量名、环境变量和接口路径——这些东西如果直接混在正文里,读者分不清「这是需要你照着敲的字面量」还是「这是解释性描述」。这一页要把反引号的各种边界情况讲清楚,尤其是被包裹的内容本身就带反引号时该怎么办。
一行之内,用一对反引号包住内容即可:
请运行 `npm install` 安装依赖。
变量 `foo` 保存结果。
<p>请运行 <code>npm install</code> 安装依赖。
变量 <code>foo</code> 保存结果。</p>
反引号包住的内容不会再被解析成任何 Markdown 语法。星号、井号、下划线、方括号在里面全部退化为普通字符,这正是行内代码最实用的地方——当你需要把一段「看起来像语法的东西」原样展示时,用反引号最省事也最安全:
使用 `*星号*` 与 `**双星号**` 不产生强调
<p>使用 <code>*星号*</code> 与 <code>**双星号**</code> 不产生强调</p>
内容里含有反引号
如果被包裹的内容本身就带反引号,就把外层反引号加倍(加得更多也可以):
这叫 `` `code` `` 写法。
<p>这叫 <code>`code`</code> 写法。</p>
规则很朴素:外层反引号的数量必须比内容里出现的反引号串更长,解析器才能找到配对的结束位置。
两端的空格会被吃掉
代码段的内容如果同时以空格开头和结尾,解析器会各去掉一个。这是规范规定的行为,好处之一是让 ` 这种写法能干净地表示一个反引号本身:
`` ` `` 表示一个反引号
<p><code>`</code> 表示一个反引号</p>
但只有一侧有空格时,空格会被原样保留:
` a` 与 `a `
<p><code> a</code> 与 <code>a </code></p>
反斜杠不生效
代码里的反斜杠是普通字符,不会产生转义效果,\* 就显示出反斜杠加星号:
`a \* b` 的星号不会被转义
<p><code>a \* b</code> 的星号不会被转义</p>
同样地,代码里的 <、& 在生成 HTML 时会被转义成实体,<div> 变成 <div>。这正是它该有的行为——保证内容原样显示,而不是被当成标签解析。
行内代码的适用边界是「短到能塞进一句话里」:一个命令名、一个路径、一个变量名、一个配置键。超过这个尺度,就该换成代码块。
反过来,凡是不该被读者直接照抄的内容就别用行内代码。它带有「这是可执行内容」的暗示力,用它标注解释性词汇会让读者反复确认自己是不是漏了操作。需要强调的普通名词,用斜体或改写句子更合适。
| 写法 | 实际渲染 | 原因 |
|---|---|---|
npm install | 行内代码 | 基本用法 |
`code` | 含反引号的行内代码 | 内部有反引号,外层要加倍 |
` a ` | a | 两端空格各去掉一个 |
a | a | 只有一侧有空格,空格保留 |
*文字* | *文字* | 代码内不解析强调 |
a \* b | a \* b | 反斜杠在代码内不转义 |
| 跨空行的一对反引号 | 不成代码 | 不能跨越段落边界 |
代码段不能跨越段落。 反引号可以跨过一次换行(换行会折成一个空格),但中间一旦出现空行,段落就断了,代码段随之失效,页面上会原样显示出那些反引号和文字。
把下面这句话改写成 Markdown,要求命令、文件名、环境变量都用行内代码标出,并且让句子里原本带反引号的那段文字原样显示出来。
先执行 pnpm install,然后复制 .env.example 为 .env.local;README.md 里写的 `code` 标记要保持原样,最后把 NODE_ENV 设成 production。
解题思路:
行内代码用一对反引号包裹。关键难点是最后那个 code——它自身带反引号,如果只用一对反引号包裹,外层的反引号会和内容里的反引号配对错位,导致整段失效。解法是把外层反引号加倍,写成两个反引号夹住内容。
详细步骤:
- 命令
pnpm install用一对反引号包住:写成`pnpm install`。 - 两个文件名
.env.example与.env.local各自用一对反引号包住;它们在句中是两个不同的路径,要分开写,不能合并成一段。 - 环境变量
NODE_ENV用一对反引号包住。 - 原样显示的那段
code自身含有反引号,外层必须加倍:外层改用两个反引号(开头两个、结尾两个),内层保留原有的单个反引号,整段才算配对成功。 - 检验:渲染后命令、文件名、环境变量都变成等宽文字,而
`code`这一段显示为带反引号的原样内容,没有把句子切碎。
最终答案:
先执行 `pnpm install`,然后复制 `.env.example` 为 `.env.local`;`README.md` 里写的 `` `code` `` 标记要保持原样,最后把 `NODE_ENV` 设成 `production`。读完这一页,你应当能写出正确的行内代码,能在内容含反引号时主动把外层加倍,也能解释两端空格为什么会被吃掉、反斜杠为什么不转义、为何不能跨段落。接下来写文档时,凡是命令、路径、变量名,你都能不假思索地加上反引号,不会因为少写一对括号让整段文字原样裸露。
