跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

Oink 博客

OINK 公告、工程实践与实现笔记

1 - 把博客列表变成画廊

用文章封面浏览博客,支持等高拼接、无缝和瀑布流,并为触屏与键盘保留完整的文字入口。

有时候,认出一篇文章最快的办法是看封面。旅行手记、速写集、项目记录,都可能 比普通技术文章更适合先看图、再读标题。

OINK 1.4.0 新增一种博客视图:gallery。每篇文章成为一张可点击的 封面,默认按比例拼成行;鼠标悬停或键盘聚焦时,标题和描述浮现出来,点击则 进入文章。

已随 OINK 1.4.0 发布

画廊已经属于正式主题。它沿用普通博客文章模型,只增加一种以封面浏览同一批文章的方式。

同一批文章,四种浏览方式

现有的几种视图各有用途。知道日期或标题时,表格最便于查找;想先读摘要, 水平条目更从容;卡片把封面和文章信息放在一起。画廊则把大部分空间留给封面。

博客视图 读者看到什么
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 中加入:

content/blog/_index.md
blog_index: gallery
blog_index_toggle: true
blog_index_size: 24
blog_gallery:
  mode: wall
  size: 240

blog_index 决定初始视图。blog_index_toggle 允许读者循环切换四种视图, 设为 false 就只发布画廊。blog_index_size 控制每页文章数, blog_gallery.size 控制目标格子大小,两者各管一件事。

如果想设成站点默认值,将这些键放入 params.ui:

hugo.yml
params:
  ui:
    blog_index: gallery
    blog_index_toggle: true
    blog_index_size: 24
    blog_gallery:
      mode: wall
      size: 240

页面或栏目 cascade 可以覆盖站点默认值。blog_gallery 块会整体替换站点块, 因此希望保留两个设置时,要把两个字段一起写上。封面继续使用页面包里的 特色图片或已有的 images 字段。

上述配置适用于主题自带的博客栏目索引;自定义首页和术语页模板若需展示画廊, 需要显式调用画廊 partial。

保持实现简单

主题会把可处理的大封面缩放到 960 × 960 范围内,保留原图比例;GIF 封面使用 静帧预览。图片采用延迟加载,隐藏视图首次显示时也沿用这个机制。本地封面 不需要远程图片服务,也不增加浏览器端依赖。

画廊有自己的小型运行时,复用 Expo 的几何计算。当视图重新显示、可用宽度 改变、字体加载完成,或图片实际尺寸确定后,都会重新计算布局。这些变化比 第一张截图更值得检查:初次打开没问题的页面,可能在拖动侧栏或切换视图后 发生重叠。

检查器会比较四种视图和不同分页中的文章顺序。浏览器回归覆盖中英文、桌面 与触屏、浅色与深色、键盘操作、缺失封面、图片加载失败及禁用 JavaScript。 完整参数见博客创作指南,内容模型与实现 归属记录在设计决策中。

2 - 在 Blog 布局中实现沉浸式阅读

四个 front matter 键即可把普通 Blog 页面切换为阅读优先的版式: 以全幅 Hero 开场,再用随文大纲栏承接正文。

本页直接由标准 Blog 布局渲染,无需新增专门的内容类型。只需四个 front matter 键 就能切换版式;也可以在栏目 cascade 中统一配置:

featured_image: hero      # 题图作为全幅开场背景
toc_style: flow           # 更宽的大纲栏从正文起点开始
toc_taxonomies: false     # 右栏只保留大纲
sidebar_enabled: false

Hero 开场

带有题图的页面可以用它作为开场。hero 会把图片铺满视口顶部, 将标题下移留出空间,并在正文开始前渐隐收束。由于题图由页面外层布局绘制, 栏目索引页同样可以使用这一版式。

页面卡片、社交预览与 Hero 共用同一套代表图片解析规则。featured_image: banner 保留带边框的横幅模式;没有合适图片的页面则自动回退到普通页头。

随文大纲栏

toc_style: flow 用更宽的随文大纲栏取代固定在视口上的目录面板。它在 Hero 下方 与正文齐平展开,向下滚动后才吸附固定。这个开关与题图相互独立,因此即使部分文章没有配图, 整个栏目仍能保持统一的大纲版式。

toc_taxonomies: false 用于隐藏右侧的分类词云。如果页面既没有目录也没有词云, 右侧空栏会自动省略。

仍然保留的能力

开场下方依然是完整的标准 Blog 文章:日期与阅读时长、标签徽章、作者信息、系列导航条、 摘要导语、分享栏、来源标注、顺序翻页与评论。Blog 布局默认隐藏面包屑; 需要展示页面在内容树中所处位置时,可设置 breadcrumb: true 重新开启。

3 - OINK 实施日记:从复制外壳到统一主题

记录 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 无法表达的合法图表选项。现有页面用它们格式化提示、标签以及按数据选择颜色。把这些回调单独视为迁移例外,只会增加配置,并不会形成沙箱。

因此短代码采用一套直接契约:

  1. 内容提供 JSON 或 YAML,由 Hugo 解析并安全序列化;
  2. 可选的 JavaScript 围栏代码块声明回调;
  3. $fn:name 在选项解析后重新连接这些回调;
  4. 作者按照行内 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。文档阶段完成了四项工作:

  1. 把英文设为首要语言、简体中文设为第二语言;后续外壳评审又从演示站点移除了法文;
  2. 为每份核心文档与博客源文件创建并置的 .zh.md 译文;
  3. 在每个中文标题中显式保留英文标题 ID;
  4. 增加 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 的文档主题,并提供多语言基础设施与可复用内容组件。

今天,我们发布 OINK 实现预览:它从 Docsy 直接演进而来,提供统一的产品页面骨架、仅依赖 Hugo 的站点构建、本地优先的浏览器依赖、通用多语言框架,以及一组从 PGSTY 文档站提炼出的可复用内容组件。

这次预览完成了首个正式标签与 Cloudflare Pages 生产部署之前的实现与文档里程碑。

为什么需要 OINK?

多个成熟的文档站此前各自复制了相同的 Docsy 布局、导航、搜索代码、SCSS、JavaScript 与短代码。每当修复一个共性问题,都必须在多个仓库里重复改动;同时每个站点都背着一套前端工具链与隐式外部网络依赖,导致离线构建异常繁琐。

OINK 将真正可复用的基础层收敛到主题中。产品矩阵、门户、价格页等业务专属逻辑留在各自站点;共享主题统一负责文档骨架、浏览器运行时、多语言路由、无障碍交互与内容组件契约。

有哪些变化?

产品本身,而不是一种模式

OINK 不是可选皮肤。项目没有 oink.enabled 开关、params.oink.* 命名空间,也没有“上游版与品牌版”并行的两套模板树。theme/ 中的实现就是产品本身。

这项取舍避免了同时维护两套视觉系统与两套测试矩阵。Hugo 原生设置与兼容的 Docsy 参数继续保持原有语义。

消费端仅依赖 Hugo 构建

下游站点只需运行一条命令即可完成构建:

hugo --gc --minify

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

使用说明更新于 2026-10-17

本文记录最初的实现预览。当前搭建与验收统一使用 Hugo Extended 0.168.0,基线随 稳定版更新,不再测试或适配旧 Hugo。

安装 Git、Go 1.27 或更新版本,以及 Hugo Extended 0.168.0,再评估 官方 Starter:

git clone https://github.com/pgsty/oink-starter.git my-docs
cd my-docs
hugo server

旧 Starter 的 workflow 固定版本也应同步更新。打开本地英文与中文页面,切换语言、 使用本地搜索、改变颜色模式,并访问组件示例。网络隔离环境按 离线归档安装指南操作。

当前验证范围

当前实现的自动化覆盖包括:

  • 统一使用 Hugo Extended 0.168.0 构建;
  • 禁止消费端 Node/npm/PostCSS/Autoprefixer 路径;
  • LTR、RTL、子路径、打印、颜色模式与生产资源;
  • 语言选择器的隐藏、点击轮换、悬停菜单、缺失译文回退与 RTL 行为;
  • 本地按页运行时与重复组件实例;
  • ECharts 结构化选项与回调集成;
  • 离线双语 starter 与离线发行归档;
  • vendor 许可证与校验值;
  • SILO、PGSTY、SOW 与 Pigsty 的非破坏性迁移演练。

最近一次四站演练已全部在临时副本中通过生产构建。

正式发布前还需要什么?

在打上首个正式版本标签前,我们将敲定模块与软件包命名,把初始版本号同步写入源码标签、归档包与文档,并将生产 Cloudflare Pages 项目接入固定的 Hugo 构建流水线。