docs(admin): 后台文档与 hint 补齐 + 修复 config.yml 重复键结构缺陷（5g T6）
- docs/管理台.md 扩写 25→156 行（原文要点全保留，131 增 0 删）：四集合
总表、块编辑九类（字段+示例 yaml+预览限制）、页面排版覆盖（含整页换字体
的体积成本提醒）、theme 17 旋钮分组约束、首页三字段、开源页六字段 +
include 未命中排查 + README 回落矩阵四级（把 T5 的"相对链接不重写/
徽章不阻断"两条限制落到用户文档）
- docs/写作指南.md：首页可配项补三行、新增「页面块」字段速查节（含 ≤24
块/≤4000 字/未知块跳过/空则回落 intro 的边界）、字体子集化段
（694KB→420KB −40% + subset-fonts.py 命令）、加字流程第④步挂子集化
- 后台 hint 49→64：九类块型说明、tagline/blurb、font 下拉体积提醒、scale
取值范围
- **修 config.yml 结构缺陷（重要）**：typography 对象被插进双语字段的
name: 与 widget: object 之间，导致重复键 widget/fields（后者覆盖前者）→
后台 tagline/blurb 退化成字符串写入、排版选择器字段被劫持。已挪到双语
字段之后，恢复 object+zh/en 结构（重复键检测：修前 4 处 → 修后 0）
- 新增 scripts/build-perf/config-check.py：用自定义 StrictLoader 在解析阶段
对重复键报错（Python 默认 safe_load 静默覆盖是本次漏检根因）+ hint 覆盖
率体检；build.sh 守卫挂载（[ -f ] 先行，与既有闸门同级）
验证: 构建 48 页 exit 0；E2E 37/37；content-lint 49 页 0/0/0；对比度闸门
4 项 PASS；config-check 五文件全 OK + 206 字段/64 hint
Spec: 2026-11-02_blog-5g-pages (T6)
Co-authored-by: GLM-5.3
This commit is contained in:
wait4xandGLM-5.3 committed
1 parent
3e09a362cc
commit
8274180f81
6 files changed
+304
-12
No files matched your search
+131
@@ -1,17 +1,148 @@
|
||||
# 管理台（Sveltia CMS）使用指南
|
||||
|
||||
> 地址：`https://wait4x.online/admin/`（页脚「管理」入口）｜ 用途：照片上传与 sidecar 编辑的图形界面 ｜ 保存即 commit 到 main → webhook 自动构建发布（约 10 秒上线）
|
||||
>
|
||||
> 这份是**操作手册**：每个入口能改什么、字段怎么填、改完会发生什么。写文章正文的排版技巧见 [写作指南](./写作指南.md)——两份分工：这里讲"后台怎么用"，那里讲"正文怎么写"。
|
||||
|
||||
## 登录
|
||||
|
||||
选 **Sign In with Token** → 用 gitea 的 access token（宿主 `~/docker_apps/gitea/init-templates.txt` 里的 api-token，或 gitea 网页新建 scope=read/write:repository）。token 存浏览器 localStorage，下次免登。
|
||||
|
||||
## 四类内容集合
|
||||
|
||||
| 入口 | 文件位置 | 用来放什么 | 关键约束 |
|
||||
|---|---|---|---|
|
||||
| 文章 | `content/posts/<slug>.md` | 书评 / 技术文 / 摄影札记三轨 | `category` 三选一（`reading` / `tech` / `photo`），首页分轨由它派生 |
|
||||
| 瞬间 | `content/moments/*.md` | 一句话 + 一张图的时间线 | `text` 与 `image` **至少填一项**（后台无法表达条件必填，保存前自查） |
|
||||
| 照片 | `content/photos/*.json` + 图 | 图库（街拍 / 风景两组） | 标题**必填**（空标题会让构建炸，实测坑）；EXIF 由构建期 loader 自动补全 |
|
||||
| 站点页面 | `content/site/*.yaml` | 首页、关于页、开源页、主题 | 后台改的是**单例文件**，没有"新建" |
|
||||
|
||||
几条通用规则：
|
||||
|
||||
- **双语字段成对出现**：中文 / 英文两个输入框。英文留空不是错误——构建期回落中文并在日志里打 WARN（`[blocks] 缺译…`），页面不会破版。
|
||||
- **留空 = 用默认**：任何字段清空都回到仓库自带的默认文案 / 默认值，构建永远成功。想让某段彻底消失，请看字段自带的"留空则不渲染"提示。
|
||||
- **文章英文版**：不在后台写。跑 `python3 scripts/translate/translate_posts.py` 生成 `content/posts-en/` 同名文件；手写润色过的译文在 frontmatter 写 `locked: true`，翻译脚本会无条件跳过它。
|
||||
- **保存即提交**：后台保存等于向仓库提交，push 后约 10 秒自动构建上线。
|
||||
|
||||
## 照片上传流
|
||||
|
||||
1. 图库照片 → New Entry：填标题（**必填**，空标题会让构建炸——实测坑）、选分组（street/landscape）、可写 alt
|
||||
2. 图片字段 → 资产库上传 jpg（与 sidecar 同目录落位，零重压缩）
|
||||
3. Save → 自动 commit + 构建 → 画廊出现（EXIF 构建期自动提取，exif 字段留空即可）
|
||||
|
||||
## 块编辑：关于页的块式页面构建器
|
||||
|
||||
关于页（`content/site/about.yaml`）的正文由 **blocks 列表**构成，后台里是一串可拖拽排序的卡片。每个块都有「显示」开关；关掉只是不渲染，块本身留在数据里。
|
||||
|
||||
两条渲染纪律：
|
||||
|
||||
- 列表为空（或全关）时，页面回落到 `intro` 字段的 markdown 正文；`intro` 也空则用内置默认文案。三级回落，任何一级为空都不会出白页。
|
||||
- 未知块型（手工编辑 yaml 写错的 `type`）会被**跳过并打印 `[blocks]` 警告**，不会炸构建；块数上限 24，单块文本上限 4000 字，超限截断并 WARN。
|
||||
|
||||
九类块与字段（文本字段一律 `{zh, en}` 双语对象）：
|
||||
|
||||
| 块型 | 必填 | 可选 | 用途 |
|
||||
|---|---|---|---|
|
||||
| `prose` 正文 | `body` | `title`、`width`（`narrow` 版心 / `full` 通栏） | markdown 长文，最常用 |
|
||||
| `tracks` 版图 | `title`、`items[].name` | `items[].icon`、`items[].desc` | 几条主线 / 能力面，图标白名单外或留空显示首字占位 |
|
||||
| `cards` 卡片墙 | `items[].title` | `title`、`columns`（2 或 3，默认 3）、`items[].desc/href/tag` | 并列展示若干条目 |
|
||||
| `timeline` 时间线 | `items[].time`、`items[].title` | `title`、`items[].desc` | 时间列是自由文本（`2024 — 2026` 也行） |
|
||||
| `quote` 引文 | `text` | `cite` | 单句金句，配 `font-kai` 更出效果 |
|
||||
| `figure` 图片 | `image` | `alt`、`caption` | **只能后台上传**（落 `content/site/assets/`，走图片管线），禁止外链 |
|
||||
| `linklist` 链接清单 | `items[].label`、`items[].href` | `title`、`items[].note` | 相关阅读 / 外部资源 |
|
||||
| `cta` 行动按钮 | `text`、`href`、`label` | — | 一页建议不超过一个 |
|
||||
| `divider` 分隔 | — | `style`（`line` 细线 / `space` 纯留白） | 长页分段 |
|
||||
|
||||
yaml 形态示例（手工编辑时照此写）：
|
||||
|
||||
```yaml
|
||||
blocks:
|
||||
- type: prose
|
||||
title: { zh: 关于这个站点, en: About this site }
|
||||
body:
|
||||
zh: 这里写 markdown 正文，支持列表、粗斜体、链接与排版类。
|
||||
en: Markdown body here.
|
||||
width: narrow
|
||||
- type: quote
|
||||
text: { zh: 所谓暮色，就是光慢慢地承认自己要走。, en: Dusk is light admitting it has to go. }
|
||||
cite: { zh: 本站, en: this site }
|
||||
- type: figure
|
||||
image: ./assets/desk.jpg # 后台会替你写成这个相对路径
|
||||
caption: { zh: 工作台一角, en: A corner of the desk }
|
||||
```
|
||||
|
||||
其它可用字段：`layout.showIdCard`（关掉则不渲染名片区，默认开）、`typography`（见下一节）。
|
||||
|
||||
**预览限制**：后台只提供字段编辑与列表摘要（摘要显示块型名），块的真实排版以下次构建后的页面为准——想调间距 / 字号，请用「主题设置」而不是在块里硬凑空行。
|
||||
|
||||
## 页面排版覆盖（每页一处）
|
||||
|
||||
首页 / 关于页 / 开源页各自有一个「页面排版覆盖（可选）」对象：
|
||||
|
||||
| 字段 | 取值 | 说明 |
|
||||
|---|---|---|
|
||||
| `font` | 字族下拉（10 项） | 本页**正文**默认字体类 |
|
||||
| `accent` | 颜色下拉（18 项） | 本页强调色类 |
|
||||
| `scale` | 0.8–1.25 | 字号缩放，1 = 全站默认 |
|
||||
|
||||
- 只作用于**该页内容容器**（挂 `.page-typo` + CSS 变量），不写全站 tokens，其它页面零影响。
|
||||
- **体积成本提醒**：整页换艺术/展示字族（`font-huiwen` 汇文、`font-kuaile` 快乐体）意味着整页正文都要下载对应切片——单页字体成本会明显抬升，见写作指南的体积账。
|
||||
- 白名单外的类名会被忽略（构建期过滤），写错不报错、也不生效。
|
||||
|
||||
## 主题设置（全站 17 个旋钮）
|
||||
|
||||
「主题设置」入口写 `content/site/theme.yaml`，17 项全部可选，留空 = 仓库默认值。**配错不会炸站**：越界值回落默认，组内单调性被破坏则整组回落。
|
||||
|
||||
| 组 | 字段 | 范围 | 约束语义 |
|
||||
|---|---|---|---|
|
||||
| 强调色 | `accent_light` / `accent_dark` | `#rrggbb` | 明暗各一份；构建期对比度闸门断言正文 ≥4.5:1，不达标构建失败 |
|
||||
| 圆角 | `radius_img` | 4–16 | 图片圆角，建议 ≤14 |
|
||||
| 标题字号 | `text_h1` / `text_h2` / `text_h3` | h1/h2：22–32，h3：16–32 | **必须严格递减**（h1 > h2 > h3），否则三档一起回落默认 |
|
||||
| 正文字号 | `prose_size_reading` / `prose_size_tech` | 16–22 | 书评 / 技术文分轨独立 |
|
||||
| 行高 | `leading_reading` / `leading_tech` | 1.5–2.0 | 同上分轨 |
|
||||
| 间距梯度 | `space_3` / `space_4` / `space_5` / `space_6` | 8–80 | **必须严格递增**，否则整组回落 |
|
||||
| 流距 | `flow_p` / `flow_h2_post` | 0–2（em） | 段间距 / 标题下间距 |
|
||||
| 动效 | `dur` | 150–600（ms） | 过渡时长；`prefers-reduced-motion` 下自动归零 |
|
||||
|
||||
不能配的东西（有意为止）：版心宽度、断点、纸墨色、代码配色——它们牵动版面结构与分轨身份，属于设计红线。注入方式是构建期内联 `:root:root{…}`，运行时零 JS、零请求。
|
||||
|
||||
## 首页与开源页的其余旋钮
|
||||
|
||||
### 首页三字段（5g 新增）
|
||||
|
||||
| 字段 | 取值 | 默认 | 作用 |
|
||||
|---|---|---|---|
|
||||
| `projectsLimit` | 1–99 | 6 | 首页项目墙条数（越界夹取） |
|
||||
| `announcement` | `{zh, en}` markdown | 空 | 名片区下方公告；**空 = 不渲染**，走富文本管线（可写排版类 span） |
|
||||
| `postsTracks` | `{reading, tech, photo}` 布尔 | 全开 | 关掉某轨，该轨文章不在首页列出（归档页仍可见） |
|
||||
|
||||
### 开源页（opensource.yaml）
|
||||
|
||||
| 字段 | 取值 | 说明 |
|
||||
|---|---|---|
|
||||
| `pinned` | 仓短名数组 | 置顶顺序即展示顺序 |
|
||||
| `mode` | `all` / `only` / `exclude` | 可见性模式 |
|
||||
| `include` / `exclude` | 仓短名数组 | 对应模式的白 / 黑名单 |
|
||||
| `sort` | `pinned-first` / `stars` / `updated` | 排序 |
|
||||
| `perSource` | `both` / `github` / `gitea` | 来源过滤 |
|
||||
| `intro_from` | `"off"` / `"github-readme"` | 开篇文案来源（**带引号写**，YAML 1.1 里裸 `off` 是布尔 false） |
|
||||
|
||||
**`mode: only` 的"看不见"排查**：构建日志会给每个没显示出来的 include 项打一行 `[opensource] projects：include 里的「X」…`，并区分两种原因——双源结果里根本没有这个仓（拼写 / 私有仓 / 该源刚失败），或者命中了但被 `perSource` 过滤掉。看到哪一行就知道该改什么。
|
||||
|
||||
**README 开篇（`intro_from: "github-readme"`）的回落矩阵**，构建日志逐级点名：
|
||||
|
||||
1. 取到 → 内容有变化才刷新缓存 `content/.github-readme.md`（入仓，保证构建确定性）
|
||||
2. token 缺位 / HTTP 非 2xx / 内容为空 / 超时（10 秒）/ 网络异常 → 改用缓存（日志标注"可能陈旧"）
|
||||
3. 缓存也不在 → 回落本文件 `blurb` 的叙述文案
|
||||
4. 缓存回写失败（构建仓只读挂载等）→ 只告警，本次渲染照常
|
||||
|
||||
token 位在 `~/docker_apps/blog/github-token.txt`（本机，0600）。
|
||||
|
||||
**两条已知限制**：
|
||||
|
||||
- **README 里的相对链接不重写**（如 `./img/x.png`、`docs/foo.md`）：它们相对 GitHub 仓根解析，在本站没有对应产物，点了多半 404。保原样比猜一个基址可信，所以不做改写。
|
||||
- **外部徽章图片加固但不参与构建**：shields.io、readme-typing-svg 这类第三方徽章在构建期**不抓取**，渲染时统一补 `loading="lazy"`（缺 alt 补空），它们慢、被墙或 404 都不影响页面渲染；尺寸已由样式限制在内容宽度内。
|
||||
|
||||
## 纪律（与写作指南同源）
|
||||
|
||||
- **图片体积**：上传前自行压缩（长边 ≤2400px）——Sveltia 内建优化**刻意关闭**（会抹 EXIF 断构建期提取管线）
|
||||
|
||||
Reference in new issue
Block a user