Repository Wiki
LyraVoid/Mizuki

RSS 与 Atom 全文订阅

Mizuki 为站点提供 RSS 2.0 与 Atom 双格式的全文（full-content）订阅输出，并复用与文章页面完全相同的 Markdown/MDX 渲染管线，使订阅者在阅读器中即可获得与站内一致的富内容体验（代码高亮、数学公式、Mermaid 图表等）。

Purpose and Scope

本页覆盖 Mizuki 博客主题中订阅能力的端到端机制：

  • 全文 RSS 与 Atom 输出的能力边界与设计意图（"同一渲染管线"原则）
  • 订阅与 SEO 体系（sitemap、robots.txt、Open Graph）的关系
  • 加密文章在订阅输出中的排除规则与安全边界说明

以下相关主题有意留给兄弟页面，本页仅作交叉指引：

  • Markdown/MDX 内容的渲染细节（callouts、KaTeX、Expressive Code 等）：属于内容渲染能力，不在本页展开
  • 站点地图与 robots.txt 的完整生成机制：属于 SEO 专题
  • 加密文章的浏览器端加密实现：本页仅说明其对订阅输出的影响

Overview

Mizuki 的订阅设计有一个明确的核心原则：文章页面、RSS、Atom 共用同一条 Markdown/MDX 管线。这意味着：

  • 全文而非摘要：条目输出渲染后的完整正文，而不是截断的摘要文本。README 中的功能清单将其表述为「RSS 和 Atom 全文订阅，复用文章页面的 Markdown/MDX 管线」（README.md）。
  • 富内容一致：README 明确指出「Mizuki uses one Markdown/MDX pipeline for article pages, RSS, and Atom. It supports callouts, math, enhanced code blocks, Mermaid, PlantUML, GitHub cards, Wiki Links, spoilers, responsive images, image grids, Fancybox lightboxes, and HTML embeds.」（README.en.md）。订阅者拿到的不是降级的纯文本，而是同一管线产出的富内容。
  • 双格式输出：同时提供 RSS 与 Atom 两种标准，覆盖不同阅读器的偏好，并作为整体 SEO 策略的一部分（README.md）。

典型使用场景：

  1. 读者将 rss.xml / atom.xml 订阅地址加入 Feedly、NetNewsWire 等阅读器，即可离线阅读全文
  2. 搜索引擎与聚合器通过 feed 发现机制抓取站点最新内容
  3. 跨站内容同步或归档工具消费结构化的全文数据

Architecture

订阅能力由 Astro 官方 RSS 集成驱动，构建期一次性生成静态 feed 文件：

Loading diagram...

图中的关键关系说明：

  • 单一管线，三种出口：Markdown / MDX 管线 是唯一的内容加工层，文章页、RSS、Atom 都从它取渲染结果。这是「订阅者看到的内容与站内一致」这一产品目标的架构保障——不存在为 feed 单独维护的第二套渲染逻辑，也就不会出现"站内正常、订阅乱码"的分歧。
  • 集成来源：项目通过 package.json 依赖 @astrojs/rss（^4.0.19），这是 Astro 官方的 RSS 生成集成（package.json）。
  • 加密文章的排除：README 明确说明「加密文章不会进入 RSS 和 Atom，但浏览器端加密不是服务端访问控制」（README.md）。即加密文章在生成 feed 时被过滤掉，图中以虚线表示该排除关系。
  • SEO 协同：RSS/Atom 与 sitemap、robots.txt 共同构成站点的可发现性体系（README.md）。

Core Flow：订阅生成的端到端流程

基于项目结构与依赖关系，订阅生成遵循 Astro 静态站点的标准构建时流程。以下流程图反映该机制的整体阶段：

Loading diagram...

各阶段说明：

  1. 构建期静态生成：Mizuki 是静态站点，feed 在 astro build 时一次性生成，运行期没有服务端计算。这使订阅输出天然具备 CDN 分发、零冷启动的特性。
  2. 内容收集与过滤：Astro 内容集合负责收集文章；加密文章在此环节被排除。README 的安全表述「加密文章不会进入 RSS 和 Atom，但浏览器端加密不是服务端访问控制」（README.md）说明排除是产品层的选择性过滤，而非访问控制机制。
  3. 渲染复用：非加密文章的正文走与文章页相同的管线，因此 feed 中的 content 字段是渲染后的完整富文本。
  4. 双格式输出：同一份渲染结果分别序列化为 RSS 2.0 与 Atom XML，由 @astrojs/rss 集成提供基础生成能力（package.json）。

数据安全边界：加密文章与订阅

这是订阅能力中最值得注意的边界条件。项目文档对加密内容的定位十分清晰：

Markdown and MDX support callouts, KaTeX math, Expressive Code, Mermaid, PlantUML, GitHub cards, Wiki Links, spoilers, responsive images, image grids, lightboxes, and HTML embeds. Encrypted posts are excluded from RSS and Atom, but browser-side encryption is not server-side access control.（README.en.md）

设计意图解读：

  • 排除而非加密：加密文章不会被"加密后放进 feed"，而是直接不出现在订阅输出里。这保证了 feed 中不存在可被离线暴力破解的密文载荷。
  • 明确的能力声明：浏览器端加密本质上只是客户端混淆，不能替代服务端鉴权。README 主动声明这一点，属于对使用者的诚实安全边界告知——即便内容被浏览器端加密保护，源文件本身是公开托管的。
  • 全文订阅的推论：正因为输出的是全文，排除逻辑必须发生在渲染输出之前（或至少在序列化之前），否则任何遗漏都会导致受保护内容整篇泄露到公开的 XML 文件中。这是该过滤规则必须严格、且优先级高于内容渲染的原因。

Usage Examples

由于源码探索预算在定位具体端点实现文件前已耗尽，本页未能读取到 src/ 下 RSS/Atom 端点的具体实现代码，因此不提供虚构的代码示例。以下仅呈现仓库中可直接验证的配置级证据。

依赖声明（package.json）

json
34: "@astrojs/mdx": "^7.0.3", 35: "@astrojs/rss": "^4.0.19", 36: "@astrojs/sitemap": "^3.7.3",

Source: package.json

该依赖块说明了订阅能力的三个技术支点：@astrojs/rss 负责 feed 生成；@astrojs/mdx 支撑共享渲染管线的 MDX 能力；@astrojs/sitemap 与 feed 同属可发现性体系。

能力声明（README）

markdown
- [x] RSS 和 Atom 全文订阅，复用文章页面的 Markdown/MDX 管线

Source: README.md

Configuration Options

实现细节未在本次源码探索中定位到（源码工具预算耗尽）。基于 Astro 生态的通行做法，@astrojs/rss 的典型配置维度包括站点地址、标题、描述、语言、条目数量上限与 stylesheet 等，但 Mizuki 项目内各选项的具体取值与默认值无法从已收集证据中核实，此处不做臆测。如需精确配置项，请查阅 src/pages/ 下的 feed 端点文件（通常为 rss.xml.ts / atom.xml.ts）。

API Reference

无公开 API。订阅输出是构建期生成的静态 XML 文件，不暴露任何运行期方法或服务接口。消费者仅通过 HTTP GET 获取生成的 feed 文件。

Professional Notes

失败模式与边界情况

  • 加密内容泄露风险：全文订阅的主要风险点。项目的缓解措施是在 feed 生成前排除加密文章；任何绕过该过滤的改动都可能把受保护内容写入公开 XML。相关排除声明见 README.md。
  • 大体积 feed：全文输出意味着 feed 体积随文章数线性增长。项目 README 提及「性能优化，懒加载和缓存机制」（README.md），但 feed 条目数量上限的具体策略未在本次探索中核实。
  • 富内容在阅读器中的降级：尽管管线与文章页一致，第三方阅读器对 Mermaid、PlantUML、交互组件的渲染支持程度各异，实际展示效果受阅读器能力约束。

并发与一致性

订阅文件为构建期产物，静态托管下不存在并发写入问题。一致性由构建保证：每次构建产出的 feed 与同批次文章页内容天然同源（同一管线、同一次渲染）。

运维要点

  • 修改内容管线（如新增渲染插件）后需完整重建，feed 与文章页才会同步更新
  • feed URL 的稳定性依赖站点路由配置，变更会导致读者订阅失效
  • 可通过 CDN 缓存策略控制 feed 的更新传播速度，但源文件仅在构建时刷新

Extension Points

基于 Astro 架构，订阅能力的可扩展方向包括：自定义 feed 端点以增加分页/分类 feed、调整条目过滤规则（例如额外排除草稿或特定标签）、以及为 feed 输出附加 XSL 样式表提升浏览器可读性。这些方向的现有实现细节未在本次探索中核实。