配置字典:Fragments
碎片列表、首页预览、独立评论与稳定链接。
文章目录
想先发一条内容,读发布一条碎片;这里用于查配置。安装与配置文件的位置见第一篇教程,所有模块从配置字典总入口进入。
本文默认值指主题包默认值,不是演示站当前配置。所有配置片段都合并进 src/site.config.ts 现有的 defineThemeConfig({...});不要重复创建 theme 或 i18n。
先找到要改的位置
| 想改什么 | 配置路径或位置 |
|---|---|
| 开启碎片列表和首页入口 | theme.fragments.enabled |
| 完整列表每页条数 | theme.fragments.pageSize |
| 碎片独立评论 | theme.fragments.comments.enabled,连接参数共用 theme.comments |
| 标题、描述、提示和关闭文案 | i18n.locales.<语言>.messages.fragments |
| 页码和跳页交互 | theme.pagination,文案使用 messages.blog |
| 单条内容的 ID、时间和标题 | Markdown frontmatter,不是 site.config |
| 首页显示几条、预览高度、头像 | 当前没有对应公开配置字段 |
theme.fragments.enabled:开启碎片
- 类型 / 默认值: boolean /
false。 - 状态 / 作用: 生效。开启后加载
src/content/fragments/<语言>/**/*.md,生成启用语言的碎片列表和定位索引;首页有该语言内容时显示碎片入口。 - 限制: 关闭后不加载碎片集合,也不生成对应列表路由。文件仍保留。开启但没有内容时,列表显示空状态,首页不显示入口。只读取
.md,不读取.mdx。 - 示例:
theme: { fragments: { enabled: true } }。
列表首页是 /<语言>/fragments/,第二页起是 /<语言>/fragments/2/ 等;不要自行添加首页 /1/。语言必须先启用,见多语言教程。
theme.fragments.enabled: false 时,dev、build 和 prepare-covers/doctor 跳过碎片正文中的图片引用;仅由这些引用纳入处理的图片不再要求原图或派生文件存在。文章封面引用,以及 src/assets/blog/default-covers/、src/assets/blog/covers/originals/ 两个来源池仍正常准备和校验,即使某张图只用于碎片。关闭不会删除文件,重新开启后恢复碎片图片准备与检查。
版本说明: 上述关闭后的图片隔离从 0.36.1 起提供,0.36.0 不包含;不要视为旧版本已有的行为。
theme.fragments.pageSize:完整列表每页数量
- 类型 / 默认值: number /
20。 - 状态 / 作用: 生效,控制完整列表分页和 ID 到页码的定位索引。
- 限制: 必须是 1–100 的安全整数,小数、0、负数及超出范围会报错,不会自动截断。即使碎片关闭,填写的 pageSize 也会被校验。首页预览仍固定取最新三条,不受此字段或
theme.homeLatestCount影响。 - 示例:
theme: { fragments: { pageSize: 10 } }。
同一语言内先按 pubDate 从新到旧排序;时间相同时再按 ID 的 localeCompare 结果排序。没有按文件名排序,也没有自动排除未来日期。调整每页条数会改变内容所在页,分享时使用下面的稳定链接。
theme.fragments.comments.enabled:碎片评论
- 类型 / 默认值: boolean /
false。 - 状态 / 作用: 条件生效。碎片功能开启后,在完整列表的每条卡片中显示评论按钮,点击打开共用弹窗并加载该条讨论。首页预览不显示评论按钮。
- 限制: 独立于
theme.comments.enabled(文章评论开关)。必须同时配置共用 Giscus 连接参数;缺失会在生成碎片页面时抛错,不能靠空列表绕过。Giscus 服务与仓库权限仍需正确设置。 - 示例:
theme: { fragments: { enabled: true, comments: { enabled: true } } }。
只开碎片、不启用评论:
theme: {
fragments: {
enabled: true,
pageSize: 10,
comments: { enabled: false },
},
},
只开碎片评论时,文章开关可保持 false,但仍须配置公共的 repo、repoId、category、categoryId。四项参数的类型、默认值和校验统一见Giscus 连接参数;可直接合并的完整示例见仅开启碎片评论。主题本地检查不能证明远端权限或 ID 正确。
碎片以 fragment/<稳定ID> 绑定讨论,同 ID 的多语言内容共享讨论。此绑定不使用文章的 mapping、term、number 或 shareAcrossLocales 设置;碎片固定 specific 映射、strict 为 '1'、emitMetadata 为 '1',语言跟随页面,不使用 theme.comments.lang。如果同时开启文章评论,文章配置自身的校验仍然执行。
评论主题、反应和输入框位置继续共用 Giscus 设置;完整操作见评论教程。第一次点击才插入 Giscus 脚本;这里的 loading 固定 eager,指点击之后立即加载,不是首屏提前加载。关闭弹窗保留已创建的 iframe;换一条内容时切换讨论。约 15 秒无有效加载响应时显示失败与重试界面,没有公开超时配置。
碎片界面文案:messages.fragments
完整前缀是 i18n.locales.<语言>.messages.fragments。下面每个字段都是 string,只改文案,不改变功能。默认使用内置当前语言文案,并遵循语言回退;表中只列中文 / 英文默认值。省略字段保留默认文案,空字符串是主动覆盖,不保证对应控件消失。示例列写在 fragments 对象内。
| 字段 | 中文 / 英文默认值 | 状态、作用与限制 | 示例 |
|---|---|---|---|
title |
碎片 / Fragments | 条件生效:列表标题、页面标题的一部分、首页入口的无障碍名称;不是单条标题 | title: '随手记' |
description |
沿途记录的几句话。 / Brief thoughts, kept along the way. | 条件生效:列表可见介绍及页面描述;首页展开窗口不显示此介绍 | description: '记录工作与生活的小事。' |
empty |
还没有碎片。 / No fragments yet. | 条件生效:完整列表没有内容时的提示,不会强制显示首页入口 | empty: '稍后再来看看。' |
comments |
评论 / Comments | 条件生效:开启碎片评论后的按钮文字 | comments: '参与讨论' |
close |
关闭 / Close | 条件生效:评论弹窗关闭文字及首页窗口关闭按钮的无障碍名称 | close: '关闭窗口' |
previous |
上一页 / Previous | 当前未使用:类型仍接受,实际分页使用 messages.blog.previous | previous: '上一页' |
next |
下一页 / Next | 当前未使用:类型仍接受,实际分页使用 messages.blog.next | next: '下一页' |
loading |
正在加载评论… / Loading comments… | 条件生效:评论加载状态 | loading: '正在连接讨论…' |
error |
评论未能加载,请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. | 条件生效:评论加载失败提示,不是定位索引错误 | error: '讨论暂时不可用,请重试。' |
retry |
重试 / Retry | 条件生效:评论加载失败后的重试按钮 | retry: '重新连接' |
copyLink |
复制碎片链接 / Copy fragment link | 条件生效:分享链接按钮的标题和无障碍名称,按钮由脚本启用 | copyLink: '复制本条链接' |
linkCopied |
链接已复制 / Link copied | 条件生效:复制成功提示 | linkCopied: '已复制' |
copyLinkFailed |
未能自动复制,请复制下方链接。 / Unable to copy automatically. Copy the link below. | 条件生效:剪贴板复制失败,提示手动复制 | copyLinkFailed: '请手动复制此链接。' |
notFound |
找不到这条碎片,它可能已被移除。 / Fragment not found. It may have been removed. | 条件生效:稳定 ID 定位失败,不是通用 404 文案 | notFound: '这条记录已不存在。' |
indexError |
暂时无法定位这条碎片,请刷新页面后重试。 / Unable to locate this fragment. Refresh the page and try again. | 条件生效:定位索引请求或校验失败 | indexError: '定位失败,请刷新重试。' |
例如只覆盖中文的标题和描述:
i18n: {
locales: {
zh: {
messages: {
fragments: {
title: '随手记',
description: '记录工作与生活的小事。',
},
},
},
},
},
Fragments 还会用到哪些通用配置?
| 路径 | 默认值与作用 | 限制、示例与完整说明 |
|---|---|---|
theme.pagination.* |
共用 Blog List 的八个分页字段及默认值 | 多于一页才显示分页;如 theme: { pagination: { windowSize: 5 } }。类型、范围和逐字段示例见分页设置及其后各节 |
i18n.locales.<语言>.messages.blog.previous、next、paginationAria、jumpTo、jumpInputLabel、jumpGo |
string,内置当前语言文案,控制碎片分页的可见及无障碍文字 | 如 previous: '上一页';见分页文案字典,不要改同名 fragments 字段 |
i18n.locales.<语言>.messages.blog.backToTop |
string,内置当前语言文案 | 完整列表返回顶部按钮;如 backToTop: '回到顶部',见文章界面文案 |
i18n.locales.<语言>.messages.home.viewAll |
string,内置当前语言文案 | 首页窗口底部归档链接的无障碍名称还会结合碎片标题;如 viewAll: '查看全部',见首页文案 |
theme.math.enabled |
boolean / true |
完整列表按当前页内容决定是否需要数学样式;如 theme: { math: { enabled: false } },见数学开关 |
theme.comments 的完整公共参数见Giscus 评论字典;本篇明确列出碎片需要的连接字段和绑定差异,不把文章的映射设置当成碎片配置。theme.toc.enabled、文章 OUTPUT、Red Queen 等文章功能不控制碎片列表;碎片也没有 Blog List 的 Cards/List 切换。
单条碎片的三个 frontmatter 字段
这是 src/content/fragments/<语言>/ 下 Markdown 文件的字段,不写进 site.config。当前公开 schema 只有以下三项,没有额外的兼容字段。
| 字段 | 类型 / 默认值 | 作用、状态与限制 | 示例 |
|---|---|---|---|
id |
string / 无,必填 | 生效。恰好 8 位 ASCII 英文字母或数字;同一语言内不能重复。链接和评论都依赖它,发布后保持不变 | id: 'aB3dE6gH' |
pubDate |
可转换为 Date 的日期值 / 无,必填 | 生效。必须能解析成日期;决定排序,列表按 UTC 展示。推荐带时区的 ISO 字符串,避免日期歧义 | pubDate: '2026-11-13T08:00:00.000Z' |
title |
string,可省略 / 未设置 | 条件生效。可选的卡片标题,同时用于首页预览;不填也能发布,不会自动取文件名作为标题 | title: '今天的小发现' |
---
id: 'aB3dE6gH'
pubDate: '2026-11-13T08:00:00.000Z'
title: '今天的小发现'
---
这里写正文。图片和代码直接放在 Markdown 正文中。
使用 npm run new-fragment -- --locales zh,en 会生成一组共享新 ID 和当前时间的文件。每次运行都生成新的 ID;补译已有碎片时应沿用原 ID,不要重新生成身份。不同语言可以使用同一个 ID;同一语言重复会报错。文件名可改变,ID 不应随文件名或页码改变。旧格式 ID 不会自动迁移,随意改 ID 会改变评论绑定和分享地址。
description、heroImage、tags、draft、单条 comments 等没有对应的碎片配置消费逻辑,不要套用文章 frontmatter。特别是添加 draft: true 不能让碎片变成草稿;不要把尚未公开的内容放进启用的集合。
首页预览、图片和链接的固定行为
这些行为由实现决定,当前没有额外公开字段:
- 首页条数: 当前语言最新三条,不足三条就显示实际数量。底部是“当前显示条数 / 当前语言总数”的归档链接;不会读取其他语言补足数量。
- 首页摘要: 从渲染后的内容提取文字、第一张可用 HTTP(S) 图片及第一个代码块。文字最多 180 个 Unicode 码点;代码最多 8 行、800 个码点,超出追加省略号。窗口卡片限制预览高度,超出的部分不展示;完整内容仍在列表中。标题单独显示。不是完整 Markdown 渲染,也没有可配置的 previewCount 或 previewHeight。
- 图片: 支持处理的本地图片通过已有图片清单提供尺寸和 srcset;远程或不支持处理的图片不保证自动优化。完整列表每页第一张图片 eager / high,其余图片 lazy,统一异步解码。准备原图、生成尺寸和检查产物见图片教程,不需要手动给碎片添加 heroImage。
- 稳定链接: 分享地址是
/<语言>/fragments/#<ID>。脚本通过定位索引找到当前页,必要时跳转;新增内容或调整 pageSize 后仍按 ID 定位。删除内容或改 ID 无法保留原目标。关闭 JavaScript 后普通分页仍可使用,跨页自动定位与复制按钮不可依赖。 - 语言切换: 列表的语言切换链接进入目标语言的碎片首页,不保证直接定位同 ID 的译文。
- 公开内容: 碎片 Markdown 聚合出口是
/<语言>/fragments/index.md。它不是站内搜索或文章 RSS 的启用开关;公开内容不要放敏感信息。
首页头像、悬停动画、窗口边框和代码预览高度目前不是 site.config 配置项;字典不提供不存在的设置。返回配置总入口查其他模块。