From f9e138cef0077d6faf2e652c0f8f0dce6611cdf1 Mon Sep 17 00:00:00 2001
From: xihale <xihale.top@qq.com>
Date: Sun, 20 Jul 2025 08:13:07 +0800
Subject: [PATCH 1/3] new: zigcc-zine-migration

---
 .../post/2025-07-19-zigcc-zine-migration.smd  | 166 ++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 content/post/2025-07-19-zigcc-zine-migration.smd

diff --git a/content/post/2025-07-19-zigcc-zine-migration.smd b/content/post/2025-07-19-zigcc-zine-migration.smd
new file mode 100644
index 0000000..ff325b8
--- /dev/null
+++ b/content/post/2025-07-19-zigcc-zine-migration.smd
@@ -0,0 +1,166 @@
+---
+.title = "迁移 zigcc 主页到 zine",
+.date = @date("2025-07-19"),
+.author = "xihale",
+.layout = "post.shtml",
+---
+
+# [为什么要迁移]($section.id("为什么要迁移"))
+
+原先是基于 hugo 和 docsy 主题搭建的。
+
+1. hugo 有一些小问题（比如 footer 里 md 解析得有些 奇怪的行为）
+2. docsy 主题不好看（Hugo 确实很强大，但是 Hugo 给我的初步印象是：生态太老了，无论是技术上和审美上。）
+3. 代码高亮难看
+   主流的代码高亮库有 `highlight.js` `prime.js` `shiki.js`，效果最好的是 `shiki.js`，然而，zine 对于 zig 的高亮比他们都要更加细致，由此我可以做更多细粒控制。（代价是，对其他语言的 parse 做得很烂，这里我暂时也不清楚究竟是怎么回事，上有应该是调用 tree-sitter 来解析的）
+4. 生成到其他格式（比如 pdf ）比较不方便
+   但是 zine 的 layout 和 scripty 等支持天然让我们的组织结构具有了极大的灵活性，相信在不远的将来我们便可以实现 pdf generation！（RSS 生成也是同理）
+5. 迁移后，后端 build 性能和前端 render 性能都显著提高。（当然，这也是因为 组织结构的简化带来的好处，毕竟基于 zine 的架构，结构比较简单。
+
+当然，还有一个很重要的原因是：使用 zine 可以反哺 zig 生态的发展，我觉得这是我们这些做社区的人应该背负的责任，正如 刘家财 对我说的一句话：“如果我们都不用，那更不会有别人用了。”  
+不出意料，本次 迁移 就发现了很多 zine 的问题和可以改进的点子。
+
+# [什么是 zine（zine 的组织结构）]($section.id("什么是zine"))
+
+首先我们看看 最简 sample 的 tree （基于 `zine init` 删减而来）
+
+```sh
+.
+├── assets # 资源文件
+├── content # 内容文件
+│   ├── about.smd
+│   ├── blog
+│   │   ├── first-post
+│   │   │   ├── fanzine.jpg
+│   │   │   └── index.smd
+│   │   ├── index.smd
+│   │   └── second-post.smd
+│   ├── devlog
+│   │   ├── 1989.smd
+│   │   ├── 1990.smd
+│   │   └── index.smd
+│   └── index.smd
+├── layouts # 所有的 smd 必须对应且只对应 一个 layout 文件
+│   ├── blog.shtml
+│   ├── blog.xml # RSS 支持
+│   ├── devlog-archive.shtml
+│   ├── devlog.shtml
+│   ├── devlog.xml # RSS 支持
+│   ├── index.shtml
+│   ├── page.shtml
+│   ├── post.shtml
+│   └── templates # templates 可以被其他 layout 文件 extend 以达到代码复用的目的
+│       └── base.shtml
+└── zine.ziggy # zine 配置文件
+```
+
+<https://zine-ssg.io/>
+一定要看一下官网文档。
+
+content 和 layout 这个结构非常平凡，前端框架一般都会采用这种结构，而像 hexo, hugo 等则是已经帮你写好了 theme 文件，然后暴露配置来做细粒度控制。
+
+# [如何迁移]($section.id("如何迁移"))
+
+最基本也是最重要的是：你需要将你的文件转换到 smd 和 shtml 的专属语法，他们很像，但还是有很多不一样的。
+比如：
+
+1. smd 不推荐直接嵌入 html 代码，所以你的 html 代码要用 ` ```=html` 包裹
+2. 小标题不会自动办理 warp 并且生成 id 和 hash 链接，要用 `$Section.id` (id 不能包含空格)
+3. 资源引入可以用 scripty api，也可以放在 public 下面再引用 `/xxx`
+
+下面是此次 zigcc 主页的迁移日志（大概版）
+
+由于本项目不涉及 Hugo 的专有语法（`{% ... %}`），所以此处不包括此内容的处理
+
+# [转换文件到 smd]($section.id("content2smd"))
+
+一开始我没有考虑到 org 的复杂性，让 AI 帮忙写了 md to smd 的脚本，运作良好，但是 org 的脚本就不太行，所以改用 pandoc。
+最终效果很好，但还是有一些东西要手动改，比如资源引入，html 代码块的嵌入等等。
+
+以下是用来转换 org 到 smd 的 fish 脚本，理论来说 md 也可以这么做。
+
+注意，这里其实是转换到了 md 格式。
+
+```fish
+for f in *.org
+  pandoc -s $f -t gfm -o (path change-extension "smd" $f)
+end
+```
+
+暂时可以先不去手动去做 smd 适配，先把 layout 写好再搞要方便些（可以实时预览）。
+
+# [frontmatter]($section.id("frontmatter"))
+
+zine 的 frontmatter 采用 `ziggy` 语法
+
+ziggy 很简单，基本上是对标 zig 语法（某些细微处有些不一样）
+
+[ziggy 官网](https://ziggy-lang.io/) 提供了一个 [convertor](https://ziggy-lang.io/documentation/ziggy-convert/) ，可以将 YAML/TOML/JSON 转换到 ziggy 格式
+
+```zig
+---
+.title = "Zig comptime",
+.date = @date("2025-01-23T12:00:00+08:00"),
+.author = "xihale",
+.layout = "post.shtml",
+.draft = false,
+---
+```
+
+# [layout]($section.id("layout"))
+
+由于我不喜欢 docsy 的样式，所以我选择重新设计一套 layout，采用简约风格，也就是目前这个样子，有很多地方还是有点丑，toc 以后可能还要改。
+
+1. zine 采用 [id Slot](https://zine-ssg.io/docs/superhtml/#super), 灵活性比普通的 Slot 要强一些，可以分开 head Slot 和 content Slot, 这样就很方便资源引用等操作的细粒度控制。
+2. 需要注意的是，可以使用 `<ctx>` 来简化代码组织结构
+
+更加细粒度的控制可以在 `smd` 文件中通过 ziggy frontmatter `.custom` 字段实现
+
+比如这样：
+
+```zig
+.custom{
+  .math = true,
+}
+```
+
+```html
+<ctx :if="$page.custom.getOr('math', false)">
+  <link
+    href="https://lf9-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/katex.min.css"
+    crossorigin="anonymous"
+    rel="stylesheet"
+  />
+  <script
+    defer
+    src="https://lf6-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/katex.min.js"
+    crossorigin="anonymous"
+  ></script>
+  <script
+    defer
+    src="https://lf6-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/contrib/auto-render.min.js"
+    crossorigin="anonymous"
+    onload="renderMathInElement(document.body);"
+  ></script>
+</ctx>
+```
+
+# [预览+检查]($section.id("预览+检查"))
+
+这时候就要手动修改那些不合格的格式，通过 `zine` 预览，查看效果之后看看什么地方渲染不对，然后回到 smd 中修改即可！
+
+这一步骤比较繁琐，几乎相当于需要重新审一遍所有的文章，然后还要根据具体问题进行具体修改。（需要注意的是， zine 目前还不是很完善，很多东西的报错是有问题的，需要有点耐心）
+
+# [deploying]($section.id("deploying"))
+
+https://zine-ssg.io/docs/deploying/github-pages/
+https://zine-ssg.io/docs/deploying/cloudflare-pages/
+
+Actions 可以参考 zine-ssg 或者 zigcc 主页。
+
+# [其他经验]($section.id("其他经验"))
+
+1. shtml 并非是只是基于 html 加东西，他对于 html 的语法有严苛的要求（某些要求可能会与编码者本身的习惯相冲突）。
+2. scripty 采用链式语法。
+
+遇到问题不要慌张，看看报错，看看文档，多翻翻 zine-ssg 和 ziglang 主页 的源码。

From e74799335569a157b73192969b46c0d0b27d364f Mon Sep 17 00:00:00 2001
From: jiacai2050 <dev@liujiacai.net>
Date: Sun, 20 Jul 2025 21:49:26 +0800
Subject: [PATCH 2/3] polish

---
 .../post/2025-07-19-zigcc-zine-migration.smd  | 166 --------------
 content/post/2025-07-19-zine-migration.smd    | 211 ++++++++++++++++++
 2 files changed, 211 insertions(+), 166 deletions(-)
 delete mode 100644 content/post/2025-07-19-zigcc-zine-migration.smd
 create mode 100644 content/post/2025-07-19-zine-migration.smd

diff --git a/content/post/2025-07-19-zigcc-zine-migration.smd b/content/post/2025-07-19-zigcc-zine-migration.smd
deleted file mode 100644
index ff325b8..0000000
--- a/content/post/2025-07-19-zigcc-zine-migration.smd
+++ /dev/null
@@ -1,166 +0,0 @@
----
-.title = "迁移 zigcc 主页到 zine",
-.date = @date("2025-07-19"),
-.author = "xihale",
-.layout = "post.shtml",
----
-
-# [为什么要迁移]($section.id("为什么要迁移"))
-
-原先是基于 hugo 和 docsy 主题搭建的。
-
-1. hugo 有一些小问题（比如 footer 里 md 解析得有些 奇怪的行为）
-2. docsy 主题不好看（Hugo 确实很强大，但是 Hugo 给我的初步印象是：生态太老了，无论是技术上和审美上。）
-3. 代码高亮难看
-   主流的代码高亮库有 `highlight.js` `prime.js` `shiki.js`，效果最好的是 `shiki.js`，然而，zine 对于 zig 的高亮比他们都要更加细致，由此我可以做更多细粒控制。（代价是，对其他语言的 parse 做得很烂，这里我暂时也不清楚究竟是怎么回事，上有应该是调用 tree-sitter 来解析的）
-4. 生成到其他格式（比如 pdf ）比较不方便
-   但是 zine 的 layout 和 scripty 等支持天然让我们的组织结构具有了极大的灵活性，相信在不远的将来我们便可以实现 pdf generation！（RSS 生成也是同理）
-5. 迁移后，后端 build 性能和前端 render 性能都显著提高。（当然，这也是因为 组织结构的简化带来的好处，毕竟基于 zine 的架构，结构比较简单。
-
-当然，还有一个很重要的原因是：使用 zine 可以反哺 zig 生态的发展，我觉得这是我们这些做社区的人应该背负的责任，正如 刘家财 对我说的一句话：“如果我们都不用，那更不会有别人用了。”  
-不出意料，本次 迁移 就发现了很多 zine 的问题和可以改进的点子。
-
-# [什么是 zine（zine 的组织结构）]($section.id("什么是zine"))
-
-首先我们看看 最简 sample 的 tree （基于 `zine init` 删减而来）
-
-```sh
-.
-├── assets # 资源文件
-├── content # 内容文件
-│   ├── about.smd
-│   ├── blog
-│   │   ├── first-post
-│   │   │   ├── fanzine.jpg
-│   │   │   └── index.smd
-│   │   ├── index.smd
-│   │   └── second-post.smd
-│   ├── devlog
-│   │   ├── 1989.smd
-│   │   ├── 1990.smd
-│   │   └── index.smd
-│   └── index.smd
-├── layouts # 所有的 smd 必须对应且只对应 一个 layout 文件
-│   ├── blog.shtml
-│   ├── blog.xml # RSS 支持
-│   ├── devlog-archive.shtml
-│   ├── devlog.shtml
-│   ├── devlog.xml # RSS 支持
-│   ├── index.shtml
-│   ├── page.shtml
-│   ├── post.shtml
-│   └── templates # templates 可以被其他 layout 文件 extend 以达到代码复用的目的
-│       └── base.shtml
-└── zine.ziggy # zine 配置文件
-```
-
-<https://zine-ssg.io/>
-一定要看一下官网文档。
-
-content 和 layout 这个结构非常平凡，前端框架一般都会采用这种结构，而像 hexo, hugo 等则是已经帮你写好了 theme 文件，然后暴露配置来做细粒度控制。
-
-# [如何迁移]($section.id("如何迁移"))
-
-最基本也是最重要的是：你需要将你的文件转换到 smd 和 shtml 的专属语法，他们很像，但还是有很多不一样的。
-比如：
-
-1. smd 不推荐直接嵌入 html 代码，所以你的 html 代码要用 ` ```=html` 包裹
-2. 小标题不会自动办理 warp 并且生成 id 和 hash 链接，要用 `$Section.id` (id 不能包含空格)
-3. 资源引入可以用 scripty api，也可以放在 public 下面再引用 `/xxx`
-
-下面是此次 zigcc 主页的迁移日志（大概版）
-
-由于本项目不涉及 Hugo 的专有语法（`{% ... %}`），所以此处不包括此内容的处理
-
-# [转换文件到 smd]($section.id("content2smd"))
-
-一开始我没有考虑到 org 的复杂性，让 AI 帮忙写了 md to smd 的脚本，运作良好，但是 org 的脚本就不太行，所以改用 pandoc。
-最终效果很好，但还是有一些东西要手动改，比如资源引入，html 代码块的嵌入等等。
-
-以下是用来转换 org 到 smd 的 fish 脚本，理论来说 md 也可以这么做。
-
-注意，这里其实是转换到了 md 格式。
-
-```fish
-for f in *.org
-  pandoc -s $f -t gfm -o (path change-extension "smd" $f)
-end
-```
-
-暂时可以先不去手动去做 smd 适配，先把 layout 写好再搞要方便些（可以实时预览）。
-
-# [frontmatter]($section.id("frontmatter"))
-
-zine 的 frontmatter 采用 `ziggy` 语法
-
-ziggy 很简单，基本上是对标 zig 语法（某些细微处有些不一样）
-
-[ziggy 官网](https://ziggy-lang.io/) 提供了一个 [convertor](https://ziggy-lang.io/documentation/ziggy-convert/) ，可以将 YAML/TOML/JSON 转换到 ziggy 格式
-
-```zig
----
-.title = "Zig comptime",
-.date = @date("2025-01-23T12:00:00+08:00"),
-.author = "xihale",
-.layout = "post.shtml",
-.draft = false,
----
-```
-
-# [layout]($section.id("layout"))
-
-由于我不喜欢 docsy 的样式，所以我选择重新设计一套 layout，采用简约风格，也就是目前这个样子，有很多地方还是有点丑，toc 以后可能还要改。
-
-1. zine 采用 [id Slot](https://zine-ssg.io/docs/superhtml/#super), 灵活性比普通的 Slot 要强一些，可以分开 head Slot 和 content Slot, 这样就很方便资源引用等操作的细粒度控制。
-2. 需要注意的是，可以使用 `<ctx>` 来简化代码组织结构
-
-更加细粒度的控制可以在 `smd` 文件中通过 ziggy frontmatter `.custom` 字段实现
-
-比如这样：
-
-```zig
-.custom{
-  .math = true,
-}
-```
-
-```html
-<ctx :if="$page.custom.getOr('math', false)">
-  <link
-    href="https://lf9-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/katex.min.css"
-    crossorigin="anonymous"
-    rel="stylesheet"
-  />
-  <script
-    defer
-    src="https://lf6-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/katex.min.js"
-    crossorigin="anonymous"
-  ></script>
-  <script
-    defer
-    src="https://lf6-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/contrib/auto-render.min.js"
-    crossorigin="anonymous"
-    onload="renderMathInElement(document.body);"
-  ></script>
-</ctx>
-```
-
-# [预览+检查]($section.id("预览+检查"))
-
-这时候就要手动修改那些不合格的格式，通过 `zine` 预览，查看效果之后看看什么地方渲染不对，然后回到 smd 中修改即可！
-
-这一步骤比较繁琐，几乎相当于需要重新审一遍所有的文章，然后还要根据具体问题进行具体修改。（需要注意的是， zine 目前还不是很完善，很多东西的报错是有问题的，需要有点耐心）
-
-# [deploying]($section.id("deploying"))
-
-https://zine-ssg.io/docs/deploying/github-pages/
-https://zine-ssg.io/docs/deploying/cloudflare-pages/
-
-Actions 可以参考 zine-ssg 或者 zigcc 主页。
-
-# [其他经验]($section.id("其他经验"))
-
-1. shtml 并非是只是基于 html 加东西，他对于 html 的语法有严苛的要求（某些要求可能会与编码者本身的习惯相冲突）。
-2. scripty 采用链式语法。
-
-遇到问题不要慌张，看看报错，看看文档，多翻翻 zine-ssg 和 ziglang 主页 的源码。
diff --git a/content/post/2025-07-19-zine-migration.smd b/content/post/2025-07-19-zine-migration.smd
new file mode 100644
index 0000000..600c0a4
--- /dev/null
+++ b/content/post/2025-07-19-zine-migration.smd
@@ -0,0 +1,211 @@
+---
+.title = "ZigCC 网站迁移至 Zine 实战复盘",
+.date = @date("2025-07-19"),
+.author = "xihale",
+.layout = "post.shtml",
+---
+
+本文复盘了 ZigCC 社区网站从 Hugo 迁移至 Zine 的全过程，旨在分享其中的经验与思考，为有类似需求的朋友提供参考。
+
+# [为何选择 Zine？]($section.id("为何选择-Zine"))
+
+我们最初使用 Hugo 及其 Docsy 主题搭建网站，但在使用过程中遇到了一些痛点，促使我们寻找新的解决方案。选择迁移至 Zine 主要基于以下几点考量：
+
+1.  **解决 Hugo 的既有问题**：Hugo 本身非常强大，但在某些细节上存在问题，例如 Markdown 在页脚（footer）中的解析行为不符合预期。
+2.  **追求现代设计美学**：Docsy 主题乃至 Hugo 的部分生态，在技术和审美上略显陈旧。我们希望网站风格更加现代化、简约。
+3.  **更精细的代码高亮**：主流高亮库如 `highlight.js`, `prism.js` 和 `shiki.js` 中，`shiki.js` 效果最佳。然而，Zine 对 Zig 代码的语法高亮比它们更为细致，提供了更强的自定义控制能力。（代价是 Zine 对其他语言的解析支持尚不完善，其底层似乎是调用 tree-sitter 实现的）。
+4.  **灵活的内容格式生成**：Zine 的布局（Layout）和 Scripty API 赋予了项目结构极大的灵活性，使得未来生成 PDF 或其他格式的文档变得可行，RSS Feed 的生成也同样受益。
+5.  **显著的性能提升**：迁移后，无论是后端的构建速度还是前端的渲染性能都有了明显提升。这部分也得益于 Zine 架构带来的项目结构简化。
+
+当然，还有一个至关重要的原因：**拥抱并反哺 Zig 生态**。正如 ZigCC 发起者刘家财所说：
+> “如果我们自己都不用，那更不会有别人用了。”
+
+作为 Zig 社区的一份子，我们有责任参与到生态建设中。果不其然，这次迁移过程也让我们发现了 Zine 的一些待解决问题和潜在的改进点。
+
+# [Zine 简介]($section.id("Zine简介"))
+
+Zine 是一个现代、高效的静态网站生成器。理解其核心组织结构是上手的第一步。一个最简化的 Zine 项目（通过 `zine init` 创建并删减后）目录结构如下：
+
+```sh
+.
+├── assets/      # 存放 CSS、图片等静态资源
+├── content/     # 存放网站内容，通常是 smd 文件
+│   ├── about.smd
+│   └── index.smd
+├── layouts/     # 存放布局模板，每个 smd 文件都对应一个 shtml 布局
+│   ├── index.shtml
+│   ├── page.shtml
+│   └── templates/ # 模板可以被其他布局继承，以实现代码复用
+│       └── base.shtml
+└── zine.ziggy   # Zine 项目的全局配置文件
+```
+
+上面的目录结构和 Hugo 类似， `zine.ziggy` 是网站的配置文件，ZigCC 的配置如下：
+```zig
+Site {
+    .title = "Zig 语言中文社区",
+    .host_url = "https://ziglang.cc",
+    .content_dir_path = "content",
+    .layouts_dir_path = "layouts",
+    .assets_dir_path = "assets",
+    .static_assets = [],
+}
+```
+
+在 HTML 渲染方面，Zine 与 Hugo 相差甚远，Zine 自创了两种新格式来进行数据的组织：
+- [SuperMD](https://zine-ssg.io/docs/supermd/) 格式 - 扩展了标准 Markdown，允许定义嵌入式资源和语义结构，解决了传统 Markdown 无法表达复杂内容而不使用内联 HTML 的局限性。
+- [SuperHTML](https://zine-ssg.io/docs/superhtml) 模板系统 - 扩展的 HTML 格式专注于正确的模板逻辑表达。设计确保“不可能生成语法错误的 HTML，大多数错误会在构建时被发现”。
+
+这两者本质上就是 markdown 与 html，Zine 做的增强是为它们实现了其自创的表达式语言 [scripty](https://zine-ssg.io/docs/scripty/)。因此下面重点介绍 Scripty 的用法。
+
+## [Scripty]($section.id('scripty'))
+
+Scripty 是一个非常小的语言， 专门用于嵌入到字符串中，为 SuperMD 和 SuperHTML 提供动态内容生成能力。 因此 Scripty 没有任何类型的语句或代码块，只能用于构建表达式。
+- 所有表达式都以 `$` 开头
+- 支持字段导航： `$foo.bar.baz`
+- 支持函数调用： `$foo.bar.qux('arg1', "arg2")`
+- 支持基本字面量：字符串、整数、浮点数、布尔值
+
+这里举一示例来说明 Scripty 在 SuperMD 和 SuperHTML 中的写法：
+
+```html
+<ctx about="$site.page('about')">
+  <a href="$ctx.about.link()" text="$ctx.about.title"></a>
+</ctx>
+```
+
+```markdown
+Check out our [about page]($link.page('about')).
+```
+
+既然是表达式语言，scripty 在多层嵌套时才能体现其威力：
+
+```html
+<h1 class="$page.title.len().gt(25).then('long')">...</h1>
+```
+
+如果当前页面标题长度小于 25 时，就有输出：
+
+```html
+<h1 class="long">...</h1>
+```
+
+关于 SuperMD 和 SuperHTML 的用法这里不再赘述，推荐大家去阅读 Zine 的官方文章。
+
+# [迁移步骤详解]($section.id("迁移步骤详解"))
+
+整个迁移过程可以分为内容转换、布局设计、预览调试和最终部署几个关键步骤。
+
+## [内容格式转换]($section.id("内容格式转换"))
+
+迁移的核心工作是将原有内容（本文中主要是 Markdown 和 Org Mode 文件）转换为 Zine 支持的 SuperMarkdown (`.smd`) 格式。
+
+起初，我尝试让 AI 编写 `md` 到 `smd` 的转换脚本，效果尚可。但对于结构更复杂的 Org Mode 文件，脚本难以胜任，因此最终转向使用 Pandoc。
+
+以下是使用 Pandoc 将 `.org` 文件批量转换为 Markdown 格式（并重命名为 `.smd`）的 Fish 脚本，此方法同样适用于 `.md` 文件：
+
+```fish
+# 注意：这里实际上是转换到了 GitHub Flavored Markdown (gfm) 格式
+# 后续仍需手动调整以完全适配 smd 语法
+for f in *.org
+  pandoc -s $f -t gfm -o (path change-extension "smd" $f)
+end
+```
+
+**手动适配要点**：
+
+Pandoc 完成初步转换后，仍需手动调整以适配 `.smd` 和 `.shtml` 的专属语法。常见差异包括：
+
+1.  **HTML 嵌入**：`.smd` 不推荐直接嵌入 HTML。相关代码需要用 ` ```=html` 代码块包裹。
+2.  **章节标题链接**：标题不会自动生成 ID 和锚点链接，需要手动使用 `$section.id("custom-id")` 添加（注意 ID 不能包含空格）。
+3.  **资源引用**：可以使用 Scripty API 或将资源放在 `public` 目录下通过绝对路径 (`/path/to/resource`) 引用。
+
+建议先完成布局文件的编写，在实时预览的环境下再进行这些细致的手动适配，效率更高。
+
+## [处理 Frontmatter]($section.id("处理-Frontmatter"))
+
+Zine 使用 Ziggy 语法作为 Frontmatter 的格式，它与 Zig 语法高度相似。
+
+> [Ziggy 官网](https://ziggy-lang.io/) 提供了一个方便的 [在线转换器](https://ziggy-lang.io/documentation/ziggy-convert/)，可以将 YAML、TOML 或 JSON 格式的 Frontmatter 转换为 Ziggy。
+
+一个典型的 `.smd` 文件 Frontmatter 如下：
+
+```zig
+---
+.title = "Zig comptime",
+.date = @date("2025-01-23T12:00:00+08:00"),
+.author = "xihale",
+.layout = "post.shtml",
+.draft = false,
+---
+```
+
+## [设计布局]($section.id("设计布局"))
+
+由于我们希望采用全新的简约风格，因此我没有沿用 Docsy 的样式，而是重新设计了一套布局。目前的版本虽已上线，但在目录（TOC）等细节上仍有优化空间。
+
+Zine 布局有几个关键特性：
+
+1.  **ID Slot**：Zine 采用 [ID Slot](https://zine-ssg.io/docs/superhtml/#super) 机制，比传统的 Slot 更灵活。例如，你可以将 `<head>` 和内容区的 Slot 分开处理，从而实现对资源加载等操作的精细控制。
+2.  **`<ctx>` 标签**：合理使用 `<ctx>` 标签可以简化模板的逻辑和组织结构。
+
+此外，你还可以通过在 `.smd` 的 Frontmatter 中定义 `.custom` 字段，向布局传递自定义参数，实现更细粒度的控制。
+
+例如，在 `.smd` 中启用数学公式支持：
+
+```zig
+// file: content/your-post.smd
+.custom = .{
+  .math = true,
+},
+```
+
+然后在布局文件中根据此标志加载 KaTeX 库：
+
+```html
+// file: layouts/post.shtml
+<ctx :if="$page.custom.getOr('math', false)">
+  <link
+    href="https://lf9-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/katex.min.css"
+    crossorigin="anonymous"
+    rel="stylesheet"
+  />
+  <script
+    defer
+    src="https://lf6-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/katex.min.js"
+    crossorigin="anonymous"
+  ></script>
+  <script
+    defer
+    src="https://lf6-cdn-tos.bytecdntp.com/cdn/expire-1-M/KaTeX/0.15.2/contrib/auto-render.min.js"
+    crossorigin="anonymous"
+    onload="renderMathInElement(document.body);"
+  ></script>
+</ctx>
+```
+
+## [预览与调试]($section.id("预览与调试"))
+
+完成布局和初步内容转换后，就进入了最繁琐的环节：预览、检查和修正。
+
+运行 `zine` 命令启动本地服务器，实时预览网站效果。逐一检查每篇文章的渲染情况，发现格式错误或显示异常的地方，返回 `.smd` 文件进行修改。
+
+这一步需要极大的耐心，几乎等同于重新校对所有文章。需要注意的是，Zine 目前仍在快速发展中，部分功能的报错信息可能不够明确，需要结合文档和实践耐心排查。
+
+## [部署]($section.id("部署"))
+
+Zine 官方文档提供了详细的部署指南：
+
+-   [Deploying to GitHub Pages](https://zine-ssg.io/docs/deploying/github-pages/)
+-   [Deploying to Cloudflare Pages](https://zine-ssg.io/docs/deploying/cloudflare-pages/)
+
+你可以参考 zine-ssg 或本站（ZigCC）仓库中的 GitHub Actions 配置来设置自己的自动化部署流程。
+
+# [四、总结与经验分享]($section.id("总结与经验分享"))
+
+最后，分享几点额外的经验：
+
+1.  SuperHTML (`.shtml`) 对 HTML 语法有严格的要求，它不仅仅是 HTML 的超集。某些写法可能与个人习惯冲突，需要适应其规范。
+2.  Scripty API 采用链式调用语法，非常灵活。
+
+迁移过程中遇到问题时，不要慌张。首先仔细查看终端的报错信息，然后查阅官方文档，最后可以多翻阅 zine-ssg 和 ziglang.org 等同样使用 Zine 构建的网站源码，它们是最好的学习范例。

From 22d65ee2cb1342f6cc95466ae7c8831615e2ade6 Mon Sep 17 00:00:00 2001
From: jiacai2050 <dev@liujiacai.net>
Date: Sun, 20 Jul 2025 21:55:53 +0800
Subject: [PATCH 3/3] more fix

---
 content/post/2025-07-19-zine-migration.smd | 54 ++++++++++++----------
 1 file changed, 29 insertions(+), 25 deletions(-)

diff --git a/content/post/2025-07-19-zine-migration.smd b/content/post/2025-07-19-zine-migration.smd
index 600c0a4..6f44305 100644
--- a/content/post/2025-07-19-zine-migration.smd
+++ b/content/post/2025-07-19-zine-migration.smd
@@ -7,7 +7,7 @@
 
 本文复盘了 ZigCC 社区网站从 Hugo 迁移至 Zine 的全过程，旨在分享其中的经验与思考，为有类似需求的朋友提供参考。
 
-# [为何选择 Zine？]($section.id("为何选择-Zine"))
+# [一、为何选择 Zine？]($section.id("为何选择-Zine"))
 
 我们最初使用 Hugo 及其 Docsy 主题搭建网站，但在使用过程中遇到了一些痛点，促使我们寻找新的解决方案。选择迁移至 Zine 主要基于以下几点考量：
 
@@ -22,9 +22,13 @@
 
 作为 Zig 社区的一份子，我们有责任参与到生态建设中。果不其然，这次迁移过程也让我们发现了 Zine 的一些待解决问题和潜在的改进点。
 
-# [Zine 简介]($section.id("Zine简介"))
+# [二、Zine 核心概念解读]($section.id("Zine核心概念解读"))
 
-Zine 是一个现代、高效的静态网站生成器。理解其核心组织结构是上手的第一步。一个最简化的 Zine 项目（通过 `zine init` 创建并删减后）目录结构如下：
+Zine 是一个现代、高效的静态网站生成器。要理解它，首先要掌握其核心设计理念和文件结构。
+
+## [项目结构与配置]($section.id("项目结构与配置"))
+
+一个基础的 Zine 项目结构与 Hugo 等主流生成器类似，主要包含内容、布局和静态资源目录：
 
 ```sh
 .
@@ -40,7 +44,7 @@ Zine 是一个现代、高效的静态网站生成器。理解其核心组织结
 └── zine.ziggy   # Zine 项目的全局配置文件
 ```
 
-上面的目录结构和 Hugo 类似， `zine.ziggy` 是网站的配置文件，ZigCC 的配置如下：
+项目的核心是 `zine.ziggy` 配置文件，它定义了网站的元数据和目录路径。以 ZigCC 的配置为例：
 ```zig
 Site {
     .title = "Zig 语言中文社区",
@@ -52,47 +56,47 @@ Site {
 }
 ```
 
-在 HTML 渲染方面，Zine 与 Hugo 相差甚远，Zine 自创了两种新格式来进行数据的组织：
-- [SuperMD](https://zine-ssg.io/docs/supermd/) 格式 - 扩展了标准 Markdown，允许定义嵌入式资源和语义结构，解决了传统 Markdown 无法表达复杂内容而不使用内联 HTML 的局限性。
-- [SuperHTML](https://zine-ssg.io/docs/superhtml) 模板系统 - 扩展的 HTML 格式专注于正确的模板逻辑表达。设计确保“不可能生成语法错误的 HTML，大多数错误会在构建时被发现”。
+## [内容渲染：SuperMD、SuperHTML 与 Scripty]($section.id("内容渲染"))
+
+Zine 在内容渲染上采用了与 Hugo 截然不同的哲学。它没有直接使用标准的 Markdown 和 HTML，而是引入了三个核心概念：
+
+-   **[SuperMD](https://zine-ssg.io/docs/supermd/)**: 一种扩展版的 Markdown。它解决了原生 Markdown 难以表达复杂结构（需内联 HTML）的痛点，允许开发者嵌入资源和定义更丰富的语义结构。
+-   **[SuperHTML](https://zine-ssg.io/docs/superhtml)**: 一种专为模板设计的扩展版 HTML。其设计目标是“从根本上杜绝生成语法错误的 HTML”，将大量潜在的运行时错误提前到构建时发现。
+-   **[Scripty](https://zine-ssg.io/docs/scripty/)**: 驱动前两者的微型表达式语言。
 
-这两者本质上就是 markdown 与 html，Zine 做的增强是为它们实现了其自创的表达式语言 [scripty](https://zine-ssg.io/docs/scripty/)。因此下面重点介绍 Scripty 的用法。
+本质上，SuperMD 和 SuperHTML 就是内嵌了 Scripty 动态能力的 Markdown 和 HTML。Scripty 的语法简洁，专为字符串嵌入而设计，是实现 Zine 动态内容的关键。
 
-## [Scripty]($section.id('scripty'))
+### Scripty 快速入门
 
-Scripty 是一个非常小的语言， 专门用于嵌入到字符串中，为 SuperMD 和 SuperHTML 提供动态内容生成能力。 因此 Scripty 没有任何类型的语句或代码块，只能用于构建表达式。
-- 所有表达式都以 `$` 开头
-- 支持字段导航： `$foo.bar.baz`
-- 支持函数调用： `$foo.bar.qux('arg1', "arg2")`
-- 支持基本字面量：字符串、整数、浮点数、布尔值
+-   所有表达式都以 ` 符号开头。
+-   支持链式字段访问：`$foo.bar.baz`
+-   支持函数调用：`$foo.bar.qux('arg1', "arg2")`
+-   支持字符串、数字、布尔等基本字面量。
 
-这里举一示例来说明 Scripty 在 SuperMD 和 SuperHTML 中的写法：
+下面是一个简单的示例，展示 Scripty 如何在 SuperHTML 和 SuperMD 中工作：
 
+**SuperHTML 示例：**
 ```html
 <ctx about="$site.page('about')">
   <a href="$ctx.about.link()" text="$ctx.about.title"></a>
 </ctx>
 ```
 
+**SuperMD 示例：**
 ```markdown
 Check out our [about page]($link.page('about')).
 ```
 
-既然是表达式语言，scripty 在多层嵌套时才能体现其威力：
-
-```html
-<h1 class="$page.title.len().gt(25).then('long')">...</h1>
-```
-
-如果当前页面标题长度小于 25 时，就有输出：
+Scripty 作为表达式语言，其威力在条件和嵌套逻辑中得以体现：
 
 ```html
-<h1 class="long">...</h1>
+<h1 class="{$page.title.len().gt(25).then('long-title')}">...</h1>
 ```
+在上述代码中，如果页面标题长度大于25个字符，`<h1>` 标签就会被赋予 `long-title` 这个 class。
 
-关于 SuperMD 和 SuperHTML 的用法这里不再赘述，推荐大家去阅读 Zine 的官方文章。
+通过这三者的结合，Zine 在保证内容与布局分离的同时，提供了高度的灵活性和安全性。更详细的用法，推荐阅读 Zine 官方文档。
 
-# [迁移步骤详解]($section.id("迁移步骤详解"))
+# [三、迁移步骤详解]($section.id("迁移步骤详解"))
 
 整个迁移过程可以分为内容转换、布局设计、预览调试和最终部署几个关键步骤。