Markdown 代码块与语法高亮:写技术文档不踩坑
写教程、笔记或 README 时,代码是最容易“明明写了却不显示”的部分。这篇把行内代码、围栏块和语法高亮一次讲透。
Markdown 程式碼塊與語法高亮:寫技術文件不踩坑
寫教學、筆記或 README 時,程式碼是最容易「明明寫了卻不顯示」的部分。這篇把行內程式碼、圍欄塊和語法高亮一次講透。
Markdown Code Blocks & Syntax Highlighting: Writing Technical Docs Without Pitfalls
When writing tutorials, notes, or READMEs, code is the part most likely to be "written but not shown." This article covers inline code, fenced blocks, and syntax highlighting in one go.
一、行内代码:一句话里嵌代码
想在正文里提一个变量名、命令或文件名,又不想让它被当成普通文字,用一对反引号(`)包起来即可。它会渲染成等宽字体,并和正文区分开。
比如:安装依赖用 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 标签,直接写会被当成标签吞掉;在行内用 < 转义,在围栏块里通常不用管(围栏块默认按纯文本处理)。
4. 长代码把页面撑爆
一行特别长时,好的渲染器会横向滚动。365Lab 的预览区对长代码做了横向滚动处理,移动端也不会把布局挤乱。
5. 平台不支持高亮
少数老博客或聊天工具不认语言标注,代码照样显示,只是没有颜色。发布前在目标平台先预览一次。
六、常见问题
Q:为什么我的代码块没有颜色?
A:检查开头的反引号后面是否写了语言名(如 ```python);另外确认目标平台支持高亮——GitHub、VS Code、365Lab 都支持。
Q:可以显示代码行号吗?
A:标准 Markdown 没有行号语法,要靠渲染器或插件。365Lab 预览专注“所见即所得”,需要行号时可导出后用支持的工具查看。
Q:代码里有 | 会被当成表格吗?
A:在围栏块里不会——围栏块里的管道符只是普通字符,只有表格语法区才会被解析。
Q:哪里能一边写一边看高亮效果?
A:打开 365Lab 在线编辑器,左边写围栏块、右边实时出高亮,免注册、内容本地保存。
语法全貌见 Markdown 语法速查表;写公式高亮可看 Markdown 写数学公式;想用代码写项目文档,见 Markdown 写 GitHub 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 標籤,直接寫會被當成標籤吞掉;在行內用 < 轉義,在圍欄塊裡通常不用管(圍欄塊預設按純文字處理)。
4. 長程式碼把頁面撐爆
一行特別長時,好的渲染器會橫向捲動。365Lab 的預覽區對長程式碼做了橫向捲動處理,行動端也不會把佈局擠亂。
5. 平台不支援高亮
少數老部落格或聊天工具不認語言標註,程式碼照樣顯示,只是沒有顏色。發佈前在目標平台先預覽一次。
六、常見問題
Q:為什麼我的程式碼塊沒有顏色?
A:檢查開頭的反引號後面是否寫了語言名(例如 ```python);另外確認目標平台支援高亮——GitHub、VS Code、365Lab 都支援。
Q:可以顯示程式碼行號嗎?
A:標準 Markdown 沒有行號語法,要靠渲染器或外掛。365Lab 預覽專注「所見即所得」,需要行號時可匯出後用支援的工具查看。
Q:程式碼裡有 | 會被當成表格嗎?
A:在圍欄塊裡不會——圍欄塊裡的管線符只是普通字元,只有表格語法區才會被解析。
Q:哪裡能一邊寫一邊看高亮效果?
A:打開 365Lab 線上編輯器,左邊寫圍欄塊、右邊即時出高亮,免註冊、內容本機儲存。
語法全貌見 Markdown 語法速查表;寫公式高亮可看 Markdown 寫數學公式;想用程式碼寫專案文件,見 Markdown 寫 GitHub README。
1. Inline code: code inside a sentence
When you want to mention a variable name, command, or file name in the body without it being read as plain text, wrap it in a pair of backticks (`). It renders in a monospace font and stands apart from the body text.
For example: install dependencies with npm install markdown, and don't paste < directly into the body text.
2. Fenced code blocks: multi-line code
To include code longer than one line, wrap it top and bottom withthree backticks—that's a "fenced code block." Leaving a blank line before and after is safer.
```
function greet(name) {
return "Hello, " + name;
}
```
All indentation and spaces inside a fenced block are preserved exactly, making it ideal for pasting whole scripts, configs, or logs.
3. Tag the language for syntax highlighting
Writing a language name after the opening three backticks makes most renderers (GitHub, VS Code, 365Lab, etc.) color keywords and strings, instantly improving readability:
```js
const sum = (a, b) => a + b;
console.log(sum(2, 3));
```
Common language tags: js / javascript, ts / typescript, python, bash / sh, html, css, json, sql. Getting it wrong is harmless—the code still shows, just without highlighting.
Tip: Can inline code be highlighted too? Standard Markdown doesn't support it, but most editors (including 365Lab) cover 90% of cases well enough with fenced blocks. When you need "inline colored code," prefer a short fenced block or plain emphasis.
4. Indented code blocks (the old way)
At the start of a paragraph,indent by 4 spaces or 1 tab and it also becomes a code block—this was the original syntax:
This is an indented code block
Every line keeps the same indentation
It isn't very intuitive and easily confuses with list indentation, so fenced blocks are preferred now; but you should still recognize it when reading others' old docs.
5. 5 most common pitfalls
1. A backtick appears inside the backticks
If the code itself contains a backtick, wrap it in more backticks, e.g. `` `code` ``.
2. No blank line around the fenced block
Writing it flush against the paragraph above sometimes makes the whole thing read as plain text. A blank line on each side is safest.
3. Unescaped angle brackets in code
An HTML tag like <div> written directly gets swallowed as a tag; escape inline with <, while inside a fenced block you usually don't need to (fenced blocks are treated as plain text by default).
4. Long code breaks the layout
When one line is very long, a good renderer scrolls horizontally. 365Lab's preview handles long code with horizontal scrolling, so even mobile won't wreck the layout.
5. Platform doesn't support highlighting
A few old blogs or chat tools ignore the language tag; the code still shows, just without color. Preview once on the target platform before publishing.
6. FAQ
Q: Why is my code block not colored?
A: Check whether a language name (like ```python) follows the opening backticks; also confirm the target platform supports highlighting—GitHub, VS Code, and 365Lab all do.
Q: Can I show line numbers?
A: Standard Markdown has no line-number syntax; it relies on the renderer or a plugin. 365Lab's preview focuses on WYSIWYG—if you need line numbers, export and view with a tool that supports them.
Q: Will a | in code be treated as a table?
A: Not inside a fenced block—the pipe character there is just a normal character; only the table syntax region is parsed as a table.
Q: Where can I write and see highlighting at the same time?
A: Open the 365Lab online editor, write fenced blocks on the left and see highlighting live on the right—no sign-up, content stored locally.
For the full syntax picture, see the Markdown syntax cheat sheet; for formula highlighting see Writing math in Markdown; to write project docs with code, see Writing GitHub READMEs in Markdown.