语法详解

Markdown 代码块与语法高亮:写技术文档不踩坑

写教程、笔记或 README 时,代码是最容易“明明写了却不显示”的部分。这篇把行内代码、围栏块和语法高亮一次讲透。

一、行内代码:一句话里嵌代码

想在正文里提一个变量名、命令或文件名,又不想让它被当成普通文字,用一对反引号(`)包起来即可。它会渲染成等宽字体,并和正文区分开。

比如:安装依赖用 npm install markdown,注意不要把 < 直接粘进正文。

二、围栏代码块:成段代码

要放超过一行的代码,用三个反引号把代码上下包起来,这就是“围栏代码块”(fenced code block)。前后各空一行更稳。

```
function greet(name) {
  return "Hello, " + name;
}
```

围栏块里的所有缩进、空格都会原样保留,最适合贴整段脚本、配置或日志。

三、标注语言,开启语法高亮

在开头的三个反引号后面写上语言名,多数渲染器(GitHub、VS Code、365Lab 等)就会给关键字、字符串上色,可读性立刻提升:

```js
const sum = (a, b) => a + b;
console.log(sum(2, 3));
```

常见的语言标注:js / javascript、ts / typescript、python、bash / sh、html、css、json、sql。写错了也没事,只是不高亮而已,代码本身照常显示。

小技巧:行内代码也能高亮吗?标准 Markdown 不支持,但很多编辑器(包括 365Lab)对围栏块的支持已经足够覆盖 90% 场景。需要“行内彩色代码”时,优先改用短围栏块或普通强调。

四、缩进代码块(老写法)

在段落开头缩进 4 个空格或 1 个制表符,也能变成代码块,这是最早的写法:

    这是一段缩进代码块
    每一行都要保持同样的缩进

它不够直观,而且和列表缩进容易混淆,现在更推荐用围栏块;但读别人老文档时得认得它。

五、5 个最常踩的坑

1. 反引号里再出现反引号

若代码本身含反引号,用更多反引号包外层,例如 `` `code` ``。

2. 围栏块前后没空行

紧贴着上面正文写,有时整段被当成普通文本。前后各留一个空行最稳。

3. 代码里的尖括号没转义

像 <div> 这种 HTML 标签,直接写会被当成标签吞掉;在行内用 &lt; 转义,在围栏块里通常不用管(围栏块默认按纯文本处理)。

4. 长代码把页面撑爆

一行特别长时,好的渲染器会横向滚动。365Lab 的预览区对长代码做了横向滚动处理,移动端也不会把布局挤乱。

5. 平台不支持高亮

少数老博客或聊天工具不认语言标注,代码照样显示,只是没有颜色。发布前在目标平台先预览一次。

六、常见问题

Q:为什么我的代码块没有颜色?
A:检查开头的反引号后面是否写了语言名(如 ```python);另外确认目标平台支持高亮——GitHub、VS Code、365Lab 都支持。

Q:可以显示代码行号吗?
A:标准 Markdown 没有行号语法,要靠渲染器或插件。365Lab 预览专注“所见即所得”,需要行号时可导出后用支持的工具查看。

Q:代码里有 | 会被当成表格吗?
A:在围栏块里不会——围栏块里的管道符只是普通字符,只有表格语法区才会被解析。

Q:哪里能一边写一边看高亮效果?
A:打开 365Lab 在线编辑器,左边写围栏块、右边实时出高亮,免注册、内容本地保存。


语法全貌见 Markdown 语法速查表;写公式高亮可看 Markdown 写数学公式;想用代码写项目文档,见 Markdown 写 GitHub README。

打开编辑器,边写代码边看高亮

免注册、实时预览、内容本地保存。把围栏块粘进去,右边立刻出彩色结果。

免费开始写作 →