marked.parse()仅做语法转换，不注入css/js，需手动添加样式、处理路径、控制渲染生命周期。
为什么直接用 marked.parse() 会漏掉样式和交互？
很多人试过在 HTML 页面里用 marked.parse() 把 Markdown 字符串转成 HTML，结果发现：标题没字号层级、代码块没高亮、链接没下划线、甚至表格都塌了。这不是解析失败，而是 marked 默认只做语法转换，不注入任何 CSS 或 JS 行为。
-
marked.parse()输出纯 HTML 片段，不含 class、style 或事件绑定 - 常见主题类名（如
github-markdown、markdown-body）需要手动加 wrapper 容器并引入对应 CSS - 像
<details></details>这类原生交互标签虽能保留，但折叠动画、默认箭头图标等视觉反馈仍依赖浏览器或额外 CSS - 如果原始 Markdown 含图片路径，而页面是本地 file:// 协议打开，相对路径会 404 —— 这不是解析器问题，是加载上下文缺失
自定义加载器的核心：分离“内容获取”和“渲染执行”
所谓“无缝嵌入”，本质是让 Markdown 内容像 HTML 模板的一部分一样被声明式加载、按需解析、统一挂载。关键不是换库，而是控制三件事：从哪取、怎么转、往哪塞。
- 取：用
fetch('doc.md')替代内联<script type="text/markdown"></script>，避免 HTML 文件臃肿，也方便复用同一份 .md - 转：封装一个
loadMarkdown(url, options)函数，内部调用marked.parse()，同时自动注入highlight.js代码高亮、修补图片 base64 内联（可选）、过滤危险标签（如<script></script>） - 塞：指定一个带唯一 id 的容器（如
<article id="content"></article>），而不是直接操作document.body，避免污染全局结构
容易踩的坑：HTML 标签混写时的解析边界
你可以在 Markdown 里写 <div class="note">⚠️ 注意</div>，但必须清楚解析器在哪切回 Markdown 模式。CommonMark 规范规定：块级 HTML 标签（<div>、<code><section></section>、<details></details>）之后的内容，直到遇到同级闭合标签前，全部跳过 Markdown 解析；而行内标签（<span></span>、<img>）则允许内部继续用 Markdown 语法。
- 错误写法：
<div>**加粗文本**</div>→**加粗文本**不会被转成<strong></strong>，原样输出 - 正确写法：
<div><p>**加粗文本**</p></div>→<p></p>是块级容器，其内部仍启用 Markdown 解析（部分解析器支持，如 marked +smartLists: true） - 更稳妥做法：在 HTML 块内改用纯 HTML，比如
<div><p><strong>加粗文本</strong></p></div> - 特别注意：
<pre class="brush:php;toolbar:false;"><code></code> 块内所有内容都会原样保留，连反斜杠转义都失效 —— 别在里面写 Markdown</pre>
要不要预渲染？看你的部署场景
客户端实时解析适合开发调试或内容少的页面；但若文档长、图片多、SEO 敏感，就得考虑服务端预渲染。区别不在技术难度，而在责任归属。
- 客户端渲染：JS 加载完才显示内容，首屏白屏时间长；
fetch请求失败即整块空白；Lighthouse 评分低 - 服务端预渲染（如用 Node +
marked+fs.readFile）：HTML 返回即完整，SEO 友好，但每次改 .md 都要重新构建或触发 API 生成 - 折中方案：用
service worker缓存已解析的 HTML 片段，首次访问慢，后续秒开 —— 但需处理缓存失效逻辑
真正卡住人的，往往不是解析本身，而是把 Markdown 当成静态文本去加载，却忘了它依赖上下文路径、样式链、甚至 DOM 就绪时机。嵌入不是“扔进去就完事”，是把它当作模版系统里一个有生命周期的模块来管理。
