Zine v0.14.0

# 开发日志 | Zine 来源: https://zine-ssg.io/log/ ## 关于 这是一个经过筛选的、非详尽的变更列表，旨在帮助用户快速了解自上次查看以来所进行的改进。您可以通过 RSS (https://zine-ssg.io/log/index.xml) 订阅此页面。 ## 安全升级 升级 Zine 可能会因 bug 或重大变更而改变您网站的渲染方式。阅读更新日志有助于您做好准备，但为了全面确保您的网站外观符合预期，我建议遵循以下流程： - `zine release -o old`（使用**旧版** Zine） - `zine release -o new`（使用**新版** Zine） - `diff -ru old new` 此时，您需要自行决定差异中的任何更改是否符合预期。如果您在更新日志中未提及的改动中发现变化，那可能是某个 bug 导致的，如果遇到这种情况，非常欢迎您提交可复现的 bug 报告。 更多实用的 diff 命令示例 常规的 diff 是基于行的，但有时您会更容易想要找出行内具体哪个词发生了变化。此命令会高亮显示各个单词： - `git diff --word-diff=color --no-index old new` 此命令会高亮显示各个字符，对于快速检测空白字符更改很有用： - `git diff --no-index --word-diff-regex=. old new` `delta` (https://dandavison.github.io/delta/introduction.html) 是一个跨平台的 diff 工具，默认支持单词差异和语法高亮（您无需为 git 配置它，即可将其作为独立的 diff 工具使用）： - `delta old new` ## v0.14.0 (https://zine-ssg.io/log/#v0.14.0) 2026-09-03 这是一个次要版本发布（相对于*补丁*发布而言），因为之前能成功构建的网站，现在有可能会遇到构建错误，即使 **Zine 的功能集没有重大变更**。 ### 错误修复 - 更新了 Zeit（日期时间依赖），增加了对 `America/Santiago` 时区的支持。 - 全面检修了 SuperMD 分析 cmark AST 的方式，修复了一系列 bug，这些 bug 导致某些嵌套元素无法被正确分析，从而将 Scripty 表达式原样打印出来。旧代码是我刚开始开发 Zine 时写的，其中存在许多关于 Markdown 内容结构的错误假设，现在这些都已得到纠正。**以前 SuperMD 中一些内联的 HTML 可能无法被正确捕获（并转化为错误），但现在情况已不同。** 尽管重写在测试和已知网站中未引起任何回退，但强烈建议在升级到此版本的 Zine 时，使用安全的升级流程（使用 diff 工具），以便立即发现任何潜在问题。 - 修复了 `$page.leaves()`（SuperHTML）中的几个 bug，在这些 bug 中，当某个章节页面没有子页面时，它错误地将其包含在输出中（这是不正确的，因为文件名决定了页面是否是一个章节）。 - 修复了切换 `draft` 时崩溃的问题。 ### 新特性 - 新增了一个 CLI 标志（`--url-path-prefix PATH`），用于在 Zine 的实时服务器提供服务时覆盖 `url_path_prefix`（#246 (https://github.com/kristoff-it/zine/pull/246)，感谢 mauxanhxanh！）。 - 为 `console` 增加了语法高亮支持，这是一种代表与 shell 交互的元语言。它的作用是高亮显示提示符标记，但可用作在 JS 中实现“复制命令”按钮的基础。请参阅相关文档部分 (https://zine-ssg.io/docs/supermd/#syntax-highlighting)。（5b213f1 (https://radicle.network/nodes/radicle.kristoff.it/zine/patches/5b213f122080d529737cb2b545cbcbf55626b28b)，感谢 mlugg！）。 - 增加了对 NetBSD 的支持，该支持也已添加到我们的发布中（#247 (https://github.com/kristoff-it/zine/pull/247)，感谢 Chavdar Ivanov！）。 - 在 SuperHTML 中新增了 `Array.join`，允许您使用指定的分隔符将字符串或数字数组连接成单个字符串。主要用例是能够正确实现 ``tags``。 ### 网站变更 - 添加了关于如何将 Zine 网站部署到 sourcehut 的文档 (https://zine-ssg.io/docs/deploying/sourcehut-pages/)（#247 (https://github.com/kristoff-it/zine/pull/247)，感谢 Chavdar Ivanov！）。 ## v0.13.0 (https://zine-ssg.io/log/#v0.13.0) 2026-07-19 **此版本包含架构变更，升级后请确保运行 `zine install-schemas`**。 ### 重大变更 - 配置文件中的 `auto_target_blank` 设置已移至新的 `supermd` 字段下，因为现在有更多 supermd 渲染设置可供调整。 之前： ```ziggy .zine_version = "0.12.0", .auto_target_blank = true, // ... ``` 现在： ```ziggy .zine_version = "0.12.0", .supermd = .{ .auto_target_blank = true, } // ... ``` - fontmatter 中的 `skip_subdir` 设置已被删除（它从未起过任何作用）。 - 从现在开始，SuperMD 文档不再允许标题级别跳跃。如果您有一个 “#” 标题后面跟着 “###”，现在将会收到一个构建错误。与此相关，SuperMD 文档现在必须以标题级别 1（“#”）开头。如果您故意从 “##” 开始渲染 ``headings``，则前述 ‘zine.ziggy’ 中的 `supermd` 字段有 `headings_h2` 选项，当设置为 `true` 时，会将级别 1 的标题渲染为 `h2`，依此类推。**请注意，分节内容（`$section`）目前不受此检查限制。** 我的升级建议是，首先理解您是否默认从 “##” 开始每个文档。如果是，那么您可能需要在 ‘zine.ziggy’ 中设置 `headings_h2`，并且需要从所有文件中删减一个标题级别。这里有一个单行命令可以提供帮助（**请在运行它之前确保已提交所有待处理的更改！**）： Linux & Mac： ```bash find . -name "*.smd" -type f -exec perl -pi -e 's/^#//' {} + ``` Windows： ```powershell Get-ChildItem -Recurse -Filter *.smd | % { $p=$_.FullName; $c=[IO.File]::ReadAllText($p,[Text.Encoding]::UTF8); [IO.File]::WriteAllText($p,($c -replace '(?m)^#',''),[Text.Encoding]::UTF8) } ``` 运行命令后，请务必检查生成的差异以查找错误。对于其他人来说，除了可能发现自己偶尔错误地跳过了标题级别外，其他内容不应有任何变化。我在升级自己的网站时就发现了几个这样的例子。 ### 新特性！ - SuperMD 错误信息得到了极大改进。Techatrix 在 #239 (https://github.com/kristoff-it/zine/pull/239) 中开始了这项工作，巧合的是，不久之后我也推动了这项工作，因为我不希望新的“标题级别跳跃”错误令人困惑。 - 在 SuperHTML 中，当构建由 Zine 实时服务器提供服务时，`$build.development` 为 true。 - 在 SuperHTML 中，`$site.index()` 返回站点的根索引页面（即主页）。它与 `$site.page('')` 相同，但对读者来说，您的意图更清晰。 - 您现在可以在 **`index.smd` 文件** 的 frontmatter 中指定 `forbid_subsections`。设置为 true 时，任何子页面都不能使用 `foo/index.smd` 命名样式，因为那将定义一个子章节。用户会被提示将文件命名为 `foo.smd`。此设置有助于确保 `$page.leaves()` 不会跳过那些本应是叶子的页面。 ### 错误修复 - 上个版本宣布了 `$site.custom`，但有一个 bug 阻止了 scripty 访问该数据，抱歉！ - `auto_target_blank` 有些过于积极，当设置为 `true` 时，最终会给所有链接都添加该属性。 - 当尝试将 `:text` 放入自闭合 XML 元素时，SuperHTML 会崩溃。 - 当定义了 `url_path_prefix` 时，实时开发服务器无法提供 livereloading JS 和 websocket 端点。 - 从 `build.zig` 使用 Zine 会导致 Zine 尝试解析您的 Git 标签，这是由一段构建功能引起的，该功能旨在帮助我记住在发布 Zine 时正确创建标签并更新我的 zon 文件。现在，当 Zine 作为依赖项使用时，此功能已禁用。 - 一个 bug 阻止了对 `[](#foo)` 引用的验证，您可能会在此次更新后发现新的损坏的深度链接。 ## new-forum (https://zine-ssg.io/log/#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) 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 的页面，供有需要的用户参考。 ### Setup 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 frontmatter 变更，该变更将在本更新日志条目后面的 frontmatter 升级部分中进行说明。 - 添加了 `$page.leaves()`，它返回目标章节页面子树中的（扁平的）**非章节**页面列表。它接受一个可选参数来限制迭代的长度。此功能对于显示结构化章节中的最新条目很有用。 - 移除了向 `$site.pages()` 传递参数的能力，该功能允许您遍历已知页面列表。它最初是为了简化对一系列手动选择的页面运行相同的 html 片段而创建的，但它完全可以由循环遍历在 frontmatter 中定义的 Ziggy 数组来替代。 旧版： ```superhtml {% for p in $site.pages(['a', 'b', 'c']) %} ... {% endfor %} ``` 新版： ```superhtml {% for p in [$page.site.page('a'), $page.site.page('b'), $page.site.page('c')] %} ... {% endfor %} ``` - 您现在可以向 `$site.page` 传递多个参数，这些参数将成为组成用于查找目标页面的最终路径的组件。这意味着以下调用是等效的： - `$site.page('foo/bar/baz')` - `$site.page('foo', 'bar/baz')` 当路径的一部分是固定的而另一部分是参数化的时候，这会很有用： ```superhtml $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 文件 frontmatter 的数据序列化语言。**直到最近，它可能还是 Zine 最薄弱的环节，但在投入一些关爱后，我很高兴地说现在情况已非如此。** 不幸的是，这付出了一些破坏性变更的代价，我对此深表歉意。我试图将我能想到的所有破坏性变更都放入此版本，以便用户在完成升级后可以一段时间内不受打扰。 一些 Ziggy 语法发生了变化，但最重要的是，解析器和相关工具都已成熟许多，这使得能够突破先前的*死胡同*。 #### 更好的错误信息 如果您曾经写过一个错误的日期，您可能见过这个令人困惑的错误信息： ```text content/index.smd:3:9: .date = @date("1990-01-1T00:00:00"), ^ syntax error: '@' ``` 现在变成这样： ```text content/index.smd:3:9: error: unable to parse date: InvalidCharacter | .date = .date("1990-01-1T00:00:00"), | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` 不幸的是，Zine 目前还无法告诉您日期中的“日”部分缺少一位数字，但这在我的待办事项清单上，最终会直接控制日期解析并提供更好的诊断信息。 #### 编辑器内的 schema 智能感知！ 看看其他同类产品（其他 SSG），我相信这目前是 Zine 独有的功能。要解锁此能力： 1. 您的编辑器必须配置为针对 `.ziggy`、`.ziggy-schema` 和 `.smd` 文件启动 Ziggy LSP。将来 SuperMD 将有一个专用的 LSP，但目前 Ziggy 的 LSP 将提供 frontmatter 支持。 2. 您的 Zine 网站中必须安装了正确的 Ziggy Schema 文件。这些文件包含了 Zine 配置文件 (`zine.ziggy`) 和 SuperMD frontmatter 的架构定义。使用 `zine install-schemas` 让 Zine 自动将这些文件的最新副本放置在正确的位置（`zine init` 现在也会生成一个已包含这些文件的项目）。请注意，`install-schemas` 要求您首先更新 `zine.ziggy` 配置文件。 在视频中没有展示，但 `zine.ziggy` 现在也有编辑器内支持了。Ziggy LSP 还没有达到，比如 SuperHTML LSP 那样的完善程度，但它会随着时间的推移而改进。 #### 升级您的网站 Ziggy 文档语法发生了轻微变化，请查看官方文档 (https://ziggy-lang.io/) 获取完整的变更列表。Zine 用户最关心的有以下两点： 1. `@foo` 字面量已消失。 2. 结构体不再有名称。 3. 以上两者功能上已被新引入的标签联合体替代。 4. 结构体现在像 Zig 中一样有一个前导点，所以 `{ .foo = true }` 变成了 `.{ .foo = true }`。 最后请注意，**您可以省略每个结构体字段**，只要它们在 Ziggy Schema 定义中是： - 可选的（类型表达式中有前导 `?`） - 切片（类型表达式中有前导 `[]`） - 字典（类型表达式中有前导 `{:}`） ##### 升级您的 `zine.ziggy` 之前： ```ziggy Site { // ... } ``` 之后： ```ziggy .zine_version = "0.12.0", .site = .simple(.{ // <-- 注意这个点！ // ... }), ``` `.simple` 的内容应保持与之前相同。如果您有一个多语言网站： ```ziggy .zine_version = "0.12.0", .site = .multilingual(.{ // <-- 注意这个点！ // ... }), ``` 在这种情况下，`.simple` 的内容在结构上也应相同**但请注意，您现在可以省略任何在 Ziggy Schema 定义中为可选、切片或字典的结构体字段。