必须是包裹，即结构：保留格式，提供语义；颠倒或单独使用均导致格式崩坏、高亮失效、seo与无障碍支持缺失；代码须转义特殊字符，class名需严格匹配高亮库要求。
必须是 包裹 <pre class="brush:php;toolbar:false;">，不能反过来
HTML 语义规范和所有主流高亮库（Prism.js、highlight.js）都只认 <pre class="brush:php;toolbar:false;"><code></code></pre> 这一固定结构。<code><code><pre class="brush:php;toolbar:false;"></pre> 是非法嵌套，浏览器会自动修正 DOM，导致 <pre class="brush:php;toolbar:false;"></pre> 被踢到外面、<code> 孤立，最终格式崩坏、高亮失效。
常见错误现象：
- 代码被压成一行，缩进全丢
- 复制粘贴后缩进变成制表符或空格不一致
- 屏幕阅读器读作“预格式化文本”，而非“JavaScript 代码”
原因很简单：<pre class="brush:php;toolbar:false;"></pre> 是块级容器，负责保留换行与空格；<code> 是语义锚点，告诉辅助技术、搜索引擎和样式系统“这是计算机代码”。二者职责不同，顺序不可颠倒。
为什么不能只用 <pre class="brush:php;toolbar:false;"></pre> 或只用 <code>
单独用 <pre class="brush:php;toolbar:false;"></pre>：格式能保留，但语义缺失。搜索引擎可能不索引为代码片段，CSS 难以精准隔离样式，高亮库默认不扫描它。
单独用 <code>：语义正确，但它是行内元素——浏览器会把所有换行符、多个空格、制表符全压缩成单个空格。一段 Python 函数直接塌成 def hello():print("Hi")，完全不可读。
所以必须组合：
-
<pre class="brush:php;toolbar:false;"></pre>提供格式容器（保留缩进、换行、空格） <code>提供语义标识（这是代码，不是诗歌或日志）- 二者嵌套才是唯一被 HTML 规范、辅助工具、SEO 和高亮库共同认可的路径
HTML 特殊字符不转义会导致 DOM 解析失败
只要原始代码含 、<code>>、&，就必须在插入前实体化。否则浏览器在解析 HTML 阶段就会把它们当真实标签处理。
生成Claude风格的精美单页HTML汇报文件。当用户需要生成"汇报"、"周报"、"月报"、"项目进度"、"复盘"、"演示"、"slide deck"、"状态报告"、"工作总结"时触发。支持6种模板：周报(weekly)、项目进度(project)、月度总结(monthly)、复盘报告(postmortem)、演示文稿(slid
例如这段代码：
<div id="app"></div>
如果不转义，浏览器会尝试渲染一个空 <div>，后续所有内容错位，甚至提前闭合 <code><pre class="brush:php;toolbar:false;"><code></code> 块。
<p>必须手动替换为：</p>
</pre>
<ul>
<li><code> → <code><
> → >
& → &
服务端输出建议统一调用 htmlspecialchars()；前端动态插入请用 textContent，别用 innerHTML。
class 属性写法影响语法高亮是否触发
高亮库对 <code> 的 class 属性非常敏感。写错就等于没写：
- Prism.js 默认识别
language-javascript，写成js或Javascript通常无效 - highlight.js 接受
javascript，但加language-前缀最稳（如language-bash） - class 名里有空格、拼写错误、大小写混用，都会跳过该代码块
另外，脚本必须在 DOM 加载完成后执行初始化，比如 highlight.js 需显式调用 hljs.highlightAll()；Prism.js 则依赖 Prism.highlightAll() 或自动钩子，但前提是结构完整、class 正确。
最容易被忽略的是：很多开发者以为只要写了 class="js" 就够了，其实 class 名是否匹配、脚本是否加载、DOM 是否就绪，三者缺一不可——任一环节断掉，高亮就静默失败，连报错都没有。
