技术文档应正确使用html语义化标签：用组合保留代码格式，用于内联代码，/替代/实现语义强调，复杂结构优先采用、等语义标签配合css控制样式。
用 <pre class="brush:php;toolbar:false;"></pre> 保留原始缩进和换行
技术文档常含代码块、配置片段或命令行输出，这些内容对空格、制表符、换行敏感。<pre class="brush:php;toolbar:false;"></pre> 是唯一能原样保留这些格式的 HTML 标签。浏览器会用等宽字体渲染它，且不合并多余空格。
常见错误是把 <pre class="brush:php;toolbar:false;"></pre> 当成“加粗”或“强调”用，结果导致段落错位、响应式失效。它只适合小段固定格式内容，比如：
curl -X POST http://localhost:8000/api/v1/users \
-H "Content-Type: application/json" \
-d '{"name":"alice","email":"a@example.com"}'
注意：不要在 <pre class="brush:php;toolbar:false;"></pre> 里嵌套 <p></p> 或 <div>；里面直接放纯文本或 <code><code> 即可。
用 <code> 包裹内联代码片段
<code> 不处理换行或缩进，只标记“这是代码”，语义清晰、样式可控。它该出现在句子中，比如 “运行 pip install requests 安装依赖”。
容易踩的坑：
- 误用
<b></b>或<span></span>替代 —— 它们没语义，屏幕阅读器无法识别为代码 - 在
<code>里写 HTML 字符（如<div>）却不转义 —— 必须写成 <code><div>，否则被浏览器解析为真实标签 - 嵌套
<pre class="brush:php;toolbar:false;"></pre>和<code>时结构混乱，正确写法是<pre class="brush:php;toolbar:false;"><code>...</code></pre>
别用 <u></u> 或 <b></b> 做技术强调
HTML5 明确不鼓励用 <u></u>（下划线）表示重点，因为用户已习惯它代表链接；<b></b> 只是“视觉加粗”，无语义。技术文档需要传达意图：<strong></strong> 表示关键警告（如“不可回滚”），<em></em> 表示语气强调（如“务必检查返回值”）。
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
例如：
错误写法：<u>必须设置 timeout 参数</u>
正确写法：<strong>必须设置 timeout 参数</strong> —— 屏幕阅读器会加重读出，CSS 也可统一加红底白字
复杂结构优先用 CSS 而非嵌套格式化标签
当文档出现多级命令参数、环境变量对照表、JSON 示例等，硬塞进 <pre class="brush:php;toolbar:false;"></pre> 或一堆 <code> 会导致可维护性崩坏。此时应放弃纯 HTML 格式化标签，改用语义化结构 + CSS：
比如用 <dl></dl> + <dt></dt>/<dd></dd> 做配置项说明，用 <table> 做状态码对照，再配 <code>white-space: pre-wrap 和 font-family: monospace 控制显示。
根本问题不是“怎么标得好看”，而是“怎么让开发者一眼抓住关键约束和边界条件”。格式化标签只是辅助，逻辑分层和语义准确才是技术文档存活的关键。
