为hexo博客添加附件卡片与沉浸式预览器
内容提要
本文介绍为Hexo博客添加附件卡片与沉浸式预览器的教程。通过构建期标签插件生成带数据属性的HTML卡片，运行期前端脚本按类型分流渲染，支持Markdown、PDF、图片等格式预览，不依赖在线服务。需配置skip_render、引入marked和DOMPurify库，并注意安全过滤、PJAX兼容等细节。
延伸解读
安全过滤是预览器的生命线
文章强调，Markdown 附件是纯文本 fetch 进来的，可能包含 <script> 或 onerror 等恶意内容。因此，marked 渲染出的 HTML 必须经过 DOMPurify 消毒后才能插入 DOM。作者还专门在测试文档中放置了 XSS 探针来验证清理链路。这提醒读者，任何涉及用户上传或外部内容的预览功能，都必须将安全过滤视为核心环节，不能省略。
PJAX 兼容性不可忽视
文章指出，如果博客启用了 PJAX（如 NexT 主题），换页时若不监听 pjax:send 事件收起浮层，遮罩会残留，导致页面像死机一样。此外，事件委托在 document 上，使得动态插入的卡片无需重新绑定。这提示读者，在实现类似交互时，需考虑与主题的 PJAX 机制配合，避免出现界面异常。
构建期与运行期分离的设计思路
该方案将功能拆分为构建期标签插件和运行期前端脚本。构建期负责生成带 data-* 属性的静态 HTML，类型判断、强调色等都在此确定；运行期只负责读取数据并按类型分流渲染。这种设计降低了前端复杂度，也便于维护。读者可借鉴此思路，将类似功能模块化，提高代码的可读性和可扩展性。
Q&A
如何为Hexo博客添加附件卡片和预览功能？
通过编写一个Hexo标签插件，在构建期将attachment标签编译为带data-*属性的HTML卡片；再编写一个前端脚本，在运行期通过事件委托读取卡片数据，按类型（如Markdown、PDF、图片）渲染到浮层中。同时需要配置skip_render让附件原样输出，并引入marked和DOMPurify库进行安全渲染。
Hexo附件预览功能需要哪些依赖库？
需要marked（用于Markdown渲染）和DOMPurify（用于HTML消毒）。marked 4.x使用UMD版本，DOMPurify 2.x用于兼容老浏览器。
为什么需要配置skip_render？
如果不配置skip_render，source/files/下的.md文件会被Hexo当作页面渲染成HTML，前端fetch到的就不是原始文本，导致预览乱码。配置skip_render可以让附件原样拷贝到public/，供前端直接读取。
附件卡片支持哪些文件类型？
支持Markdown、文本、PDF、Excel、PowerPoint、图片、ZIP等，通过TYPE_MAP映射，可扩展。
如何确保Markdown渲染的安全性？
marked渲染出的HTML必须经过DOMPurify消毒后再插入DOM，防止XSS攻击。同时，纯文本和源码分支使用textContent写入，天然免疫注入。
如何解决PJAX换页后浮层残留的问题？
需要监听pjax:send事件，在换页时收起浮层，否则遮罩会残留导致页面无法交互。
附件卡片如何避免影响NexT的目录（TOC）？
卡片标题使用span而不是h4等标题标签，否则NexT的目录会把附件标题也收进去，导致TOC混乱。
如何将附件卡片功能集成到NexT主题中？
通过NexT的custom_file_path功能，在head.swig中引入样式，在body-end.swig中引入脚本，并配置window.ATTACHMENT_CONFIG传递root和库的URL。
