docs(content): story 字段/页面说明文案/隐藏语义同步到指南(5j T5)

- 管理台:开源页「叙述已合一」(推荐改 story 单字段,旧字段标 legacy)、
  新增「页面说明文案」一节(瞬间/书架标题下话语 + 三档样式 + 兜底行为)、
  置顶语义补「隐藏优先」与「多本置顶在书架的默认展开」
- 写作指南:新增「隐藏文章」一节(hidden: true / tags 两种写法、页面仍生成、
  与草稿的区别、隐藏与置顶同开以隐藏为准)

验证: pnpm astro build exit 0

Spec: 2026-11-03_blog-5j-content-refine (T5)

Co-authored-by: GLM-5.3
This commit is contained in:
wait4xandGLM-5.3 committed 2026-11-04 22:16:22 +08:00
1 parent e5f2d0089e
commit a2b5755680
4 files changed
+26 -6

No files matched your search

@@ -37,7 +37,7 @@
- [ ] T1 开源页叙述合一:`story` 单字段 markdown(内联链接),旧 `blurb/blurb_after` 作为兼容回落 - [ ] T1 开源页叙述合一:`story` 单字段 markdown(内联链接),旧 `blurb/blurb_after` 作为兼容回落
- [ ] T2 贡献数据去重与时效:删除贡献蛇块与抓取;连续贡献改为热力图同源本地计算(当前/最长/总计)+ 数据时间标注 - [ ] T2 贡献数据去重与时效:删除贡献蛇块与抓取;连续贡献改为热力图同源本地计算(当前/最长/总计)+ 数据时间标注
- [ ] T3 页面文案可编辑:新增 `content/site/pages.yaml` 单例(瞬间/书架 note 双语 + 字号/颜色/字体),两页消费,后台可改 - [ ] T3 页面文案可编辑:新增 `content/site/pages.yaml` 单例(瞬间/书架 note 双语 + 字号/颜色/字体),两页消费,后台可改
- [ ] T4 关于页 5 案预览页(供用户选型),选定后落地并把 blocks 降级为可选 - [x] T4 关于页形态探索 → 拆分为独立包 `2026-11-03_blog-5k-about-designs`(2026-11-04 重划:关于页是内容选型决策,需用户在预览页里选,与本包工程主线不同节奏,独立成包避免阻塞上线)
- [ ] T5 文档与后台 hint 同步 - [ ] T5 文档与后台 hint 同步
### 3.2 扩展功能 ### 3.2 扩展功能
@@ -69,7 +69,7 @@
- [ ] 开源页叙述为单段富文本且可内联链接,旧 yaml 零回归 -> verify: task_0001 - [ ] 开源页叙述为单段富文本且可内联链接,旧 yaml 零回归 -> verify: task_0001
- [ ] 贡献蛇消失、连续贡献由本地计算并显示更新时间 -> verify: task_0002 - [ ] 贡献蛇消失、连续贡献由本地计算并显示更新时间 -> verify: task_0002
- [ ] 瞬间/书架标题下话语可从后台改,字号/颜色/字体生效 -> verify: task_0003 - [ ] 瞬间/书架标题下话语可从后台改,字号/颜色/字体生效 -> verify: task_0003
- [ ] 关于页 5 案预览可访问,用户选定 -> verify: task_0004 - [x] 关于页形态探索拆分为独立包 5k,不阻塞本包 -> (重划说明,无独立验证)
- [ ] 文档与后台 hint 同步(无过时字段说明) -> verify: task_0005 - [ ] 文档与后台 hint 同步(无过时字段说明) -> verify: task_0005
## 7. 风险与约束 ## 7. 风险与约束
@@ -22,10 +22,7 @@
- boundary: `src/components/pages/MomentsPage.astro`(改用可配置 note,替换 i18n 硬编码)、`src/components/pages/BooksPage.astro`(同上,替换字面量 `L.note`)、`src/lib/site-content.ts`(新增 `pageNote(page, locale)` 访问器:文本 + 字号 + 颜色 token + 字体类)、`content/site/pages.yaml`(新单例,由 orchestrator 建 schema/后台,车道可先写默认值) - boundary: `src/components/pages/MomentsPage.astro`(改用可配置 note,替换 i18n 硬编码)、`src/components/pages/BooksPage.astro`(同上,替换字面量 `L.note`)、`src/lib/site-content.ts`(新增 `pageNote(page, locale)` 访问器:文本 + 字号 + 颜色 token + 字体类)、`content/site/pages.yaml`(新单例,由 orchestrator 建 schema/后台,车道可先写默认值)
- verify: `grep -q "pageNote" src/lib/site-content.ts && grep -q "pages.yaml" src/content.config.ts && E2E_BASE=http://127.0.0.1:18925 node tests/e2e.mjs 2>&1 | grep -qE "汇总: [0-9]+/[0-9]+ PASS"` - verify: `grep -q "pageNote" src/lib/site-content.ts && grep -q "pages.yaml" src/content.config.ts && E2E_BASE=http://127.0.0.1:18925 node tests/e2e.mjs 2>&1 | grep -qE "汇总: [0-9]+/[0-9]+ PASS"`
- [ ] T4 关于页 5 案预览与落地 - [x] T4 关于页形态探索 → **拆分为独立包** `2026-11-03_blog-5k-about-designs`(2026-11-04 重划:关于页是"整页 markdown 直编 vs 结构化方案"的内容决策,需要用户在预览页里选型,与本包"叙述合一/贡献数据/页面文案"的工程主线不同节奏;独立成包避免阻塞本包上线)
- claim: orchestrator
- boundary: `src/pages/about-preview.astro`(新,一次性预览路由)、`src/components/pages/AboutPage.astro`、`content/site/about.yaml`
- verify: `test -f src/pages/about-preview.astro && E2E_BASE=http://127.0.0.1:18925 node tests/e2e.mjs 2>&1 | grep -qE "汇总: [0-9]+/[0-9]+ PASS"`
- [ ] T5 文档与后台 hint - [ ] T5 文档与后台 hint
- claim: orchestrator - claim: orchestrator
+9
View File
@@ -18,6 +18,15 @@ cp content/posts/writing-template.md content/posts/my-new-post.md
- **整页换字族要谨慎**:会给访问者拉一份中文字体(汇文明朝整页约 420KB,已子集化) - **整页换字族要谨慎**:会给访问者拉一份中文字体(汇文明朝整页约 420KB,已子集化)
- **折叠放细节不放结论**:`<details>` 里的内容可能永远没人展开 - **折叠放细节不放结论**:`<details>` 里的内容可能永远没人展开
## 隐藏文章(两种写法,任选其一)
不想让某篇出现在首页/归档/书架/RSS/sitemap:
- frontmatter 写 `hidden: true`(后台有开关)
- 或在 `tags` 里加一个 `hidden`
页面本身仍会生成,链接可以直接分享给别人;想连页面都不生成,用 `draft: true`(草稿)。
**隐藏与置顶同开时,以隐藏为准**(2026-11-04 修复:此前隐藏开关是假的,隐藏+置顶会照样显示还排第一)。
## 置顶文章 ## 置顶文章
首页、归档、书架三处列表默认按日期倒序。想让某篇长期排在最前,frontmatter 加一行: 首页、归档、书架三处列表默认按日期倒序。想让某篇长期排在最前,frontmatter 加一行:
+14
View File
@@ -24,13 +24,23 @@
- **文章英文版**:不在后台写。跑 `python3 scripts/translate/translate_posts.py` 生成 `content/posts-en/` 同名文件;手写润色过的译文在 frontmatter 写 `locked: true`,翻译脚本会无条件跳过它。 - **文章英文版**:不在后台写。跑 `python3 scripts/translate/translate_posts.py` 生成 `content/posts-en/` 同名文件;手写润色过的译文在 frontmatter 写 `locked: true`,翻译脚本会无条件跳过它。
- **保存即提交**:后台保存等于向仓库提交,push 后约 10 秒自动构建上线。 - **保存即提交**:后台保存等于向仓库提交,push 后约 10 秒自动构建上线。
## 页面说明文案(5j 新增:瞬间 / 书架)
「页面文案」里新增「瞬间 / 书架 标题下的说明」:那一行字的文字(markdown,支持排版类)、
字号(11–16)、颜色(灰阶四级)、字体(12 族下拉)都在这里改,两页互相独立。
兜底行为:任何字段清空/删掉都回落内置默认;越界值(如字号填 40、颜色乱写)
会被自动夹取或回落,不会破版。
## 文章置顶(5h 新增) ## 文章置顶(5h 新增)
文章编辑页有一个「置顶」开关。打开后这篇文章排在首页分轨、归档、书架三处列表的最前面,列表里显示一个灰阶「置顶」小徽标。 文章编辑页有一个「置顶」开关。打开后这篇文章排在首页分轨、归档、书架三处列表的最前面,列表里显示一个灰阶「置顶」小徽标。
语义边界(刻意如此,别当 bug 报): 语义边界(刻意如此,别当 bug 报):
- **只影响列表顺序**:`pubDate` 不变、URL 不变、RSS 里的时间序列不变,订阅者不会看到时间错乱 - **只影响列表顺序**:`pubDate` 不变、URL 不变、RSS 里的时间序列不变,订阅者不会看到时间错乱
- **与「隐藏」同开时以隐藏为准**:后台的「隐藏」开关(5j 起是真字段)会把这篇从列表/RSS/sitemap 里拿掉,页面本身仍可分享
- **支持多篇/多本同时置顶**:置顶组内部仍按日期倒序;书架页(/books)里每个置顶的书评都会排在前面并**默认展开** - **支持多篇/多本同时置顶**:置顶组内部仍按日期倒序;书架页(/books)里每个置顶的书评都会排在前面并**默认展开**
- **置顶 + 隐藏同时打开时,以隐藏为准**(5j 修复:此前隐藏开关只写一个没人读的字段,导致隐藏+置顶的文章照样显示还排第一)
- 书架页用「↑ + 横线」的回到顶部图标表示置顶(不写文字),与右侧展开箭头形状不同,不会混读 - 书架页用「↑ + 横线」的回到顶部图标表示置顶(不写文字),与右侧展开箭头形状不同,不会混读
- 关掉开关立即恢复时间序,没有"冷却期" - 关掉开关立即恢复时间序,没有"冷却期"
@@ -153,6 +163,10 @@ blocks:
| `postsTracks` | `{reading, tech, photo}` 布尔 | 全开 | 关掉某轨,该轨文章不在首页列出(归档页仍可见) | | `postsTracks` | `{reading, tech, photo}` 布尔 | 全开 | 关掉某轨,该轨文章不在首页列出(归档页仍可见) |
### 开源页(opensource.yaml) ### 开源页(opensource.yaml)
**叙述已合一(5j 起)**:改用「叙述(推荐改这里)」这一个字段,整段写成 markdown,
链接直接内联(`[文字](url)`),不再分"链接前/链接后"。旧的两个字段(链接前/链接后)
只是 legacy——仅当「叙述」为空时才会退回旧拼接,平时不用管它们。
**开篇是原生「GitHub 档案卡」(5h 起)**:头像 / 名字@handle / 定位叙述 / 社交图标 / 统计四格(关注者、公开仓、总星标)/ 语言占比灰阶条(只有第一名用强调色,其余灰阶)。**零第三方图片、零 iframe**。数据失败只隐藏对应数字,不会破版。 **开篇是原生「GitHub 档案卡」(5h 起)**:头像 / 名字@handle / 定位叙述 / 社交图标 / 统计四格(关注者、公开仓、总星标)/ 语言占比灰阶条(只有第一名用强调色,其余灰阶)。**零第三方图片、零 iframe**。数据失败只隐藏对应数字,不会破版。