Skip to content

Commit 9df883b

Browse files
Vonngclaude
Vonng
and
claude
committed
docs: bring the site to OINK 0.7.1 and correct what drifted
Pins the site to the published v0.7.1 tag, adds the bilingual release notes, and fixes documentation that described behaviour the theme no longer has -- or, in several cases, never had. Corrections verified against the theme source and a real build: - "Invalid input fails the build" was stated in roughly twenty places across the configuration and front matter references, and in the features page. The theme's templates contain no `errorf` at all: invalid values warn and fall back. The two build-stoppers that are real (Hugo's own `relref` resolution and `module.hugoVersion.min`) are left as they were. - The blog section documented three keys; it has seven. `featured_image` gained `hero`, `blog_index` gained `table`, and `blog_index_size`, `blog_index_toggle`, `toc_style` and `toc_taxonomies` had never been listed on the page that calls itself their single home. - The removed `release`, `release_products` and `release_group_by_product` keys were still documented as current API; they are replaced by the one key that works, `release_url`. Both reference pages now state that keys read only to warn about a rename live in Migration, which is also the rule the generated schema follows. - The `swagger`, `redoc` and `asciinema` output tables described the pre-0.7.1 behaviour -- and were, in fact, the only remaining source of component markup in the site's own Markdown output. They now document the static link that print, Markdown and RSS actually carry, the runtime that only interactive HTML loads, the shared URL policy, and warn-and-fall-back for the numeric parameters. - The OpenAPI guide presented Redoc as the accessible alternative to Swagger UI. Both are excluded from this site's zero-violation axe gate, Redoc for its operation-description contrast; the guide now says so instead of implying Redoc passes. - The Landing contract said navbar mega-menu columns accept 1-4. That parameter is retired: the theme warns and keeps one column, which the Shell contract already stated correctly. - Smaller fixes: date defaults are ISO, `images: []` does not suppress a bundle resource, `upstream_modified` changes the credit verb rather than adding a line, the Book guide no longer stops at print HTML now that BookManifest and the EPUB/PDF runners have shipped, and the vendored dependency count is 26. The Book publication and config-schema proposals now point at the released contracts that supersede them, and the 2026-08-26 review snapshot says which of its findings 0.7.1 closed. Retiring the config-schema proposal outright still needs a Decision to carry its rationale, so it stays listed. Browser fixtures that pinned v0.7.0 and the release-post list move with the version. The review snapshot pages were already in the working tree; they are included here because the regenerated Markdown goldens reference them. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent fd5fcde commit 9df883b

54 files changed

Lines changed: 1408 additions & 208 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎content/blog/release/0.7.1.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: Oink 0.7.1 — Nothing leaves the page, and bad input stops breaking builds
3+
linkTitle: Oink v0.7.1
4+
date: 2026-08-26T00:00:00+08:00
5+
lastmod: 2026-08-26T00:00:00+08:00
6+
draft: false
7+
description: >-
8+
Oink 0.7.1 is a security and validation patch. Swagger UI stops sending your
9+
spec URL to a third party, misconfigured values warn instead of killing an
10+
ordinary build, and the OpenAPI and terminal components finally behave in
11+
print, Markdown and RSS the way every other component already did.
12+
authors: [oink]
13+
categories: [release]
14+
tags: [Oink, Release]
15+
series: [oink-releases]
16+
series_weight: 8
17+
release_url: https://github.com/pgsty/oink/releases/tag/v0.7.1
18+
---
19+
20+
Oink 0.7.1 changes no component API and needs no content edits. It closes the
21+
code findings from an external review of the 0.7.0 line: one real privacy leak,
22+
a class of configuration values that could stop a build outright, and three
23+
components that had never been taught what a non-HTML output is.
24+
25+
{{< release-card >}}
26+
27+
## At a glance {#at-a-glance}
28+
29+
- Swagger UI no longer contacts the online validator. A published API page made
30+
a third-party request on every view; it no longer makes any.
31+
- A URL written into site configuration now passes the same safety check as one
32+
written by an author.
33+
- A mistyped number or boolean in `params` warns and falls back instead of
34+
ending an ordinary `hugo server` session.
35+
- `swagger`, `redoc` and `asciinema` emit a plain link in print, Markdown and
36+
RSS, and load their runtime only in interactive HTML.
37+
38+
## Swagger stopped phoning home {#swagger-validator}
39+
40+
Swagger UI ships with an online validator enabled by default, pointed at
41+
`validator.swagger.io`. It skips that request for `localhost`, which is why no
42+
local preview and no browser test ever showed it — and why every *deployed*
43+
API page was quietly handing your spec URL to a third party. On an intranet
44+
that URL is an internal hostname.
45+
46+
The initializer now pins `validatorUrl: null`, and it moved out of an inline
47+
`<script>` into a cacheable `js/chunks/swagger-init.js`. A normal build still
48+
downloads nothing, and now a normal *view* uploads nothing.
49+
50+
## Configured URLs go through the same gate as authored ones {#url-policy}
51+
52+
Two settings reached an `href` unchecked: the custom links in
53+
`params.ui.page_context_menu.links` and the archived-site banner's
54+
`params.url_latest_version`. A `javascript:` URL in either one rendered as a
55+
working, clickable script.
56+
57+
Both now run through the theme's shared URL policy: an unsupported scheme
58+
warns and the link is dropped rather than repaired. The archived-version
59+
banner additionally escapes its URL where it is written into the page, because
60+
clearing the scheme is not the same as being safe inside an HTML attribute.
61+
62+
Custom links also skip entries with a missing or non-text name, and the
63+
separator above them only appears when a link actually survives.
64+
65+
## Bad configuration warns; it no longer kills the preview {#validation}
66+
67+
The theme's rule has always been that invalid author or config input warns,
68+
falls back to a documented default, and keeps `hugo server` usable — with
69+
`--panicOnWarning` turning that warning into a failure where you publish.
70+
A group of numeric and boolean keys had never been wired into it.
71+
72+
Before 0.7.1, a value like `blog_index_size: nope` ended the build with a Go
73+
template error. Others were worse for being quiet: `sidebar_width_min: -50`
74+
emitted a negative pixel width without a word, and `blog_index_columns: 2.5`
75+
fed a fraction into a CSS grid.
76+
77+
Every numeric and boolean key now resolves through the shared validator:
78+
79+
| Input | Before | Now |
80+
| --- | --- | --- |
81+
| `blog_index_size: nope` | build fails | warns, uses `12` |
82+
| `blog_index_size: 0` | silently becomes `12` | warns, uses `12` |
83+
| `sidebar_width_min: -50` | emits `-50px` | warns, uses `220` |
84+
| `sidebar_width_min: 300` with `max: 200` | inverted layout | warns, uses `220`/`480` |
85+
| `blog_index_columns: 2.5` | fraction into CSS | warns, uses `3` |
86+
| `sidebar_item_overflow: clip` | silently `ellipsis` | warns, uses `ellipsis` |
87+
| `print.toc: nope` | silently `true` | warns, uses `true` |
88+
89+
The same treatment reaches the Landing sections: the hero's `media.ratio` and
90+
`media.max_width`, the capabilities board's `columns` and `rules`, and a
91+
marquee's `rows`. The hero's two style inputs were the notable ones — they were
92+
written straight into a `style` attribute, so a page's own front matter could
93+
put arbitrary CSS on the page. `ratio` now takes exactly two track sizes
94+
(`'1fr 240px'`), `max_width` a plain CSS length.
95+
96+
If you have been running with a value the theme silently corrected, you will
97+
see a new warning. That is the point — build once with `--panicOnWarning` after
98+
upgrading to find them.
99+
100+
## OpenAPI and terminal recordings respect the other outputs {#outputs}
101+
102+
Every Oink component renders once and then adapts to the output it lands in:
103+
interactive HTML, static print, plain Markdown for agents, and RSS. Sixteen
104+
components already did this. `swagger`, `redoc` and `asciinema` did not — they
105+
rendered their interactive markup into all four.
106+
107+
The result was a Markdown output carrying `<div class="td-asciinema">` and a
108+
JSON config block, a printed page holding an empty container where a player
109+
should be, and a single-page print that actually downloaded the player runtime
110+
to show one frozen frame.
111+
112+
All three now read the output format:
113+
114+
| Output | What you get |
115+
| --- | --- |
116+
| HTML | the full interactive component |
117+
| Print | a labelled static link showing the URL |
118+
| Markdown / LLMS | a plain Markdown link, nothing else |
119+
| RSS | the same plain link |
120+
121+
Only interactive HTML registers the runtime, so print and machine outputs load
122+
no player, no Swagger bundle and no ReDoc bundle. A cast or spec URL now also
123+
goes through the shared URL policy, and a mistyped `speed`, `cols`, `rows` or
124+
marker time warns and is ignored instead of ending the build.
125+
126+
## Smaller repairs {#smaller-repairs}
127+
128+
- The capabilities board's rule bars render at their authored widths. The
129+
template had always emitted them; the stylesheet never read them.
130+
- The generated configuration schemas match what Hugo actually parses. Trailing
131+
comments in `hugo.yaml` were leaking into eleven default values — `print.toc`
132+
shipped as the *string* `"true # section print views…"` — and four comment
133+
blocks documented the wrong key. Keys that exist only to warn about a rename
134+
no longer appear in editor completion.
135+
- A `hero` whose `media` is not a map warns and drops the media instead of
136+
ending the build.
137+
138+
## Upgrading {#upgrading}
139+
140+
```bash
141+
hugo mod get github.com/pgsty/oink@v0.7.1
142+
hugo mod tidy
143+
```
144+
145+
No content, configuration or template changes are required. One thing to do
146+
after upgrading: run a build with `--panicOnWarning` once. Configuration that
147+
used to be corrected silently now says so, and that build is where you will
148+
see it.
149+
150+
The complete list is in [CHANGELOG.md](https://github.com/pgsty/oink/blob/main/CHANGELOG.md).

‎content/blog/release/0.7.1.zh.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Oink 0.7.1：页面不再外泄，坏输入不再中断构建
3+
linkTitle: Oink v0.7.1
4+
date: 2026-08-26T00:00:00+08:00
5+
lastmod: 2026-08-26T00:00:00+08:00
6+
draft: false
7+
description: >-
8+
Oink 0.7.1 是一次安全与校验修补。Swagger UI 不再把你的 spec 地址发给第三方，
9+
配错的参数会告警并回退而不是中断普通构建，OpenAPI 与终端录像组件也终于像其他组件一样，
10+
在打印、Markdown 和 RSS 中表现正常。
11+
authors: [oink]
12+
categories: [release]
13+
tags: [Oink, Release]
14+
series: [oink-releases]
15+
series_weight: 8
16+
release_url: https://github.com/pgsty/oink/releases/tag/v0.7.1
17+
---
18+
19+
Oink 0.7.1 不改动任何组件 API，也不需要修改内容。它修复了对 0.7.0 主线外部审查发现的
20+
代码问题：一个真实的隐私外泄、一类会直接中断构建的配置值，以及三个从未被告知
21+
"非 HTML 输出"存在的组件。
22+
23+
{{< release-card >}}
24+
25+
## 概览 {#at-a-glance}
26+
27+
- Swagger UI 不再联系在线 validator。已发布的 API 页面每次被浏览都会发出一个第三方请求，现在不会了。
28+
- 写在站点配置里的 URL，现在和作者写的 URL 走同一道安全检查。
29+
- `params` 中数值或布尔值写错，会告警并回退，而不是终止普通的 `hugo server`。
30+
- `swagger`、`redoc`、`asciinema` 在打印、Markdown 和 RSS 中输出纯链接，只在交互 HTML 中装载运行时。
31+
32+
## Swagger 不再向外汇报 {#swagger-validator}
33+
34+
Swagger UI 默认开启在线 validator，地址指向 `validator.swagger.io`。它对 `localhost`
35+
跳过这个请求——这正是本地预览和浏览器测试从来看不到它的原因，也意味着每一个已经部署上线的
36+
API 页面，都在悄悄把你的 spec 地址交给第三方。在内网站点上，那个地址就是一个内部主机名。
37+
38+
现在初始化写死 `validatorUrl: null`，并从内联 `<script>` 移入可缓存的
39+
`js/chunks/swagger-init.js`。普通构建依然不下载任何东西，而现在普通的浏览也不再上传任何东西。
40+
41+
## 配置里的 URL 与作者写的走同一道门 {#url-policy}
42+
43+
有两处设置未经检查就进入了 `href`：`params.ui.page_context_menu.links` 里的自定义链接，
44+
以及归档站点横幅的 `params.url_latest_version`。在其中任何一处写 `javascript:` URL，
45+
都会渲染成一个可点击、可执行的脚本链接。
46+
47+
现在两者都走主题的统一 URL 策略：不支持的 scheme 会告警并丢弃该链接，而不是尝试修补。
48+
归档版本横幅在写入页面时还会额外做 HTML 转义——因为"scheme 合法"和"放进 HTML 属性里安全"
49+
不是一回事。
50+
51+
自定义链接还会跳过缺少名称或名称不是文本的条目，并且只有当确实有链接留下来时，
52+
才渲染它们上方的分隔线。
53+
54+
## 配置写错会告警，而不再让预览挂掉 {#validation}
55+
56+
主题一直有一条规则：非法的作者或配置输入应当告警、回退到有文档记载的默认值，
57+
并保持 `hugo server` 可用；而 `--panicOnWarning` 会在发布时把这个告警变成失败。
58+
只是有一批数值和布尔配置从来没有接入这条规则。
59+
60+
在 0.7.1 之前，`blog_index_size: nope` 会以一个 Go 模板错误终止构建。另一些则因为安静而更糟：
61+
`sidebar_width_min: -50` 一声不响地输出了负的像素宽度，`blog_index_columns: 2.5`
62+
把一个小数送进了 CSS 网格。
63+
64+
现在每一个数值与布尔配置都经过统一校验器：
65+
66+
| 输入 | 之前 | 现在 |
67+
| --- | --- | --- |
68+
| `blog_index_size: nope` | 构建失败 | 告警，使用 `12` |
69+
| `blog_index_size: 0` | 静默变成 `12` | 告警，使用 `12` |
70+
| `sidebar_width_min: -50` | 输出 `-50px` | 告警，使用 `220` |
71+
| `sidebar_width_min: 300` 且 `max: 200` | 布局反转 | 告警，使用 `220`/`480` |
72+
| `blog_index_columns: 2.5` | 小数进入 CSS | 告警，使用 `3` |
73+
| `sidebar_item_overflow: clip` | 静默当作 `ellipsis` | 告警，使用 `ellipsis` |
74+
| `print.toc: nope` | 静默当作 `true` | 告警，使用 `true` |
75+
76+
同样的处理覆盖了 Landing 各区块：hero 的 `media.ratio` 与 `media.max_width`、
77+
capabilities 的 `columns` 与 `rules`、以及跑马灯的 `rows`。其中 hero 的两个样式输入尤其值得一提——
78+
它们此前被原样拼进 `style` 属性，因此页面自己的 front matter 就能往页面上注入任意 CSS。
79+
现在 `ratio` 只接受两个轨道尺寸（`'1fr 240px'`），`max_width` 只接受一个纯 CSS 长度。
80+
81+
如果你的站点此前一直用着某个被主题静默纠正过的值，升级后会看到新的告警。这正是目的所在——
82+
升级后用 `--panicOnWarning` 构建一次，把它们找出来。
83+
84+
## OpenAPI 与终端录像尊重其他输出 {#outputs}
85+
86+
Oink 的每个组件都只渲染一次，然后适配它所在的输出：交互 HTML、静态打印、
87+
给智能体读的纯 Markdown，以及 RSS。已有十六个组件这样做，而 `swagger`、`redoc`、
88+
`asciinema` 没有——它们把交互标记原样渲染进了全部四种输出。
89+
90+
结果是：Markdown 输出里带着 `<div class="td-asciinema">` 和一整块 JSON 配置，
91+
打印页面上是一个本该有播放器的空壳，而单页打印甚至真的下载了播放器运行时，
92+
只为显示一帧静止画面。
93+
94+
现在三者都读取输出格式：
95+
96+
| 输出 | 你会得到 |
97+
| --- | --- |
98+
| HTML | 完整的交互组件 |
99+
| 打印 | 一行带标题的静态链接，地址可见 |
100+
| Markdown / LLMS | 一个纯 Markdown 链接，仅此而已 |
101+
| RSS | 同样的纯链接 |
102+
103+
只有交互 HTML 会登记运行时，因此打印与机器输出不再装载播放器、Swagger 包或 ReDoc 包。
104+
录像与 spec 地址现在同样走统一 URL 策略，而写错的 `speed`、`cols`、`rows` 或标记时间
105+
会告警并被忽略，不再终止构建。
106+
107+
## 其他修复 {#smaller-repairs}
108+
109+
- capabilities 的横条现在按作者写的宽度渲染。模板一直在输出这些宽度，只是样式表从未读取。
110+
- 生成的配置 Schema 与 Hugo 实际解析的结果一致。`hugo.yaml` 的行尾注释此前污染了十一个默认值——
111+
`print.toc` 是以字符串 `"true # section print views…"` 发布的——另有四段注释挂在了错误的键上。
112+
仅用于提示重命名的旧键不再出现在编辑器补全里。
113+
- `hero` 的 `media` 不是一个映射时会告警并丢弃该媒体，而不是终止构建。
114+
115+
## 升级 {#upgrading}
116+
117+
```bash
118+
hugo mod get github.com/pgsty/oink@v0.7.1
119+
hugo mod tidy
120+
```
121+
122+
不需要修改内容、配置或模板。升级后建议做一件事：用 `--panicOnWarning` 构建一次。
123+
那些过去被静默纠正的配置现在会开口，而这次构建就是你听到它们的地方。
124+
125+
完整清单见 [CHANGELOG.md](https://github.com/pgsty/oink/blob/main/CHANGELOG.md)。

‎content/docs/about/features.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,14 @@ delivered per page according to what that page actually uses.
4747
Everything the browser needs is committed to the theme repository: Bootstrap,
4848
Font Awesome, four fonts, Lunr, Mermaid, KaTeX, Markmap, Swagger UI, Redoc,
4949
Asciinema, ECharts, Infographic. `VENDOR.json` records the version, source,
50-
licence file and SHA-256 checksum of each of the 28 dependencies; updating a
50+
licence file and SHA-256 checksum of each of the 26 dependencies; updating a
5151
runtime means updating artifact, licence and checksum together.
5252

53-
Where a feature could cause a network request, the theme fails the build rather
53+
Where a feature could cause a network request, the theme leaves it off rather
5454
than reaching out silently: PlantUML without `params.plantuml.svg_image_url`,
5555
Diagrams.net without `params.drawio.drawio_server`, and Algolia without
56-
`appId` / `apiKey` / `indexName` all stop the build.
56+
`appId` / `apiKey` / `indexName` each warn and stay disabled, and a publishing
57+
gate built with `--panicOnWarning` turns that warning into a failure.
5758

5859
Local-first does not extend to what an author adds. All of these are explicit
5960
network choices: external links, remote images and video, iframes, remote API

‎content/docs/about/features.zh.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,9 @@ aliases:
2828

2929
## 本地优先 {#local-first}
3030

31-
浏览器需要的资源全部提交在主题仓库里：Bootstrap、Font Awesome、四款字体、Lunr、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic。`VENDOR.json` 逐项记录 28 个依赖的版本、来源、许可证文件与 SHA-256 校验值，更新某个运行时要同时更新产物、许可证与校验值。
31+
浏览器需要的资源全部提交在主题仓库里：Bootstrap、Font Awesome、四款字体、Lunr、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic。`VENDOR.json` 逐项记录 26 个依赖的版本、来源、许可证文件与 SHA-256 校验值，更新某个运行时要同时更新产物、许可证与校验值。
3232

33-
对可能引起网络请求的功能，主题让构建失败而不是静默连出去：PlantUML 缺 `params.plantuml.svg_image_url`、Diagrams.net 缺 `params.drawio.drawio_server`、Algolia 缺 `appId` / `apiKey` / `indexName`，构建都会报错。
33+
对可能引起网络请求的功能，主题让它保持关闭而不是静默连出去：PlantUML 缺 `params.plantuml.svg_image_url`、Diagrams.net 缺 `params.drawio.drawio_server`、Algolia 缺 `appId` / `apiKey` / `indexName`，都会告警并保持禁用；带 `--panicOnWarning` 的发布关卡会把这条告警变成失败。
3434

3535
本地优先不覆盖作者自己添加的内容。以下都是显式的网络选择：外部链接、远程图片与视频、iframe、远程 API 规范；Algolia、Google 自定义搜索这类托管搜索；分析、评论与其它 SaaS 集成；作者主动配置远程渲染器的 PlantUML 与 Diagrams.net。用到它们的页面仍然是有效页面，但站点不应再宣称这些页面可以完全离线使用。
3636

‎content/docs/admin/analytics.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ To give a shared link an image, set `images` in front matter:
143143

144144
```yaml {title="any page"}
145145
---
146-
title: OINK v0.7.0 released
146+
title: OINK v0.7.1 released
147147
images: [/images/releasenote.webp]
148148
---
149149
```

‎content/docs/admin/analytics.zh.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ canonical 由 `baseURL` 拼出。`baseURL` 配错时 canonical 会把搜索引
114114

115115
```yaml {title="任意页面"}
116116
---
117-
title: OINK v0.7.0 发布
117+
title: OINK v0.7.1 发布
118118
images: [/images/releasenote.webp]
119119
---
120120
```

‎content/docs/admin/upgrade.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ A production site pins a release tag or an immutable commit, follows no branch,
3737
and does not use `@latest`:
3838

3939
```bash {title="Terminal"}
40-
hugo mod get github.com/pgsty/oink@v0.7.0 # the tag from the release notes
40+
hugo mod get github.com/pgsty/oink@v0.7.1 # the tag from the release notes
4141
hugo mod tidy
4242
hugo mod graph | grep github.com/pgsty/oink
4343
```
@@ -51,7 +51,7 @@ module github.com/pgsty/oink.pgsty.com
5151

5252
go 1.26.6
5353

54-
require github.com/pgsty/oink v0.7.0
54+
require github.com/pgsty/oink v0.7.1
5555
```
5656

5757
> [!DANGER] A local module replacement overrides that pin

‎content/docs/admin/upgrade.zh.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ aliases:
2929
生产站点固定发布标签或不可变 commit，不跟随分支，也不用 `@latest`：
3030

3131
```bash {title="终端"}
32-
hugo mod get github.com/pgsty/oink@v0.7.0 # 换成发布注记里的标签
32+
hugo mod get github.com/pgsty/oink@v0.7.1 # 换成发布注记里的标签
3333
hugo mod tidy
3434
hugo mod graph | grep github.com/pgsty/oink
3535
```
@@ -41,7 +41,7 @@ module github.com/pgsty/oink.pgsty.com
4141

4242
go 1.26.6
4343

44-
require github.com/pgsty/oink v0.7.0
44+
require github.com/pgsty/oink v0.7.1
4545
```
4646

4747
> [!DANGER] 本地模块替换会盖掉这个固定版本

0 commit comments

Comments
 (0)