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:
1 parent
3e09a362cc
commit
8274180f81
6 files changed
+304
-12
No files matched your search
+44
-1
@@ -153,6 +153,18 @@ https://astro.build/
|
||||
|
||||
体积账结论(2026-11-02 实测,本地无 gzip 的相对值):**未使用某字体的页面,字体字节增量恒为 0**(构建期按页子集化 + unicode-range 按需拉取)。汇文采用文风开源的 cn-font-split 切片包(339 片),实测只拉用到字符的 19 片。
|
||||
|
||||
**再裁一刀(按本站实际用字子集化)**:切片包本身粒度粗(一片含数百字),只做标题/短句的艺术字体往往只用到几十个字符。`scripts/build-perf/subset-fonts.py` 读字体 CSS 的 `@font-face`、收集内容里真实出现的字符、逐片求交集后用 `pyftsubset` 重写——实测汇文整页 **694KB → 420KB**(约 −40%)。命令:
|
||||
|
||||
```bash
|
||||
python3 scripts/build-perf/subset-fonts.py \
|
||||
--css node_modules/@fontsource/huiwen-mincho/index.css \
|
||||
--out public/fonts/subset/huiwen \
|
||||
--chars-from content/posts content/moments content/site/*.yaml
|
||||
# 可选:--chars-mode all|headings(只统计标题字)、--min-bytes 4096(小于该值的片不裁)
|
||||
```
|
||||
|
||||
子集化产物输出到 `--out` 指定目录(如 `public/fonts/subset/`);把它接进站点(构建链挂守卫 + 字体 CSS 指向子集)是独立一步,接线后随构建自动生成,未接线前需手动跑。**换字/加字后重跑一次**,否则新字会回落到下一个切片或系统字体。
|
||||
|
||||
### 候补字体清单(未落地,加一款约"一条命令 + 一次体积账")
|
||||
|
||||
| 字体 | 许可证 | 允许 webfont 嵌入 | 未落地原因 |
|
||||
@@ -168,7 +180,7 @@ https://astro.build/
|
||||
| 阿里妈妈东方大楷 / 演示悠然小楷 | 免费商用 / 个人免费 | ⚠️ 需逐款核嵌入条款 | 无包;"个人免费"字体常禁 @font-face |
|
||||
| 霞鹜文楷 Light/Bright | OFL-1.1 | ✅ | 实测 **+8605KB**(CJK 切片粒度所致) |
|
||||
|
||||
> 加新字体的流程:①核许可证与 **web 嵌入条款**(很多"个人免费"字体明文禁 @font-face,只能进系统回退)②npm 装或放入 `public/fonts/<family>/`(优选 cn-font-split 类切片包)③`global.css` 加类 + `rehype-class-whitelist` 放行 + `public/admin/typography-classes.js` 加一项 ④跑体积账,超 150KB/页 的要评估是否值得。
|
||||
> 加新字体的流程:①核许可证与 **web 嵌入条款**(很多"个人免费"字体明文禁 @font-face,只能进系统回退)②npm 装或放入 `public/fonts/<family>/`(优选 cn-font-split 类切片包)③`global.css` 加类 + `rehype-class-whitelist` 放行 + `public/admin/typography-classes.js` 加一项 ④跑体积账,超 150KB/页 的要评估是否值得;展示类字体再跑一次 `scripts/build-perf/subset-fonts.py` 按实际用字裁切(命令见上节)。
|
||||
|
||||
```markdown
|
||||
<span class="ink-muted">次要说明</span>
|
||||
@@ -211,6 +223,34 @@ typography:
|
||||
|
||||
**层 3 · 艺术字体**:`font-art-kuaile`(站酷快乐体,艺术字专用类)。⚠️ **仅用于标题/短句**:艺术字字形大,CJK 切片体积高(实测用到页 +163KB),长段使用会显著抬高单页字体成本。
|
||||
|
||||
## 页面块(关于页 blocks,字段速查)
|
||||
|
||||
关于页正文可由九个块拼成(后台拖拽排序,每块有「显示」开关)。完整操作见 [管理台](./管理台.md);这里是写内容时对照的字段表——文本字段一律 `{zh, en}`。
|
||||
|
||||
| 块型 | 必填 | 可选 | 一句话 |
|
||||
|---|---|---|---|
|
||||
| `prose` | `body` | `title`、`width`(narrow/full) | markdown 长文 |
|
||||
| `tracks` | `title`、`items[].name` | `items[].icon`、`items[].desc` | 主线/能力面 |
|
||||
| `cards` | `items[].title` | `title`、`columns`(2/3)、`items[].desc/href/tag` | 并列卡片墙 |
|
||||
| `timeline` | `items[].time`、`items[].title` | `title`、`items[].desc` | 时间线(时间可自由文本) |
|
||||
| `quote` | `text` | `cite` | 单句引文 |
|
||||
| `figure` | `image` | `alt`、`caption` | 单图(必须上传,禁外链) |
|
||||
| `linklist` | `items[].label`、`items[].href` | `title`、`items[].note` | 链接清单 |
|
||||
| `cta` | `text`、`href`、`label` | — | 行动按钮 |
|
||||
| `divider` | — | `style`(line/space) | 分隔 |
|
||||
|
||||
```yaml
|
||||
blocks:
|
||||
- type: prose
|
||||
body: { zh: 正文 markdown,可含排版类 span, en: Body markdown }
|
||||
- type: cards
|
||||
columns: 3
|
||||
items:
|
||||
- { title: { zh: 写作, en: Writing }, desc: { zh: 书评与技术文, en: Reviews & tech } }
|
||||
```
|
||||
|
||||
边界:块数 ≤24、单块文本 ≤4000 字(超限截断并 WARN);未知块型跳过 + WARN;`blocks` 为空时回落 `intro` markdown,再空回落内置文案。图片字段走 `image()`,只能后台上传进 `content/site/assets/`。
|
||||
|
||||
## 发布提醒
|
||||
|
||||
- push main → webhook 自动构建发布(约 10 秒)
|
||||
@@ -303,6 +343,9 @@ markdown 原生语法,无需任何配置:
|
||||
| `latestPhotos` | 0-6 | 4 | 「最新影像」张数;**0 = 隐藏该区块** |
|
||||
| `perTrackLimit` | 4-8 | 6 | 首页阅读/技术两轨各显示条数 |
|
||||
| `sections` | `{tracks, photos, heatmap, projects}` 布尔 | 全开 | 区块开关,关掉即不渲染 |
|
||||
| `projectsLimit` | 1-99 | 6 | 首页项目墙条数(越界夹取) |
|
||||
| `announcement` | `{zh, en}`(markdown 富文本) | 空 | 名片区下方公告;空 = 不渲染 |
|
||||
| `postsTracks` | `{reading, tech, photo}` 布尔 | 全开 | 关掉某轨则该轨文章不在首页列出(归档页仍可见) |
|
||||
|
||||
越界值会被夹取(如 perTrackLimit=20 按 8 处理),不报错;**全部留空 = 现有形态不变**。
|
||||
|
||||
|
||||
Reference in new issue
Block a user