标签仅适用于行内短代码，多行代码必须与嵌套使用以保留格式并确保语义正确，且内容需转义特殊字符。
直接用 <code> 标签是语义正确的起点，但仅靠它无法优雅展示——它不保留换行、不处理缩进、不转义特殊字符，还容易被浏览器误解析。真正优雅的关键，在于组合使用 + 必要的预处理。
为什么不能只用 <code> 单独包裹多行代码
<code> 是行内元素，浏览器会把所有空白符（包括换行、多个空格）压缩成单个空格。比如你写：
<code>
function hello() {
console.log("hi");
}</code>
实际渲染出来就是一行： function hello() { console.log("hi"); } ——完全失去结构。
- 必须配合
<pre class="brush:php;toolbar:false;"></pre>保留原始格式（换行、缩进） -
<pre class="brush:php;toolbar:false;"></pre>本身无语义，所以要用<pre class="brush:php;toolbar:false;"><code>...</code></pre>双层嵌套：外层管格式，内层管语义 - 否则搜索引擎和屏幕阅读器无法识别“这是一段代码”，而只是“一段等宽文字”
特殊字符必须转义，否则代码会消失或报错
HTML 解析器看到 <div> 就会尝试当标签处理，导致后续内容错乱甚至截断。下面这段代码：
<pre class="brush:php;toolbar:false;"><pre class="brush:php;toolbar:false;"><code>const el = document.querySelector("<div>");
<p>实际只会显示 <code>const el = document.querySelector(");</code>，因为 <code><div> 被当成未闭合标签吞掉了。
<ul>
<li>所有 <code> 必须写成 <code><</code>，<code>></code> → <code>></code>，<code>&</code> → <code>&</code></code>
</li>
<li>手动转义太麻烦？可用工具如 <code>he.encode()</code>（JavaScript）、<code>html.escape()</code>（Python）或 VS Code 插件“Auto Encode HTML”</li>
<li>别依赖后端模板自动转义——有些框架（如某些 PHP 模板）默认不转义 <code><pre class="brush:php;toolbar:false;"></pre> 内容
如何让 <pre class="brush:php;toolbar:false;"><code></code> 看起来专业又易读</pre>
纯语义还不够，用户需要可读性。加几行 CSS 就能显著提升体验：
pre code {
display: block;
padding: 1rem;
background: #f6f8fa;
border-radius: 4px;
overflow-x: auto;
font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
line-height: 1.5;
}
-
overflow-x: auto防止长行撑破容器（比white-space: pre-wrap更可靠） - 指定等宽字体栈，避免某些系统 fallback 到非等宽字体（如 Windows 上的 Times New Roman）
- 不要只设
font-family: monospace——它在不同平台渲染差异大，且可能模糊 - 如果支持语法高亮，优先用
Prism.js或highlight.js，它们会自动处理转义和 class 注入
什么时候该用 <details><summary></summary></details> 折叠代码
文档中嵌入大量示例代码时，页面会变得冗长。用 <details></details> 收起非核心代码是轻量级解决方案：
<details><summary>点击查看完整配置</summary><pre class="brush:php;toolbar:false;"><code>{ "timeout": 5000, "retry": true }</code>
- 原生支持，零 JS，无障碍友好（屏幕阅读器能识别展开/收起状态）
- 注意：
<summary></summary>内不能放<code>（语义冲突），所以代码必须放在<details></details>的子级，如<pre class="brush:php;toolbar:false;"><code></code></pre> - 别滥用——频繁折叠会增加用户操作成本，适合辅助说明、错误堆栈、长 JSON 等非主干内容
最常被忽略的一点：语义化不是贴标签，而是做判断。比如一个命令行交互片段：npm install --save-dev eslint，该用 <code> 还是 <kbd></kbd>？答案是后者——<kbd></kbd> 专指用户输入，<code> 指程序代码。混用会让语义失效，连带影响可访问性和 SEO 权重分配。
