配置字典:文章详情页
区分全站开关、文章字段和界面文案,查询目录、数学、监视器、OUTPUT 与阅读交互。
文章目录
版本说明: 实时响应减弱动画设置,以及文章作者与自动分享图键一致性的修复,从 0.36.1 起提供,0.36.0 不包含。
返回配置字典总入口。先确认字段写在哪个文件:全站功能与文案放在 src/site.config.ts,单篇标题、日期、图片和统计放在 Markdown/MDX 顶部的 frontmatter。不要把两者互换。
本文基于包提供的标准文章路由。它为启用语言生成文章页,按实际内容提供目录、统计、译文链接及最多三篇其他文章;自定义直接调用 BlogPost 的页面需要自己传入相应组件属性,不能期待它自动具有所有路由行为。
1. 全站功能开关
以下字段在 site.config 的 theme 中,类型均为 boolean,主题默认值均为 true。下面每行都提供一段可合并进 theme 的示例,按需要选用,不是建议全部关闭。
| 完整路径 | 作用与生效条件 | 限制与示例 |
|---|---|---|
theme.toc.enabled |
默认显示文章目录,收集编译器提供的二级/三级 Markdown 标题;没有可用标题时不显示 | 单篇 toc: true/false 优先;组件内部或原始 HTML 标题不自动纳入;例 toc: { enabled: false } |
theme.math.enabled |
开启 Markdown/MDX 数学处理;文章正文实际含数学标记时才引入数学样式 | 全局设置,没有单篇 math 开关;错误公式会编译失败,关闭会改变数学解析行为;例 math: { enabled: false } |
theme.effects.enableRedQueen |
显示文章侧面的 Red Queen 监视器 | false 不关闭背景网络、封面 Canvas 或整页 AI 氛围;例 effects: { enableRedQueen: false } |
theme.search.enabled |
开启搜索入口与文章索引生成;完整定义见搜索字典 | 单篇 search: false 可以排除;单篇 true 不能重新开启全站已关闭的搜索;例 search: { enabled: false } |
theme.tags.enabled |
显示文章标签链接,也控制标签目录和标签列表 | false 不删除原 tags 数据;例 tags: { enabled: false };完整范围见列表字典 |
theme.socialImage.enabled |
未明确填写 ogImage 的文章自动生成 1200×630 分享图 | false 不影响手动 ogImage,改为封面或站点默认图回退;不等于隐藏页面封面;例 socialImage: { enabled: false } |
这些字段均为条件生效,受单篇内容、页面区域和所列优先级影响。例如可以只关闭默认目录,保留其他默认行为:
theme: { toc: { enabled: false } },
目录中的三级标题可嵌在二级标题下,孤立三级标题也能作为目录条目。四级及更深标题不进入此目录。正文仍然直接显示,目录不是必须等待的加载步骤。
2. 作者、署名、分享图和评论的关联设置
这些属于通用模块,本节只说明对文章的实际影响:
| 完整路径 | 对文章的影响 | 主说明 |
|---|---|---|
site.author |
单篇 author 省略或空白时的作者回退,也用于生成分享图 | 站点身份 |
theme.enableAboutPage |
开启且文章作者等于站点作者时,作者链接指向该语言 About;否则是纯文字 | About 开关 |
theme.footer.showCredits |
影响自动文章分享图中的主题署名,不修改自定义图片 | 页脚设置 |
site.ogImage |
页面没有更高优先级图片时的站点分享图回退 | 站点身份与图片优先级 |
theme.comments.enabled |
文章评论还需连接参数完整并满足映射约束;没有单篇 frontmatter 评论开关 | Giscus 评论 |
3. 单篇文章字段:不要放进 site.config
以下是文章 frontmatter 的完整 22 项,而不是新增的 site.config 字段。类型描述以作者填写的值为起点;日期会解析为 Date,本地图片会解析为图片元数据。
内容与元信息
| 字段 | 类型与默认行为 | 作用、限制与示例 |
|---|---|---|
title |
必填 string,无默认 | 文章标题及相关元信息,不是全站名称;例 title: '我的笔记' |
description |
必填 string,无默认 | 页面元描述,context 未设置时也用作标题下的上下文;不是整篇正文;例 description: '一次调试的记录。' |
pubDate |
必填可解析日期,无默认 | 发布时间、列表排序及发布元信息;详情以 UTC 日期显示,未来日期不会隐藏文章;例 pubDate: '2026-11-13' |
updatedDate |
可选日期,未设置 | 显示更新日期,sitemap 优先使用它;不代替 pubDate 排序;例 updatedDate: '2026-11-14' |
author |
可选 string,省略或空白使用站点作者 | 不自动创建作者页;例 author: '另一位作者' |
subtitle |
可选 string,未设置 | 显示副标题;与上下文完全相同时不重复显示;例 subtitle: '从现象到定位' |
context |
可选 string,省略使用 description | 标题下上下文文字;空字符串隐藏这行,但不清空元描述;例 context: '解决一个具体问题。' |
tags |
可选 string 数组,未设置时无标签条目 | 链接显示还受全站标签开关控制;例 tags: ['astro', '笔记'] |
heroImage |
可选本地图片路径,未设置时无封面区 | 不能直接用远程 URL 或把 public 网址当作同一规则;例 heroImage: ./cover.jpg,先放入文件 |
ogImage |
可选本地图片/public 路径/HTTPS,省略走分享图回退 | 不改变正文封面;例 ogImage: /images/share.png,先放入文件 |
toc |
可选 boolean,继承全站目录设置 | true 可覆盖全站目录关闭,但没有标题仍不显示;例 toc: false |
search |
可选 boolean,默认 true | false 排除该篇站内搜索,不隐藏文章、RSS、sitemap 或 AI 导出;例 search: false |
开始时可以只写必填字段,再按需要补充:
---
title: '我的笔记'
description: '一次调试的记录。'
pubDate: '2026-11-13'
subtitle: '从现象到定位'
context: '解决一个具体问题。'
tags: ['astro', '笔记']
toc: true
search: true
---
文章没有 draft、定时发布、单篇 comments、单篇 Red Queen 或单篇数学开关。未完成的内容放在内容目录之外,不要把未知字段当成隐私控制。
OUTPUT 统计与状态文字
| 字段 | 类型与默认行为 | 作用、限制与示例 |
|---|---|---|
wordCount |
可选非负整数,默认从正文源文本计算 | 独立覆盖字词数;例 wordCount: 800,不改变 tokenCount |
tokenCount |
可选非负整数,默认 round(max(自动字词数, 1) × 1.3) | 估算而非模型分词器或实际用量;例 tokenCount: 1040 |
aiModel |
可选 string,未设置时无此标签 | 显示在标题状态区及 OUTPUT,不验证真实模型;例 aiModel: '作者填写的模型名' |
aiMode |
可选 string,未设置时无此标签 | 仅显示模式文字,不执行任务;例 aiMode: 'notes' |
aiState |
可选 string,未设置时无此标签 | 仅显示状态文字,不查询服务健康状态;例 aiState: 'edited' |
自动统计会去掉部分 Markdown、代码和链接等内容;CJK 汉字、假名及韩文按字符计,其余主要按空白分词。公式和 MDX 源码仍可能影响估算。只手填 wordCount 不会重算 tokenCount;两者达到 1,000 时以一位小数 k 显示,不修改原始值。
wordCount: 800
tokenCount: 1040
aiModel: '作者填写的模型名'
aiMode: 'notes'
aiState: 'edited'
兼容和当前未使用字段
| 字段 | 类型与默认值 | 状态、限制与示例 |
|---|---|---|
readMinutes |
可选正整数,未填写 | 兼容保留,当前不展示阅读时长;例 readMinutes: 3 不会使页面重新显示它 |
aiLatencyMs |
可选非负整数,未填写 | 兼容保留,当前不展示延迟;例 aiLatencyMs: 150 也不是实际测量 |
aiConfidence |
可选 0–1 的 number,未填写 | 兼容保留,当前不展示置信度;例 aiConfidence: 0.9 不代表文章正确性评估 |
canonicalTopic |
可选 string,未填写 | 当前未使用;例 canonicalTopic: 'astro' 不生成专题、不修改 canonical |
sourceLinks |
可选地址数组,未填写 | 当前只有校验/规范化;接受 HTTP(S),裸域名补 https;例 sourceLinks: ['https://example.com/'] 不会自动显示参考链接或进入导出正文 |
需要读者看到引用来源,直接在正文放 Markdown 链接。旧字段被接受不等于对应界面仍存在,也不需要为了升级删除原内容。
4. 文章界面文案
下面前缀为 i18n.locales.<语言>.messages.blog。字段类型均为可选 string 覆盖,按普通语言文案规则解析;下表列中文/英文内置默认值。示例列是放入对应 blog 对象的单个成员,不是 frontmatter。
所有有效文案均为条件生效,要求对应区域实际出现。空字符串可能清空标签但不会隐藏整个功能;可访问名称不应清空。标记为当前未使用的字段则没有页面效果。
| 字段 | 中文默认 / 英文默认 | 作用与限制 | 状态 | 成员示例 |
|---|---|---|---|---|
rqBadge |
监视器信号 / monitor feed | 监视器徽标;仅 Red Queen 开启时出现,不代表真实监测 | 条件生效 | rqBadge: "监视器信号" |
rqReplayAria |
重放监视器信号 / Replay monitor feed | 监视器重播按钮名称;不修改素材或播放策略 | 条件生效 | rqReplayAria: "重放监视器信号" |
backToTop |
返回顶部 / Back to top | 返回顶部按钮名称;按钮显示受滚动状态影响 | 条件生效 | backToTop: "返回顶部" |
toastP10 |
语境解析 10% / context parsed 10% | 阅读进度早期提示,不是 AI 请求进度 | 条件生效 | toastP10: "语境解析 10%" |
toastP30 |
语境解析 30% / context parsed 30% | 阅读进度提示,不是语义解析结果 | 条件生效 | toastP30: "语境解析 30%" |
toastP60 |
推理稳定 60% / inference stable 60% | 阅读进度提示,不是模型推理状态 | 条件生效 | toastP60: "推理稳定 60%" |
toastDone |
输出完成 / output finalized | 阅读完成阶段提示,不证明生成或校验完成 | 条件生效 | toastDone: "输出完成" |
metaPublished |
发布 / published | 发布时间前的标签,不修改日期 | 条件生效 | metaPublished: "发布" |
metaAuthor |
作者 / by | 作者前的标签,不改变作者值 | 条件生效 | metaAuthor: "作者" |
metaUpdated |
更新 / updated | 更新日期前的标签,只有提供 updatedDate 才显示 | 条件生效 | metaUpdated: "更新" |
systemStatusAria |
模型状态 / Model status | 标题状态区可访问名称,需要至少一个状态字段 | 条件生效 | systemStatusAria: "模型状态" |
systemModelLabel |
模型 / model | 模型标签,aiModel 存在时使用,也用于 OUTPUT | 条件生效 | systemModelLabel: "模型" |
systemModeLabel |
模式 / mode | 模式标签,需要 aiMode | 条件生效 | systemModeLabel: "模式" |
systemStateLabel |
状态 / state | 状态标签,需要 aiState | 条件生效 | systemStateLabel: "状态" |
promptContextLabel |
语境 / Context | 上下文前的标签,需要有非空上下文 | 条件生效 | promptContextLabel: "语境" |
heroMonitor |
神经监视器 / neural monitor | 封面监视器文字,需要 heroImage | 条件生效 | heroMonitor: "神经监视器" |
heroSignalSync |
信号同步中 / signal sync active | 封面信号标记,静态装饰文字,不查询同步状态 | 条件生效 | heroSignalSync: "信号同步中" |
heroModelOnline |
模型在线 / model online | 封面模型标记,静态装饰文字,不查询服务 | 条件生效 | heroModelOnline: "模型在线" |
toc |
文章目录 / On this page | 目录名称,需要目录启用且有可用标题 | 条件生效 | toc: "文章目录" |
responseOutput |
输出 / Output | 正文 OUTPUT 栏名称,不控制正文内容 | 条件生效 | responseOutput: "输出" |
statsWords |
词 / words | 字词数标签,不修改统计值 | 条件生效 | statsWords: "词" |
statsTokens |
令牌 / tokens | tokens 标签,不修改估算 | 条件生效 | statsTokens: "令牌" |
copySectionLink |
复制本节链接 / Copy section link | 正文 h2/h3 章节链接复制名称,不改变锚点算法 | 条件生效 | copySectionLink: "复制本节链接" |
regenerate |
重播扫描 / Replay scan | 重播扫描按钮文字,仅触发视觉效果 | 条件生效 | regenerate: "重播扫描" |
relatedAria |
相关文章 / Related posts | 相关文章区域的可访问名称,需要有其他文章 | 条件生效 | relatedAria: "相关文章" |
related |
相关文章 / Related | 相关文章区标题,不控制推荐算法 | 条件生效 | related: "相关文章" |
backToBlogAria |
返回博客 / Back to blog | 返回博客导航的可访问名称 | 条件生效 | backToBlogAria: "返回博客" |
backToBlog |
返回博客 / Back to blog | 返回博客链接的可见文字,不改变链接目标 | 条件生效 | backToBlog: "返回博客" |
comments |
评论 / Comments | 评论区域可访问名称,需要文章评论配置有效 | 条件生效 | comments: "评论" |
metaReadMinutes |
分钟阅读 / min read | 当前未使用;改此文案不会恢复阅读时长 | 当前未使用 | metaReadMinutes: "分钟阅读" |
latencyLabel |
延迟估计 / latency est | 当前未使用;改此文案不会恢复延迟 | 当前未使用 | latencyLabel: "延迟估计" |
confidenceLabel |
置信度 / confidence | 当前未使用;改此文案不会恢复置信度 | 当前未使用 | confidenceLabel: "置信度" |
这些状态、封面标记和滚动提示主要表达界面氛围,不能当作真实 AI 模型在线、网络同步或准确率检测结果。regenerate 对应的按钮只重播扫描视觉效果,不改写文章、不请求 AI 服务。
例如修改 OUTPUT 和复制章节链接的文案:
i18n: {
locales: {
zh: {
messages: {
blog: {
responseOutput: '正文',
statsWords: '字词',
statsTokens: '估算 tokens',
copySectionLink: '复制这一节的网址',
regenerate: '重播扫描效果',
},
},
},
},
},
返回博客链接的实际目的地仍是当前语言的博客列表;修改文字不会改链接。相关文章当前取同语言中排除本篇后的最新最多三篇,不是 AI 相似度推荐,也没有数量或相似度配置字段。字段 related/relatedAria 只改变文字及可访问名称。
代码复制与图片预览的文字
前缀改为 i18n.locales.<语言>.messages,以下每项也都是可选 string 覆盖和条件生效;不会改变复制权限、图片来源或添加功能开关。
| 路径末段 | 中文默认 / 英文默认 | 作用与限制 | 成员示例 |
|---|---|---|---|
codeCopy.copy |
复制代码 / Copy code | 代码块复制按钮文字,不修改被复制内容 | codeCopy: { copy: "复制代码" } |
codeCopy.copied |
已复制 / Copied | 代码及章节链接复制成功提示 | codeCopy: { copied: "已复制" } |
codeCopy.failed |
复制失败,请手动选择代码。 / Copy failed. Select the code manually. | 代码及章节链接复制失败提示,不授予剪贴板权限 | codeCopy: { failed: "复制失败,请手动选择代码。" } |
imagePreview.open |
查看大图 / View image | 图片预览入口和弹窗的可访问名称 | imagePreview: { open: "查看大图" } |
imagePreview.close |
关闭图片预览 / Close image preview | 关闭图片预览按钮名称,不修改图片源 | imagePreview: { close: "关闭图片预览" } |
i18n: {
locales: {
zh: {
messages: {
codeCopy: { copy: '复制内容', copied: '复制好了', failed: '无法复制,请手动选择。' },
imagePreview: { open: '放大这张图片', close: '收起图片' },
},
},
},
},
复制章节链接只给正文中有 id 的 h2/h3 添加按钮,成功/失败复用 codeCopy.copied/failed。代码复制和图片预览需要 JavaScript;普通正文图片预览不包括封面或链接/按钮里的图片,放大复用浏览器选中的源,不另外请求高清原图。它们没有 site.config 的 enabled 字段。
5. 当前配置边界与验证
文章页会实时响应系统的“减弱动画”偏好,无需刷新。开启后,封面与背景网络使用静态呈现,Red Queen 停止并隐藏;关闭后按原有启动节奏恢复。切换不会重置阅读进度或重绑代码复制、章节链接和图片预览,也没有新增 site.config 开关。
正文和正文面板直接出现并保持静止;背景网络、标题光带和封面效果独立存在。当前没有全站 AI 主题切换、正文入场时长、面板呼吸、相关文章数量、图片预览 enabled 或代码复制 enabled 等公开配置。不要靠添加任意同名键期待生效。
locale、articleSlug、headings、filePath、related、localeHrefs 和 seoLocaleHrefs 是 BlogPost 组件调用属性,不是 site.config 或文章 frontmatter;标准路由会提供对应数据。新建普通文章不需要手工填写这些属性。
先在 dev 查看有标题/无标题、有封面/无封面等实际内容下的结果;代码复制、章节链接和图片预览自行检查交互。搜索在构建后的 preview 验证。发布前停止 dev,运行 npm run doctor 再 npm run preview,成功后无需紧接着重复 check 或 build;重新部署后线上才更新。