这是本节的多页打印视图。 .
Oink 博客
- 1: 把博客列表变成画廊
- 2: 在 Blog 布局中实现沉浸式阅读
- 3: OINK 实施日记:从复制外壳到统一主题
- 4: OINK 实现预览正式亮相
1 - 把博客列表变成画廊
有时候,认出一篇文章最快的办法是看封面。旅行手记、速写集、项目记录,都可能 比普通技术文章更适合先看图、再读标题。
OINK 1.4.0 新增一种博客视图:gallery。每篇文章成为一张可点击的
封面,默认按比例拼成行;鼠标悬停或键盘聚焦时,标题和描述浮现出来,点击则
进入文章。
画廊已经属于正式主题。它沿用普通博客文章模型,只增加一种以封面浏览同一批文章的方式。
同一批文章,四种浏览方式
现有的几种视图各有用途。知道日期或标题时,表格最便于查找;想先读摘要, 水平条目更从容;卡片把封面和文章信息放在一起。画廊则把大部分空间留给封面。
| 博客视图 | 读者看到什么 |
|---|---|
list |
带缩略图、元数据和摘要的水平条目 |
cards |
带 16:9 封面与文章信息的规则卡片网格 |
table |
紧凑的日期、标题、标签行 |
gallery |
按比例排布的封面,附带标题和简短描述 |
开启布局切换后,四种视图显示同一页文章,日期顺序与分页结果一致。读者可以先 看封面,再切成表格查找,不必重新翻到另一页。关闭切换器时,独立表格仍保留 原来的行为:一次列出整个栏目。
借用 Expo 的排布
Expo 已经有图片展墙。博客画廊复用它的行布局算法和 紧凑的控制方式,内容仍取自普通博客页面:特色图片作为封面,页面标题作为 名称,description 提供描述。作者无需再维护一份相册清单。
点击后的去向也要符合读者预期。Expo 的图片打开查看器,博客封面进入文章;
设置了 manual_link 的文章仍然前往外部地址。这样,画廊可以作为写作内容的
索引,也适合封面承担主要表达、正文只有几句话的视觉短记。
画廊内部提供三种排布:
| 排布 | 布局方式 | 文字显示 |
|---|---|---|
wall |
等高拼接,保留 6px 间隙 | 悬停或键盘聚焦时显示 |
seamless |
使用相同的行布局,去掉间隙 | 悬停或键盘聚焦时显示 |
cards |
每个条目放入当前最短的一列,形成瀑布流 | 始终显示在图片下方 |
这里的 cards 是画廊里的瀑布流,与博客外层的规则卡片视图区分开。旁边的
滑杆可以在 160–360 CSS 像素之间调整目标图片大小。画廊独立记忆这些选择,
不会因为改了博客列表,就把下一页的 Expo 相册也换一种排法。
给手机上的文字留出空间
只能悬停才出现的描述,在触摸屏上几乎没有用。没有精细指针与悬停能力的设备, 会把展墙和无缝模式的文字放在图片下方。排版时,每一行还会留出最高一块文字 所需的空间,避免下一行盖住链接或正文。
超长竖图需要额外处理。如果窄屏格子完全遵循原图比例,下面的文字可能每行只 放得下几个字。画廊宽度低于 500px 时,我们会进一步收紧格子的宽高比范围。 图片仍在格子里完整显示,必要时留白。这是在封面不裁切与文字可读之间做的取舍。
键盘聚焦会显示与悬停相同的说明,并画出格子内侧的焦点环。链接以文章标题 作为无障碍名称。没有封面的文章保留可点击的标题块,图片加载失败时也采用 相同回退。即使禁用 JavaScript,页面仍是一份带有可见文字和普通链接的 响应式网格。
为栏目开启画廊
在博客栏目的 _index.md front matter 中加入:
blog_index 决定初始视图。blog_index_toggle 允许读者循环切换四种视图,
设为 false 就只发布画廊。blog_index_size 控制每页文章数,
blog_gallery.size 控制目标格子大小,两者各管一件事。
如果想设成站点默认值,将这些键放入 params.ui:
页面或栏目 cascade 可以覆盖站点默认值。blog_gallery 块会整体替换站点块,
因此希望保留两个设置时,要把两个字段一起写上。封面继续使用页面包里的
特色图片或已有的 images 字段。
上述配置适用于主题自带的博客栏目索引;自定义首页和术语页模板若需展示画廊, 需要显式调用画廊 partial。
保持实现简单
主题会把可处理的大封面缩放到 960 × 960 范围内,保留原图比例;GIF 封面使用 静帧预览。图片采用延迟加载,隐藏视图首次显示时也沿用这个机制。本地封面 不需要远程图片服务,也不增加浏览器端依赖。
画廊有自己的小型运行时,复用 Expo 的几何计算。当视图重新显示、可用宽度 改变、字体加载完成,或图片实际尺寸确定后,都会重新计算布局。这些变化比 第一张截图更值得检查:初次打开没问题的页面,可能在拖动侧栏或切换视图后 发生重叠。
检查器会比较四种视图和不同分页中的文章顺序。浏览器回归覆盖中英文、桌面 与触屏、浅色与深色、键盘操作、缺失封面、图片加载失败及禁用 JavaScript。 完整参数见博客创作指南,内容模型与实现 归属记录在设计决策中。
2 - 在 Blog 布局中实现沉浸式阅读
本页直接由标准 Blog 布局渲染,无需新增专门的内容类型。只需四个 front matter 键 就能切换版式;也可以在栏目 cascade 中统一配置:
Hero 开场
带有题图的页面可以用它作为开场。hero 会把图片铺满视口顶部,
将标题下移留出空间,并在正文开始前渐隐收束。由于题图由页面外层布局绘制,
栏目索引页同样可以使用这一版式。
页面卡片、社交预览与 Hero 共用同一套代表图片解析规则。featured_image: banner
保留带边框的横幅模式;没有合适图片的页面则自动回退到普通页头。
随文大纲栏
toc_style: flow 用更宽的随文大纲栏取代固定在视口上的目录面板。它在 Hero 下方
与正文齐平展开,向下滚动后才吸附固定。这个开关与题图相互独立,因此即使部分文章没有配图,
整个栏目仍能保持统一的大纲版式。
toc_taxonomies: false 用于隐藏右侧的分类词云。如果页面既没有目录也没有词云,
右侧空栏会自动省略。
仍然保留的能力
开场下方依然是完整的标准 Blog 文章:日期与阅读时长、标签徽章、作者信息、系列导航条、
摘要导语、分享栏、来源标注、顺序翻页与评论。Blog 布局默认隐藏面包屑;
需要展示页面在内容树中所处位置时,可设置 breadcrumb: true 重新开启。
3 - OINK 实施日记:从复制外壳到统一主题
OINK 源于一个现实痛点:手头的多个生产文档站本就同源,却把公共实现拆成了散落各处的复制文件。虽然前台外观看着一致,日常维护却要在多个仓库里来回同步。
这篇日记记录我们如何把散落的站点覆盖项收敛为一套统一主题,重点交代背后的技术取舍、迁移演练与测试设计。
锁定产品契约
第一项真正有价值的工作是做减法。选择实现方式之前,我们先写清产品必须是什么:
- 从 Docsy 直接演化而来的独立主题;
- 唯一标准外壳,而不是可切换皮肤;
- Hugo Extended 是消费端唯一构建依赖;
- 所有主题自带浏览器资源默认本地优先;
- 多语言行为从 Hugo 推导,而不是从 PGSTY 域名推导;
- 可复用组件进入主题,业务语义留在站点;
- 保留 Docsy 历史、许可证与可追踪的上游关系。
这排除了一个看似诱人、实际代价高昂的捷径:增加 params.oink.enabled
并保留旧外壳。模式开关会让每次布局调整、无障碍修复与测试都支持两套产品。直接演化则让目标设计成为唯一设计。
替换页面外壳
文档、博客与 API 参考布局围绕一组小型共享 partial 重新构建。新的外壳包括:
- 全局导航与响应式次级导航;
- 可调整宽度、可折叠的侧栏;
- 本地搜索与快捷链接;
- 语言与颜色模式控件;
- 面包屑、目录(TOC)、页面元数据与反馈;
- 一致的页脚与打印布局。
真正困难的不是画出导航栏,而是在删除复制的 baseof.html
时保留 Docsy 既有扩展点。范围明确的 hook 仍然存在;复制整个站点外壳不再是正常的定制路径。
移除消费端工具链
原有依赖链假设 Bootstrap 与 Font Awesome 来自 npm,部分路径还会调用 PostCSS。OINK 把必需源码与编译产物移入主题,并让 SCSS 留在 Hugo 自身的 Asset Pipeline 中。
测试不只检查 hugo
是否成功。fixture 中的陷阱会在消费端构建尝试运行 Node.js、npm、PostCSS 或 Autoprefixer,或模板调用
resources.GetRemote 时立即失败。LTR 与 RTL 页面遵守同一约束。
这里的区分非常重要:仓库仍使用 Node 运行维护者测试工具。“仅依赖 Hugo”描述的是消费站点取得完整主题后所需的构建环境,并不是禁止主题仓库使用开发工具。
纳管浏览器运行时
下一层工作覆盖浏览器原本可能从远端获取的全部依赖:Bootstrap、Font Awesome、字体、jQuery、Lunr、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic 及其辅助库。
theme/VENDOR.json
为每项选定产物记录来源、固定版本、许可证路径、校验值与更新流程。许可证与 vendor 内容相邻存放。清单会与真实文件一起验证,而不是停留在愿望列表。
PlantUML 与 Diagrams.net 迫使我们做出一项重要区分:它们依赖服务,而不只是 JavaScript 库。OINK 拒绝虚构公共端点;启用功能却没有配置服务时,构建会失败。
构建多语言内核
旧的语言行为散落在导航逻辑与站点专用假设中。新的内核从 Hugo 已配置语言、.Translations
与 .AllTranslations 出发。
呈现方式刻意保持稳定:只有一种语言时隐藏选择器;两种或更多语言统一使用同一个图标按钮。点击会按配置权重切换,短暂悬停或键盘聚焦则打开完整语言菜单。
缺少译文时回退到目标语言首页。语言名称使用该语言的自称。同一组对象还会驱动
lang、书写方向、canonical、 hreflang 与 Open Graph
locale 元数据,因此可见选择器不会与 SEO 输出漂移。
测试会让 RTL 语言作为当前语言覆盖每种状态,而不只验证 starter 的两种 LTR 语言。原生链接与 disclosure 控件让键盘行为保持可预期。
提炼通用组件
Asciinema、ECharts、Infographic、文档轮播、折叠块、标签页、卡片与参数渲染,已经在 PGSTY 站点证明了价值。接下来的工作,是把复制品转化为产品 API:
- 统一参数名称与默认值;
- 根据页面身份与短代码序号生成唯一 ID;
- 每页只加载一次运行时,未使用页面完全省略;
- 保持子路径 URL 正确;
- 支持多个内容完全相同的实例;
- 提供打印、深色模式、移动端、键盘与减少动态效果行为;
- 为导入内容保留兼容别名。
产品矩阵等业务控件没有迁入主题。是否复用不能只看有多少仓库包含同一个副本;通用组件必须拥有稳定、与业务无关的契约。
支持 ECharts 回调
ECharts 回调是 JSON 与 YAML 无法表达的合法图表选项。现有页面用它们格式化提示、标签以及按数据选择颜色。把这些回调单独视为迁移例外,只会增加配置,并不会形成沙箱。
因此短代码采用一套直接契约:
- 内容提供 JSON 或 YAML,由 Hugo 解析并安全序列化;
- 可选的 JavaScript 围栏代码块声明回调;
$fn:name在选项解析后重新连接这些回调;- 作者按照行内 HTML 与其他自定义集成相同的信任模型审查可执行代码。
测试覆盖内容相同的重复图表、非法 CSS 长度、结构化选项与回调注册。
创建 starter 与归档
如果最小示例能完整演示契约,契约就更容易获得信任。starter 包含双语首页、文档、博客与组件页面,以及本地搜索、深色模式、图表、API 文档和新增组件;它没有
package.json,也没有站点工作流。
离线打包器会组合
theme/、starter/、许可证、上游记录与迁移指南,并排除生成结果与依赖缓存。它会写出配套 SHA-256 文件,并拒绝覆盖已有产物。
验收测试把 starter 与主题复制到临时目录,清空缓存,阻断 HTTP/HTTPS 与 Go 代理,使用 Hugo 构建,再检查 HTML 与 CSS 中是否出现第三方子资源。
演练四站迁移
SILO、PGSTY、SOW 与 Pigsty 提供了现实检验。演练工具会复制各工作区而不是修改源目录,只删除已经分类的公共覆盖项,应用本地主题 replacement,禁止网络与前端工具,再运行生产构建。
最近一次演练分别从 SILO、PGSTY、SOW 删除了 20 个公共覆盖项,从 Pigsty 删除了 24 个。Pigsty 保留三个业务矩阵短代码与现有 ECharts 回调。四个站点的临时副本均顺利完成构建,分别生成 1,095、16、128 与 2,473 个 HTML 文件。
把样例站变成 OINK 文档
继承而来的 docsy.dev
站点是很有价值的回归语料库,但它只描述 Docsy。文档阶段完成了四项工作:
- 把英文设为首要语言、简体中文设为第二语言;后续外壳评审又从演示站点移除了法文;
- 为每份核心文档与博客源文件创建并置的
.zh.md译文; - 在每个中文标题中显式保留英文标题 ID;
- 增加 OINK 产品指南、项目公告与本实施日记。
翻译之前,我们先建立术语与排版指南。随后使用检查器验证源文件与译文配对、标题数量、中文显式 ID,以及渲染后的中英文标题 ID 是否完全相同。
Docsy 历史发布文章保持忠实翻译,其中的 npm 时代说明属于历史语境;OINK 架构与迁移指南则明确说明当前仅依赖 Hugo 的产品契约。
测试如何改变设计
多项测试不仅验证实现,也反过来改变了设计:
- 子路径 fixture 迫使每个本地组件 URL 都经过 Hugo URL 处理;
- 重复实例测试用“页面加序号”ID 替代内容哈希;
- 离线浏览器检查暴露了隐含运行时请求;
- RTL 语言矩阵避免选择器只适用于 starter 的两种 LTR 语言;
- ECharts 回调 fixture 保证回调注册与结构化选项可以协同工作;
- 迁移演练保留了直接清空
layouts/时会被误删的站点专用 partial。
后续工作
在首个正式版本发布前,我们将确定公开仓库、模块与软件包命名,并把 Cloudflare Pages 项目接入源分支构建与线上验证。
生产站点迁移将逐个推进,每个站点使用独立分支完成预览部署、视觉回归检查并准备好回滚产物。
经验总结
- 动手搬移文件前先划清产品边界。
- 本地优先设计需要同时在构建阶段和浏览器运行阶段通过校验。
- 配置项应当表达用户意图,而不是暴露内部实现分支。
- 翻译质量不仅看译文是否通顺,还要保证链接稳定、代码一致、排版规范与渲染结构对齐。
- 提炼通用组件是为了消除重复维护,不应把业务专属逻辑塞进主题。
最终我们得到了一套能够作为完整产品理解、构建、测试、翻译与升级的统一主题。
4 - OINK 实现预览正式亮相
今天,我们发布 OINK 实现预览:它从 Docsy 直接演进而来,提供统一的产品页面骨架、仅依赖 Hugo 的站点构建、本地优先的浏览器依赖、通用多语言框架,以及一组从 PGSTY 文档站提炼出的可复用内容组件。
这次预览完成了首个正式标签与 Cloudflare Pages 生产部署之前的实现与文档里程碑。
为什么需要 OINK?
多个成熟的文档站此前各自复制了相同的 Docsy 布局、导航、搜索代码、SCSS、JavaScript 与短代码。每当修复一个共性问题,都必须在多个仓库里重复改动;同时每个站点都背着一套前端工具链与隐式外部网络依赖,导致离线构建异常繁琐。
OINK 将真正可复用的基础层收敛到主题中。产品矩阵、门户、价格页等业务专属逻辑留在各自站点;共享主题统一负责文档骨架、浏览器运行时、多语言路由、无障碍交互与内容组件契约。
有哪些变化?
产品本身,而不是一种模式
OINK 不是可选皮肤。项目没有 oink.enabled 开关、params.oink.*
命名空间,也没有“上游版与品牌版”并行的两套模板树。theme/ 中的实现就是产品本身。
这项取舍避免了同时维护两套视觉系统与两套测试矩阵。Hugo 原生设置与兼容的 Docsy 参数继续保持原有语义。
消费端仅依赖 Hugo 构建
下游站点只需运行一条命令即可完成构建:
Bootstrap、Font Awesome、字体、搜索、图表、API 文档运行时与 OINK 组件均已随主题提交。构建站点不再需要安装 Node.js、npm、PostCSS、Autoprefixer,也不再从 CDN 下载资源。
主题仓库维护者仍使用 Node 工具运行回归测试与更新 vendor 资源,但这套维护工具链不进入下游站点的构建流程。
本地优先的浏览器行为
默认 starter 会从生成后的站点提供页面外壳、字体、图标、搜索、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts 与 Infographic 依赖。可选运行时按页面选取,并且每页最多加载一次。
PlantUML 与 Diagrams.net 不再拥有公共服务默认值。站点必须配置受控端点、使用预渲染结果,或明确选择远程服务。
多语言基础设施
语言路由来自 Hugo 的语言与翻译对象。配置一种语言时隐藏选择器;配置两种或更多语言时,直接点击按配置顺序切换,短暂悬停或键盘聚焦则打开完整菜单。当前页面缺少译文时,选择器会进入目标语言首页,而不是失效路径。
starter 与本站均以英文为首要语言、简体中文为第二语言。核心文档与博客范围内的每个页面都有并置的
.zh.md 译文,且标题采用稳定的显式 ID。
可复用组件
OINK 新增主题级 Asciinema、ECharts、Infographic、文档轮播、折叠块、标签页、卡片、导航卡片、文档卡片与参数组件。它们会生成唯一实例 ID,并且只在实际使用时加载本地资源。
ECharts 接受结构化 JSON 或 YAML,也支持通过 $fn:name
引用可选的 JavaScript 回调。回调代码只在声明它的页面运行。
哪些能力保持不变?
OINK 沿用 Docsy 的内容组织、front matter、文档与博客 section、菜单、taxonomy、打印输出、仓库链接、常用短代码、图表、API 参考能力与扩展 hook。现有站点可以删除重复公共实现,而不必重写普通 Markdown。
项目也保留 Docsy 的 Apache-2.0 历史与归属信息。vendor 清单记录固定的第三方来源、许可证、产物与校验值。
体验 starter
本文记录最初的实现预览。当前搭建与验收统一使用 Hugo Extended 0.168.0,基线随 稳定版更新,不再测试或适配旧 Hugo。
安装 Git、Go 1.27 或更新版本,以及 Hugo Extended 0.168.0,再评估
官方 Starter:
旧 Starter 的 workflow 固定版本也应同步更新。打开本地英文与中文页面,切换语言、 使用本地搜索、改变颜色模式,并访问组件示例。网络隔离环境按 离线归档安装指南操作。
当前验证范围
当前实现的自动化覆盖包括:
- 统一使用 Hugo Extended 0.168.0 构建;
- 禁止消费端 Node/npm/PostCSS/Autoprefixer 路径;
- LTR、RTL、子路径、打印、颜色模式与生产资源;
- 语言选择器的隐藏、点击轮换、悬停菜单、缺失译文回退与 RTL 行为;
- 本地按页运行时与重复组件实例;
- ECharts 结构化选项与回调集成;
- 离线双语 starter 与离线发行归档;
- vendor 许可证与校验值;
- SILO、PGSTY、SOW 与 Pigsty 的非破坏性迁移演练。
最近一次四站演练已全部在临时副本中通过生产构建。
正式发布前还需要什么?
在打上首个正式版本标签前,我们将敲定模块与软件包命名,把初始版本号同步写入源码标签、归档包与文档,并将生产 Cloudflare Pages 项目接入固定的 Hugo 构建流水线。