Zine 0.12.0

# 开发日志 | Zine 源码：https://zine-ssg.io/log/?v0.12.0 ## 关于本篇 这是一份非详尽的、精选的变更列表，旨在帮助用户快速了解自上次查看以来有哪些改进。您可以通过 RSS (https://zine-ssg.io/log/index.xml) 订阅此页面。 ## 安全升级 升级 Zine 可能会因 bug 或重大变更而改变网站的渲染方式。阅读变更日志有助于您做好准备，但要完全确认网站显示是否符合预期，建议遵循以下流程： - `zine release -o old`（使用**旧版** Zine） - `zine release -o new`（使用**新版** Zine） - `diff -ru new old` 此时，由您自行决定 diff 中的任何更改是否可取。如果发现变更日志中未提及的更改，则可能是 bug 导致，此时欢迎提交可复现的 bug 报告。 更多有用的 diff 命令示例 普通 diff 是基于行的，但偶尔您会更希望轻松找出行内哪个单词发生了更改。以下命令可以高亮单个单词： - `git diff --word-diff=color --no-index new old` 以下命令可以高亮单个字符，有助于快速检测空白字符的变化： - `git diff --no-index --word-diff-regex=. new old` ## 变更 ### 新论坛 (https://zine-ssg.io/log/?v0.12.0#new-forum) #### 2026-07-09 为了给寻求帮助的用户提供更多空间，并开始将 Zine 的讨论与 Discord 脱钩，我创建了一个新的 Discourse 论坛，邀请 Zine 用户加入，既可以提供和获取使用 Zine 的帮助，也可以讨论静态网站相关的一般话题。 https://zine.discourse.group/ ### v0.12.0 (https://zine-ssg.io/log/?v0.12.0#v0.12.0) #### 2026-06-29 此版本包含一些新特性和一项重大变更。 ### Zine 开发服务器现在支持 Firefox 我终于定位并解决了导致 Firefox 在“过多点击”后停止从开发 Web 服务器加载页面的问题。原来是我忘了 flush，而 Firefox 在页面重新加载时忘了销毁部分升级的 WebSocket 连接（Firefox bug 报告 (https://bugzilla.mozilla.org/show_bug.cgi?id=2051402)）。 ### 现在可以向静态资产添加目录 厌倦了在 `static_assets` 中逐一列出所有字体？现在可以将它们放在 `fonts` 目录中，只需在配置文件中添加该目录即可。或者，您也可以直接创建 `assets/static` 目录，将其作为一种约定，不仅限于字体。 我对这个特性的实现也相当自豪。如果不加注意，这个特性很容易变得比实际需要的计算量更大。另外请注意，如果同一文件被重复包含两次（无论是直接指定还是通过目录包含），Zine 会发出警告。这样做是为了确保您不会陷入这样的困境：自以为已从静态资产中删除某个文件，但实际上由于其他引用，该文件仍被安装。 ### Zine 配置文件现在支持自定义字段 新的 `zine.ziggy` 定义允许您指定一个 `.custom` Ziggy 字典，您可以通过 `$site.custom` 访问。具体外观请参见下方升级指南部分。 ### Codeberg Pages 文档中新增了一个专门介绍部署到 Codeberg Pages 的页面，供有兴趣的用户参考。 ### 设置 Zine 版本 2 GitHub / Codeberg 的 `kristoff-it/setup-zine@v1` Action 要求您指定要获取哪个 Zine 版本，但新的 Ziggy 配置文件支持 `zine_version` 字段，该字段现在应被视为网站所需 Zine 版本的权威来源。将 CI 脚本更新为使用 `kristoff-it/setup-zine@v2`，并移除输入设置，即可享受更无缝的体验。**请注意，现在 Zine 会在网站配置文件中的版本与 Zine 可执行文件版本不匹配时发出警告。** ### SuperHTML Scripty 变更！ - 新增 `$page.subpagesByAuthor()` 和 `$page.subpagesByTag()`，允许您分别查找给定分区的所有子页面中具有指定作者或标签的页面。**之前可以通过手动遍历子页面并基于该属性过滤来实现，但内置函数可以查询索引，从而提供更好的性能。** `byAuthor` 变体依赖于本变更日志后续前置元数据升级部分中提到的 Ziggy 前置元数据变更。 - 新增 `$page.leaves()`，返回目标分区页面子树中**非分区**页面的（扁平）列表。它接受一个可选参数来限制迭代长度。此函数在显示结构化分区中的最新条目时非常有用。 - 移除了向 `$site.pages()` 传递参数的功能，该功能允许您遍历已知页面的列表。最初创建它是为了简化在手动选择的页面列表上运行相同 HTML 片段的操作，但现在完全可以替换为在前置元数据中定义 Ziggy 数组并进行循环。 旧版： `$site.pages(.{ .include = [ "foo", "bar", "baz" ], }),` 新版： 在页面前置元数据的 `custom` 字典中定义数组，然后循环 `$site.pages().filter(...)` 或其他方式。实际上，可以用 `$site.page` 逐一获取。 - 现在可以向 `$site.page` 传递多个参数，这些参数将成为组成目标页面最终路径的组件。这意味着以下调用是等价的： - `$site.page('foo/bar/baz')` - `$site.page('foo', 'bar/baz')` 当您的路径部分固定、部分参数化时，这会很有用： `$site.page('speakers', $page.authors.at(0))` - SuperHTML Scripty 参考文档现在使用略有不同的语法来表示数组。以前 `[String]` 表示字符串数组，现在改为 `[]String`，以便更贴近新版 Ziggy Schema 语法 (https://ziggy-lang.io/docs/builtin-types/)。可变参数函数参数仍表示为 `[String...]`。 ### 新版 Ziggy 升级指南 Ziggy (https://ziggy-lang.io/) 是 Zine 配置文件 (`zine.ziggy`) 和 SuperMD 文件前置元数据中使用的数据序列化语言。**直到最近，它可能还是 Zine 最薄弱的环节，但在经过一番打磨之后，我很高兴地宣布情况已不再如此。** 不幸的是，这带来了一些重大变更，对此我深表歉意。我试图将我能想到的所有重大变更都集中在这个版本中，以便用户在升级完成后能安享一段平静时光。部分 Ziggy 语法发生了变化，但最重要的是，解析器和周边工具都成熟了很多，这让我们能够突破之前的死胡同。 #### 更好的错误信息 如果您曾写过错误的日期，可能见过这个误导性的错误信息： ``` content/index.smd:3:9: .date = @date("1990-01-1T00:00:00"), ^ syntax error: '@' ``` 现在变为： ``` content/index.smd:3:9: error: unable to parse date: InvalidCharacter | .date = .date("1990-01-1T00:00:00"), | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` 遗憾的是，Zine 目前还无法告诉您日期中缺少了一位数字，但直接接管日期解析并提供更好的诊断信息已在我的待办清单上。 #### 编辑器内模式智能！ 纵观其他静态网站生成器，我认为这目前是 Zine 的独有功能。要启用此能力： 1. 您的编辑器必须配置为对 `.ziggy`、`.ziggy-schema` 和 `.smd` 文件启动 Ziggy LSP。将来 SuperMD 会有专用的 LSP，但目前 Ziggy LSP 可提供前置元数据支持。 2. 您必须在 Zine 网站中安装正确的 Ziggy Schema 文件。这些文件包含 Zine 配置文件 (`zine.ziggy`) 和 SuperMD 前置元数据的模式定义。使用 `zine install-schemas` 让 Zine 自动将最新版的这些文件放置在正确位置（`zine init` 现在也会生成一个已包含这些文件的项目）。请注意，`install-schemas` 要求您先更新 `zine.ziggy` 配置文件。视频中没有展示，但 `zine.ziggy` 现在也支持编辑器内支持。Ziggy LSP 的完善程度还没有达到 SuperHTML LSP 的水平，但会逐渐改进。 #### 升级您的网站 Ziggy 文档 Ziggy 文档语法略有变化，请查阅官方文档 (https://ziggy-lang.io/) 了解完整的变更列表。Zine 用户最关心的有以下两点： 1. `@foo` 字面量已消失。 2. 结构体不再有名称。 3. 上述两者已由新引入的标记联合体功能替代。 4. 结构体现在像 Zig 一样需要一个前导点号，因此 `{ .foo = true }` 变为 `.{ .foo = true }`。 最后请注意，**您可以省略任何在 Ziggy Schema 定义中为以下类型的结构体字段**： - 可选的（类型表达式中的前导 `?`） - 切片（类型表达式中的前导 `[]`） - 字典（类型表达式中的 `{:}`） ##### 升级您的 `zine.ziggy` 旧版： ``` Site { // ... } ``` 新版： ``` .zine_version = "0.12.0", .site = .simple(.{ // <-- 注意点号！ // ... }), ``` `.simple` 的内容应与之前保持一致。如果您有多语言网站： ``` .zine_version = "0.12.0", .site = .multilingual(.{ // <-- 注意点号！ // ... }), ``` 同样，`.simple` 的内容在结构上应相同，**但请注意嵌套结构体（例如 `Locale`）现在也需要一个前导点号。** 提醒一下，您现在还可以在配置文件中定义自定义属性，这些属性可通过 `$site.custom` 访问： ``` .zine_version = "0.12.0", .site = .simple(.{ // <-- 注意点号！ // ... }), .custom = { // <-- 字典没有点号！ "my": ["custom", "values!"], } ``` 修复 `zine.ziggy` 后，最好运行 `zine install-schemas`。 ## 重大变更 新的 Zine 配置文件模式新增了一个设置：`auto_target_blank`，用于定义 SuperMD 生成的外部链接是否默认带有 `target="_blank"` 属性。Zine 之前默认自动添加这些属性，而现在默认关闭。如果您想保留之前的行为，请将此设置为 `true`。请注意，您始终可以在定义链接时使用显式的 Scripty 语法来覆盖此设置： ``` [my link]($link.url(https://example.com).new(true)) ``` ##### 升级您的前置元数据 - `@date` 已替换为 `.date` 和 `.unix`（后者接受 Unix 时间戳而非字符串）。 - `.author` 已替换为 `.authors`，该字段可以省略，接受一个字符串列表。 - 与配置文件一样，结构体现在需要前导点号，这会影响您如果： - 没有为前置元数据使用无括号的顶层语法 - 定义了 `alternatives`（每个都是一个结构体） - 在自定义数据字典中使用了结构体语法 - 一些以前必填的字段现在变为可选，请参阅前置元数据 Ziggy Schema 了解更多信息（在 Zine 文档的 SuperMD 部分也有）。简而言之，示例如下： 旧版： ``` --- .title = "Home", .date = @date("2018-07-06T00:00:00"), .description = "", .author = "Loris Cro", .layout = "index.shtml", .alternatives = [{ .name = "rss", .layout = "rss.xml", .output = "/index.xml", }], --- ``` 新版： ``` --- .title = "Home", .date = .date("2018-07-06T00:00:00"), .layout = "index.shtml", .alternatives = [.{ // <-- 注意点号！ .name = "rss", .layout = "rss.xml", .output = "/index.xml", }], --- ``` 对于 `.author` 字段，我建议对于个人网站（作者通常为同一人）在模板中硬编码作者姓名。新的 `.authors` 字段接受字符串列表，适用于更复杂的需求。如果您确实有更复杂的作者管理需求，别忘了可以使用 `.authors` 字段中的条目不仅作为“可直接打印”的名称，还可以作为页面导航的键（例如每个作者有专用页面），或者作为定义在某处的 `.custom` 字段（例如 `$site.custom`）的键。 ### v0.11.3 (https://zine-ssg.io/log/?v0.12.0#v0.11.3) #### 2026-06-17 此版本将 Zig 从 0.15.0 一路升级到 0.17.0-dev。我没有为 Zig 0.16.0 发布版本，因为 translate-c 存在回归问题，现已修复。此版本包含相对较少且较小的面向用户的改进，主要目的是将 Zig 升级过程带来的潜在 bug 与即将对 Zine 进行的更改隔离开来。在下一个 Zine 版本中，我将把 Ziggy（.smd 前置元数据语言）更新为语法有所变化的新版本，需要您做一些工作才能使用。 ### Bug 修复与重大变更 - 仅当 `id` 属性有设定值时，才从 SuperMD 中生成 `id` 属性。（#198 (https://github.com/kristoff-it/zine/pull/198)，感谢 GasInfinity！）。 - 修复了一个 bug：空的 `index.smd`（即无内容、无前置元数据）会被 Zine 部分识别，创建出一个有问题的分区，在某些情况下会导致 Zine 崩溃。 - 修复了一个 bug：将 `.draft` 字段从 `false` 切换为 `true` 会导致 Zine 开发服务器崩溃。 ### 新特性 - 在 SuperMD 中，您现在可以指定音频嵌入，如下所示：`[](<$audio.asset('music.wav')>)`（#195 (https://github.com/kristoff-it/zine/pull/195)，感谢 PowerUser64！）。 - 在 SuperHTML 中，为整数添加了 `.minus()` 方法（#188 (https://github.com/kristoff-it/zine/pull/188)，感谢 acc1729！）。 - 发布版本现在包含 FreeBSD 的 tarball（#202 (https://github.com/kristoff-it/zine/pull/202)，感谢 dmarker！）。 - Zig 构建系统集成已更新至 Zig 0.17.0-dev（参见 Zon 文件了解更多信息）。 ### v0.11.2 (https://zine-ssg.io/log/?v0.12.0#v0.11.2) #### 2025-11-21 此版本修复了自上次发布以来发现的一些 bug，现有网站无需任何更改。下一个版本将合并新版本的 Ziggy（SuperMD 前置元数据中使用的数据语言），届时将需要您更改内容文件，请做好冲击准备 :^) 但作为交换，Ziggy 语言有了很大改进，您最终将能获得出色的代码智能，从而更轻松地正确编写前置元数据。更多详情敬请期待下个版本。 修复： - 修复了涉及绝对路径时替代链接的渲染问题。 - `zine init` 模板文件是在 superhtml 具有良好自动格式化支持之前创建的，导致首次保存文件时大量代码发生移动（使用了具有更精细自动格式化行为的新版 superhtml）。现在嵌入 Zine 的模板文件已经过格式化，为您提供更好的开箱即用体验。 - 由于 bug 和缺少功能，以前无法从 SuperMD 链接到网站首页。现在您可以使用普通语法（`[home](/)`）或显式 Scripty 语法（`$link.site()`，此版本新增）。 - Zig 构建系统集成：如果您指定了 `path` 选项，serve 步骤现在能正确使用预构建的 zine，之前它会忽略该设置，始终从头构建 Zine。 ### v0.11.1 (https://zine-ssg.io/log/?v0.12.0#v0.11.1) #### 2025-07-26 又一轮 bug 修复，此版本已解决所有已知 bug！ - `release` 和 `serve` 命令在处理某些资产路径时方式不一致，导致根据路径是绝对还是相对，资产路径可能只对其中一个命令有效。现在所有路径在使用前都已标准化。 - 静态资产的绝对安装路径会被 `release` 解释为绝对路径，从而导致尝试在输出目录之外安装资产，通常而言这并不理想。现在我们规范化路径，确保不会错误地覆盖您的 `/etc/shadow`（或 `~/.ssh/id_rsa`）。