224 lines
16 KiB
Markdown
224 lines
16 KiB
Markdown
# 管理台（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 秒自动构建上线。
|
||
|
||
## 页面说明文案（5j 新增：瞬间 / 书架）
|
||
|
||
「页面文案」新增 `content/site/pages.yaml`（后台「瞬间 / 书架 标题下的说明」）：那一行字的文字（markdown，支持排版类）、
|
||
字号（11–16）、颜色（灰阶四级）、字体（12 族下拉）都在这里改，两页互相独立。
|
||
|
||
兜底行为：任何字段清空/删掉都回落内置默认；越界值（如字号填 40、颜色乱写）
|
||
会被自动夹取或回落，不会破版。
|
||
|
||
## 文章置顶（5h 新增）
|
||
|
||
文章编辑页有一个「置顶」开关。打开后这篇文章排在首页分轨、归档、书架三处列表的最前面，列表里显示一个灰阶「置顶」小徽标。
|
||
|
||
语义边界（刻意如此，别当 bug 报）：
|
||
- **只影响列表顺序**：`pubDate` 不变、URL 不变、RSS 里的时间序列不变，订阅者不会看到时间错乱
|
||
- **与「隐藏」同开时以隐藏为准**：后台的「隐藏」开关（5j 起是真字段）会把这篇从列表/RSS/sitemap 里拿掉，页面本身仍可分享
|
||
- **支持多篇/多本同时置顶**：置顶组内部仍按日期倒序；书架页（/books）里每个置顶的书评都会排在前面并**默认展开**
|
||
- **置顶 + 隐藏同时打开时，以隐藏为准**（5j 修复：此前隐藏开关只写一个没人读的字段，导致隐藏+置顶的文章照样显示还排第一）
|
||
- 书架页用「↑ + 横线」的回到顶部图标表示置顶（不写文字），与右侧展开箭头形状不同，不会混读
|
||
- 关掉开关立即恢复时间序，没有"冷却期"
|
||
|
||
## 瞬间（5h 起与文章同级）
|
||
|
||
「瞬间」集合的「文字」字段是 **markdown 编辑器**，与文章同一套表达力：
|
||
|
||
- markdown：`**加粗**`、`*斜体*`、列表、`> 引用`、`` `行内代码` ``
|
||
- 排版类 HTML：`<span class="c-blue font-kai">彩色 + 楷体</span>`（可用类清单见写作指南「文章排版类」一节，与文章完全同一份白名单）
|
||
- 彩色**不再限次**（原来的"一页最多三处"已取消）；仍守外壳灰阶：导航/页脚/按钮/背景不染色
|
||
|
||
**每条瞬间自带评论区**：时间线卡片下方有「评论」折叠条，读者点开才加载评论（不点开不为它付任何加载成本）。中文页与英文页共用同一条评论流，语言切换不会丢评论。
|
||
|
||
**每条的浏览 / 评论数字是只读的**：读者点开评论区不会虚增浏览数（只有整页访问才计一次）。
|
||
|
||
## 照片说明文字（灯箱右侧）支持排版（5i 新增）
|
||
|
||
照片的「说明」（caption）现在支持 markdown 与排版类，与文章正文同一套：
|
||
|
||
```yaml
|
||
caption: 落日把海与城一齐烫成金箔，**这一帧等了二十分钟**
|
||
```
|
||
|
||
```html
|
||
<span class="c-blue">蓝色</span>、<span class="font-kai">楷体</span> 这些类都能用。
|
||
```
|
||
|
||
灯箱是深底，颜色类会自动取柔和对暗底的那一档，不会刺眼。EXIF 那几行是相机数据，不做排版。
|
||
|
||
## 照片上传流
|
||
|
||
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）
|
||
**叙述已合一（5j 起）**：改用 `story` 字段（后台显示为「叙述（推荐改这里）」），整段写成 markdown，
|
||
链接直接内联（`[文字](url)`），不再分"链接前/链接后"。旧的两个字段（链接前/链接后）
|
||
只是 legacy——仅当「叙述」为空时才会退回旧拼接，平时不用管它们。
|
||
|
||
|
||
**开篇是原生「GitHub 档案卡」（5h 起）**：头像 / 名字@handle / 定位叙述 / 社交图标 / 统计四格（关注者、公开仓、总星标）/ 语言占比灰阶条（只有第一名用强调色，其余灰阶）。**零第三方图片、零 iframe**。数据失败只隐藏对应数字，不会破版。
|
||
|
||
想换那段「定位叙述」，改本文件的 `blurb` + `blurb_after`（双语，后台可改）——它们现在同时供给档案卡与项目墙下方的说明。
|
||
|
||
下面的 `intro_from: "github-readme"` **仍可用但不推荐**：那会把 GitHub 专用 README 原样渲染，带 7 类外链图（shields.io、readme-typing-svg、github-readme-stats、streak-stats、activity-graph、snake、komarev 访客徽章）与 `<div align="center">` 居中——本站按普通块渲染，故居中失效；外链图在慢网或被墙时全空白。这也是当初"部分内容没居中、有些图片没显示"的根因。
|
||
|
||
| 字段 | 取值 | 说明 |
|
||
|---|---|---|
|
||
| `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 都不影响页面渲染；尺寸已由样式限制在内容宽度内。
|
||
|
||
## 浏览与评论计数（5h 新增）
|
||
|
||
文章页、瞬间页、开源页、关于页都用同一枚灰阶徽标：**眼睛图标 = 浏览数，气泡图标 = 条评论**，数据来自自建 Artalk，不依赖任何第三方徽章服务。
|
||
|
||
几条行为约定（省得当成 bug）：
|
||
|
||
- **一页只计一次浏览**：「计一次」发生在这页唯一那个 `page` 模式徽标（文章页在标题下方），同一页其余徽标都是只读镜像，显示的是同一个数字——不会出现"页头 17、评论区 16"
|
||
- **开评论不算浏览**：瞬间逐条徽标是只读的，读者展开评论区不会给那条动态虚增浏览量
|
||
- **接口挂掉显示「–」而不是 0**：宁可留白，也不给读者看一个错误的零
|
||
- **换页重计、同页刷新重计**：这是浏览量的定义，不是重复计数的 bug（软导航回同一页也算新一次访问）
|
||
|
||
## 纪律（与写作指南同源）
|
||
|
||
- **图片体积**：上传前自行压缩（长边 ≤2400px）——Sveltia 内建优化**刻意关闭**（会抹 EXIF 断构建期提取管线）
|
||
- **删除**：删条目会连带删除被其独占引用的 jpg（实测行为，官方文档说的"不连带"是错的）
|
||
- EXIF 覆盖字段一般留空；文章 markdown 仍建议本地/gitea web 写（Sveltia 只管照片）
|
||
- 保存直连 main 无分支缓冲——webhook 构建是安全网，构建失败 gitea 的 webhook 投递记录可查
|
||
|
||
## 已知限制
|
||
|
||
- 启动时探测 /api/forgejo 报 404 属良性回落（日志噪音，无影响）
|
||
- 大视频仍走仓外 store + /media/ 绝对路径（见写作指南体积纪律表）
|