晴雀堂

从博客文章中的附件需求出发

在技术文章里，作者有时需要提供大纲、数据表或源码文件。直接放一个裸链接，读者点击后可能开始下载，也可能在浏览器里看到未经排版的纯文本。晴雀堂的教程提出一种更直观的做法：在文章里标注附件信息，构建后显示为卡片，卡片提供文件名称、类型等提示；读者点击时，再由页面打开浮层预览或给出下载入口。

这篇教程将实现拆成构建期与运行期两个部分。构建期由 Hexo 标签插件读取文章里写入的附件标签，把文件路径、名称、类型和显示信息转成 HTML 卡片及 data 属性。运行期的前端脚本接收点击事件，读取卡片保存的数据，再依据文件类型选择对应的展示方式。这样做让类型判断集中在构建阶段，浏览器端只需要按既定类型调用合适的处理逻辑。

将附件原文件保留为可读取资源

教程把附件本体放在 Hexo 的 source/files 目录，并通过配置跳过常规渲染，让原始文件按原样复制到生成后的 public 目录。这个安排很重要：如果 Markdown 附件被静态站点生成器当作普通页面重新渲染，前端请求得到的可能是转换后的 HTML，而不是原始文本。预览器需要读取源文件，才能将 Markdown 内容交给浏览器中的渲染器处理。

因此，附件卡片和附件文件承担不同职责。卡片负责呈现链接、类型和交互入口；存放在站点输出目录中的原文件则作为预览或下载的实际数据来源。站长在部署后需要确认两者路径相互对应，资源能够通过站点地址访问。教程通过单独设置附件目录的构建行为，避免把“页面如何展示”和“文件如何发布”混成一个问题。

按扩展名映射到不同展示方式

教程采用一个文件类型映射表，把扩展名关联到卡片标签、视觉样式和前端处理类别。例如 Markdown 与文本文件属于可读取内容，PDF 可以使用浏览器的内嵌显示方式，图片可以直接呈现；表格和演示文稿等办公文件则提示用户下载，压缩包等二进制文件也可以保留为下载入口。这个类型表使新增格式时有明确位置，开发者可以为新扩展名指定合适的处理类别。

构建阶段的标签插件负责根据附件路径推断类型，也允许文章作者显式传入标题或类型信息。插件再生成带有必要属性的 HTML 卡片。前端脚本把事件监听委托到文档层面，用户点击卡片时读取对应属性，再根据类型分派到 Markdown 渲染、文本展示、PDF 预览、图片显示或普通下载等处理函数。页面的展示逻辑因此不需要在每篇文章里重复编写。

预览器如何保持阅读连续性

教程描述的交互是在当前页面上方打开一个浮层，而不是跳转到新的页面。读者可以在原文章中查看附件，关掉预览后继续阅读。Markdown 文件由客户端渲染成较易阅读的内容；PDF 以内嵌方式展示；图片直接查看；办公文档则给出下载提示。对博客读者而言，这让不同类型文件有清楚一致的入口，也保留了每类文件适合的处理方式。

将不同格式分开处理，可以避免把所有附件都当作同一种内容。文本类文件需要可读的版式，PDF 更适合保留页面布局，图片适合原样展示，办公文件则通常需要本地应用继续编辑。卡片可提前显示类型，让读者在点击前知道自己将进入预览还是下载流程。教程中的映射表把这些差异集中起来，便于后续调整和维护。

实现时检查路径、安全和降级行为

标签插件需要把附件路径编码进卡片属性，前端脚本再从这些属性取出文件地址、显示名称和类型。生成 HTML 时要对用户填写的标题和路径进行转义，避免把普通文字当作标签或属性代码解析。教程示例包含 HTML 转义函数，并将未知类型映射到通用文件展示类别，给未登记扩展名留下可预期的后备表现。

部署后可以逐项检查：文章标签是否生成卡片、卡片数据是否正确、附件原文件是否出现在发布目录、Markdown 是否能渲染、PDF 和图片是否能够查看，以及不支持预览的文件是否明确提示下载。由于浏览器能力、文件类型和站点部署路径各有差异，实际配置还需要在当前 Hexo 主题和部署环境中核对。教程将附件目录设置、构建插件、前端脚本、样式和页面注入分别说明，便于站长按模块定位问题。

适合希望增强博客附件体验的站长

晴雀堂的文章不只介绍最终效果，也把附件目录、类型映射、事件处理和样式注入等实现环节串在一起。读者可以先从整体设计理解卡片与预览器的分工，再按自己常用的文件格式扩展映射表，并通过部署检查确认资源路径和交互都正常。对于经常在文章里分享 Markdown、PDF、图片或源码的博客作者，这个思路能让附件说明更清楚，也让读者在预览和下载之间有合适的选择。