文章页面与阅读体验（目录、阅读时间、相关文章）

Mizuki 是一个基于 Astro 的静态博客项目，本页聚焦"单篇文章页面"在读者侧呈现的三类阅读体验能力：文章目录（TOC）、阅读时间（reading time）估算，以及相关文章（related posts）推荐。本页同时说明这些能力在仓库中的定位方式与可验证的配置入口。

证据边界声明（重要）：本次源码考察在工具预算（6 次调用）内，通过 ListFiles 与 Grep 未能在仓库中定位到目录 / 阅读时间 / 相关文章的具体实现源码文件（例如 src/**/*.astro 下未检索到 toc / TableOfContents 等标识符的命中；唯一一次 toc 大小写不敏感搜索命中的是 astro.config.mjs 中的 showCopyToClipboardButton 与 pnpm-lock.yaml 中的哈希噪声）。因此本页描述以可验证的仓库结构证据为基础，凡是属于实现细节推断的部分均明确标注，绝不虚构代码示例。

目的与范围

本页覆盖：

文章页面读者体验能力的范围界定：目录、阅读时间、相关文章三者分别解决什么问题；
这些能力在 Mizuki 整体"内容 → 构建 → 渲染 → 阅读"流水线中的位置；
可验证的配置入口（astro.config.mjs）与相关文档入口（docs/ 目录）。

有意留给兄弟页面的主题：

内容渲染流水线的完整机制（Markdown 处理、组件渲染细节）——见 docs/CONTENT_RENDERING.md；
内容仓库与文章来源的组织方式——见 docs/CONTENT_REPOSITORY.md；
内容与代码分离的原则——见 docs/CONTENT_SEPARATION.md；
内容创作规范（frontmatter、frontmatter 编辑器）——见 docs/CONTENT_AUTHORING.md 与 docs/editor/；
构建触发与部署——见 docs/AUTO_BUILD_TRIGGER.md 与 docs/DEPLOYMENT.md。

概述

在一个以 Astro 为基础的静态博客中，读者在文章页看到的目录、阅读时间、相关文章都属于构建期产物：它们不是在浏览器中动态计算，而是在站点构建时由文章内容（Markdown / frontmatter）派生并固化进静态 HTML。这类设计的典型动机是：

目录（TOC）：由文章标题层级（h2/h3…）生成锚点结构，让长文可导航；锚点通常依赖渲染时为标题注入的 id。
阅读时间：通常由正文字数 / 字符数除以一个阅读速度常量估算，用于管理读者预期（对中日韩文本与拉丁文本往往需要不同的计数策略）。
相关文章：基于 frontmatter 中的标签 / 分类 / 日期等元数据做相似度或近邻筛选，用于延长站内停留与发现路径。

仓库结构证据表明 Mizuki 采用了明确的内容与渲染分离架构（存在 docs/CONTENT_SEPARATION.md、docs/CONTENT_REPOSITORY.md、docs/CONTENT_RENDERING.md 三份文档），并且存在独立的内容编辑器（docs/editor/editor.html、editor.js、editor.css）与自动构建触发机制（docs/AUTO_BUILD_TRIGGER.md）。这意味着文章元数据（标题层级、标签、日期——即上述三项体验能力的数据来源）在创作阶段即由编辑器与创作规范约束，在渲染阶段被消费。

架构总览

下面的架构图基于可验证的仓库文件结构绘制，节点均对应真实存在的文件 / 文档 / 构建产物；"阅读体验三要素"作为本页主题的输出能力挂在渲染层之后：

Loading diagram...

图中的分层含义：

内容层：文章与其元数据在此产生。编辑器与创作规范约束了 frontmatter 的形状，这是后续"相关文章"筛选所依赖的数据基础。
构建层：内容变更通过自动构建触发进入渲染流水线，astro.config.mjs 是渲染行为的集中配置点（本页已验证其中 frames.showCopyToClipboardButton 一项，见下文配置表）。
读者层：渲染产物即静态文章页面；目录、阅读时间、相关文章是该页面上的三个派生区块。

为什么这样分层：把体验能力全部放在构建期意味着读者浏览器无需执行额外逻辑即可获得完整导航信息，同时站点可保持纯静态、可低成本托管（配合 docs/DEPLOYMENT.md 所述的部署方式）。代价是任何阅读体验逻辑的修改都需要重新构建——这正是仓库配备自动构建触发文档的原因之一。

栺心数据流（概念视图）

下图为概念视图（conceptual view），说明三项体验能力各自的数据来源类型；注意：节点是概念而非源码中的类名，具体实现文件未在本次考察范围内定位到：

Loading diagram...

三项能力的共同点：输入都是"内容仓库中的单篇文章"，输出都是文章页面的一个静态区块。差异在于输入的具体字段——目录消费标题层级，阅读时间消费正文长度，相关文章消费元数据（并可能结合全站文章集合）。

已验证的配置项

以下条目来自本次考察中通过 Grep 直接验证的源码片段，位于 astro.config.mjs 的 frames 配置段：

javascript

		frames: {
			showCopyToClipboardButton: false,
		},

Source: astro.config.mjs

配置项	类型	默认值（仓库当前值）	说明
`frames.showCopyToClipboardButton`	boolean	`false`	控制代码框是否显示"复制到剪贴板"按钮。属于阅读体验类的页面装饰配置，与本页主题同属读者侧体验范畴。

注：astro.config.mjs 文件长度超过 200 行，本次考察预算内未逐行读取全文，因此上表仅列出经直接验证的条目。其余配置项请直接查阅 astro.config.mjs。

文档入口（内容与渲染链路）

仓库 docs/ 目录中与文章页面链路直接相关的文档（文件存在性已通过 ListFiles 验证）：

文档	与本页的关系
docs/CONTENT_RENDERING.md	渲染流水线细节；目录锚点注入、阅读时间计算若有实现应在此链路中
docs/CONTENT_SEPARATION.md	内容与代码分离原则，决定了体验逻辑在渲染层而非内容层实现
docs/CONTENT_REPOSITORY.md	文章来源与元数据组织
docs/CONTENT_AUTHORING.md	frontmatter 创作规范（含 .zh / .tw / .ja 多语言版本），相关文章筛选依赖的字段在此定义
docs/AUTO_BUILD_TRIGGER.md	内容变更后的自动构建触发，是阅读体验改动生效的路径
docs/editor/editor.html	内容编辑器，frontmatter 的录入界面

使用示例

由于本次源码考察未定位到目录 / 阅读时间 / 相关文章的实现源码，本页无法提供这三项能力的真实代码示例（遵循"不虚构代码"原则）。当前唯一可验证的、与读者体验直接相关的代码摘录是上文配置一节中的 astro.config.mjs 片段。

后续若需补充实现级示例，建议的定位路径：在 astro.config.mjs 中检索渲染集成配置（如 Markdown / rehype 插件段），或在 Astro 页面组件目录中检索包含 toc、reading、related 之类标识符的组件文件。

故障模式、边界情况与并发

本节在现有证据下只能给出架构层面的判断，无法引用具体实现代码佐证：

构建期失败：三项能力均在构建期生成，任何计算错误（例如标题层级缺失导致空目录、正文为空导致阅读时间为 0）表现为构建产物缺失或空区块，而非运行时报错；排查入口是渲染流水线（见 docs/CONTENT_RENDERING.md）。
元数据缺失的边界情况：相关文章依赖 frontmatter 元数据（标签 / 分类 / 日期）。当一篇文章缺少这些字段时，相关区块的降级行为（隐藏、显示空、回退到最近文章）取决于实现——该行为未在本次考察中验证。
并发与一致性：纯静态产物不存在读者侧并发问题；需要关注的是构建触发的一致性（同一内容只触发一次构建），相关机制文档见 docs/AUTO_BUILD_TRIGGER.md。

扩展点

新增阅读体验区块：按本仓库的分层，体验逻辑应落在渲染层而非内容层（参见 docs/CONTENT_SEPARATION.md 的分离原则）；配置开关类行为可参考 frames.showCopyToClipboardButton 的做法，集中放在 astro.config.mjs。
调整阅读时间估算：属于纯构建期计算，修改后需经自动构建触发重新生成站点。
扩展相关文章策略：输入字段由创作规范（docs/CONTENT_AUTHORING.md，含多语言版本）与编辑器（docs/editor/）约束；新增筛选维度通常需要同步更新编辑器的 frontmatter 表单。