Standardize section titles and improve content structure across multiple SMD files. Update headings to ensure consistent formatting and enhance navigation with appropriate links. Remove obsolete files and adjust layout templates for better organization and clarity.

Author: xihale

content/about.smd

@@ -6,7 +6,7 @@
 .draft = false,
 --- 
 
-## [About Zine]($section.id('About Zine'))
+# [About Zine]($section.id('About Zine'))
 Zine is an MIT-licensed project created by [Loris Cro](https://kristoff.it) and
 other contributors listed on the [official repository](https://github.com/kristoff-it/zine/contributors).
 
@@ -34,7 +34,7 @@ of authoring languages:
   ># [NOTE]($block)
   >The correct file extension for SuperMD pages is `.smd`.
 
-## [Zine is alpha software]($section.id('Zine is alpha software'))
+# [Zine is alpha software]($section.id('zine-is-alpha-software'))
 
 Zine is not yet complete. The main functionality is present and you will be able
 to build even moderately complex static websites without issue.

content/community.smd

@@ -8,7 +8,7 @@
 TODO: issue
 [让我们一起探索 Zig 的魅力，推动 Zig 在中文社区内的发展！]($text.attrs('center','large','bold'))
 
-## [网站更新日志]($section.id('网站更新日志'))
+# [网站更新日志]($section.id('website-update-log'))
 
 - **2025-06-30:** 切换到 [zine](https://zine-ssg.io/)
 - **2024-08-18:** 切换主题 [docsy](https://github.com/google/docsy)

content/contributing.smd

@@ -12,7 +12,7 @@ Zig 中文社区是一个开放的组织，我们致力于推广 Zig 在中文
 2. 改进 zigcc 组织下的开源项目，这是 [open issues](https://github.com/search?q=state%3Aopen+org%3Azigcc++NOT+%E6%97%A5%E6%8A%A5&type=issues&ref=advsearch)
 3. 参与不定期的线上会议 TODO
 
-## [供稿方式]($section.id('供稿方式'))
+# [供稿方式]($section.id('供稿方式'))
 
 1. Fork 仓库 https://github.com/zigcc/zigcc.github.io
 2. 在 `content/post` 内添加自己的文章（md 或 org 格式均可），文件命名为： `${YYYY}-${MM}-${DD}-${SLUG}.md`
@@ -26,13 +26,13 @@ date: '2023-09-05T16:13:13+0800'
 ---
 ```
 
-## [本地预览]($section.id('本地预览'))
+# [本地预览]($section.id('本地预览'))
 TODO
 ```bash
 zine
 ```
 
-## [发布平台]($section.id('发布平台'))
+# [发布平台]($section.id('publishing-platform'))
 
 - [ZigCC 网站](https://ziglang.cc)
 - [ZigCC 公众号](https://github.com/zigcc/.github/raw/main/zig_mp.png)

content/learn/10-coding-in-zig.smd content/learn/coding-in-zig.smdcontent/learn/10-coding-in-zig.smd renamed to content/learn/coding-in-zig.smd

@@ -1,6 +1,6 @@
 ---
 .title = "实战",
-.date = @date("2024-01-01T00:00:00"),
+.date = @date("2024-01-10T00:00:00"),
 .author = "Karl Seguin; ZigCC",
 .layout = "learn.shtml",
 .draft = false,
@@ -10,7 +10,7 @@
 
 在介绍了 Zig 语言的大部分内容之后，我们将对一些主题进行回顾，并展示几种使用 Zig 编程时一些实用的技巧。在此过程中，我们将介绍更多的标准库，并介绍一些稍复杂些的代码片段。
 
-## [悬空指针 Dangling Pointers]($section.id('dangling-pointers'))
+# [悬空指针 Dangling Pointers]($section.id('dangling-pointers'))
 
 我们首先来看看更多关于悬空指针的例子。这似乎是一个奇怪的问题，但如果你之前主要使用带垃圾回收的语言，这可能是你学习 Zig 最大的障碍。
 
@@ -105,7 +105,7 @@ const User = struct {
 
 如果把所有东西都放在一个函数中，再加上一个像 `User` 这样的小值，这仍然像是一个人为制造的问题。我们需要一个能让数据所有权成为当务之急的例子。
 
-## [所有权 Ownership]($section.id('ownership'))
+# [所有权 Ownership]($section.id('ownership'))
 
 我喜欢哈希表（HashMap），因为这是每个人都知道并且会经常使用的结构。它们有很多不同的用例，其中大部分你可能都用过。虽然哈希表可以用在一个短期查找的地方，但通常用于长期查找，因此插入其内的值需要同样长的生命周期。
 
@@ -218,7 +218,7 @@ defer {
 
 我保证，关于悬挂指针和内存管理的讨论已经结束了。我们所讨论的内容可能还不够清晰或过于抽象。当你有更实际的问题需要解决时，再重新讨论这个问题也不迟。不过，如果你打算编写任何稍具规模（non-trivial）的程序，这几乎肯定是你需要掌握的内容。当你觉得可以的时候，我建议你参考上面这个示例，并自己动手实践一下。引入一个 `UserLookup` 类型来封装我们必须做的所有内存管理。尝试使用 `*User` 代替 `User`，在堆上创建用户，然后像处理键那样释放它们。编写覆盖新结构的测试，使用 `std.testing.allocator` 确保不会泄漏任何内存。
 
-## [ArrayList]($section.id('arraylist'))
+# [ArrayList]($section.id('arraylist'))
 
 现在你可以忘掉我们的 `IntList` 和我们创建的通用替代方案了。Zig 标准库中有一个动态数组实现：`std.ArrayList(T)`。
 
@@ -313,9 +313,9 @@ pub fn main() !void {
 }
 ```
 
-## [Anytype]($section.id('anytype'))
+# [Anytype]($section.id('anytype'))
 
-在[语言概述的第一部分](03-language-overview-1)中，我们简要介绍了 `anytype`。这是一种非常有用的编译时 duck 类型。下面是一个简单的 logger：
+在[语言概述的第一部分](language-overview-1)中，我们简要介绍了 `anytype`。这是一种非常有用的编译时 duck 类型。下面是一个简单的 logger：
 
 ```zig
 pub const Logger = struct {
@@ -383,7 +383,7 @@ fn stringify(
 
 第一个参数 `value: anytype` 是显而易见的，它是要序列化的值，可以是任何类型（实际上，Zig 的 JSON 序列化器不能序列化某些类型，比如 HashMap）。我们可以猜测，`out_stream` 是写入 JSON 的地方，但至于它需要实现什么方法，你和我一样猜得到。唯一的办法就是阅读源代码，或者传递一个假值，然后使用编译器错误作为我们的文档。如果有更好的自动文档生成器，这一点可能会得到改善。不过，我希望 Zig 能提供接口，这已经不是第一次了。
 
-## [@TypeOf]($section.id('typeof'))
+# [@TypeOf]($section.id('typeof'))
 
 在前面的部分中，我们使用 `@TypeOf` 来帮助我们检查各种变量的类型。从我们的用法来看，你可能会认为它返回的是字符串类型的名称。然而，鉴于它是一个 PascalCase 风格函数，你应该更清楚：它返回的是一个 `type`。
 
@@ -412,7 +412,7 @@ pub const User = struct {
 
 更常见的是 `@TypeOf` 与 `@typeInfo` 配对，后者返回一个 `std.builtin.Type`。这是一个功能强大的带标签的联合（tagged union），可以完整描述一个类型。`std.json.stringify` 函数会递归地调用它，以确定如何将提供的 `value` 序列化。
 
-## [构建系统]($section.id('build-system'))
+# [构建系统]($section.id('build-system'))
 
 如果你通读了整本指南，等待着深入了解如何建立更复杂的项目，包括多个依赖关系和各种目标，那你就要失望了。Zig 拥有强大的构建系统，以至于越来越多的非 Zig 项目都在使用它，比如 libsodium。不幸的是，所有这些强大的功能都意味着，对于简单的需求来说，它并不是最容易使用或理解的。
 
@@ -497,7 +497,7 @@ test "dummy build test" {
 
 这是启动和运行构建系统所需的最低配置。但是请放心,如果你需要构建你的程序，Zig 内置的功能大概率能覆盖你的需求。最后，你可以（也应该）在你的项目根目录下使用 `zig init`，让 Zig 为你创建一个文档齐全的 `build.zig` 文件。
 
-## [第三方依赖]($section.id('third-party-deps'))
+# [第三方依赖]($section.id('third-party-dependencies'))
 
 Zig 的内置软件包管理器相对较新，因此存在一些缺陷。虽然还有改进的余地，但它目前还是可用的。我们需要了解两个部分：创建软件包和使用软件包。我们将对其进行全面介绍。
 

content/learn/11-conclusion.smd content/learn/conclusion.smdcontent/learn/11-conclusion.smd renamed to content/learn/conclusion.smd

@@ -1,6 +1,6 @@
 ---
 .title = "总结",
-.date = @date("2024-01-01T00:00:00"),
+.date = @date("2024-01-11T00:00:00"),
 .author = "Karl Seguin; ZigCC",
 .layout = "learn.shtml",
 .draft = false,

content/learn/09-generics.smd content/learn/generics.smdcontent/learn/09-generics.smd renamed to content/learn/generics.smd

@@ -1,6 +1,6 @@
 ---
 .title = "泛型",
-.date = @date("2024-01-01T00:00:00"),
+.date = @date("2024-01-09T00:00:00"),
 .author = "Karl Seguin; ZigCC",
 .layout = "learn.shtml",
 .draft = false,

content/learn/08-heap-memory.smd content/learn/heap-memory.smdcontent/learn/08-heap-memory.smd renamed to content/learn/heap-memory.smd

@@ -1,6 +1,6 @@
 ---
 .title = "堆内存",
-.date = @date("2024-01-01T00:00:00"),
+.date = @date("2024-01-08T00:00:00"),
 .author = "Karl Seguin; ZigCC",
 .layout = "learn.shtml",
 .draft = false,
@@ -14,7 +14,7 @@
 
 本部分分为两个主题。第一个主题是第三个内存区域--堆的总体概述。另一个主题是 Zig 直接而独特的堆内存管理方法。即使你熟悉堆内存，比如使用过 C 语言的 `malloc`，你也会希望阅读第一部分，因为它是 Zig 特有的。
 
-## [堆]($section.id('dui'))
+# [堆]($section.id('heap'))
 
 堆是我们可以使用的第三个也是最后一个内存区域。与全局数据和调用栈相比，堆有点像蛮荒之地：什么都可以使用。具体来说，在堆中，我们可以在运行时创建大小已知的内存，并完全控制其生命周期。
 
@@ -52,7 +52,7 @@ fn getRandomCount() !u8 {
 
 一般来说，每次 `alloc` 都会有相应的 `free`。`alloc`分配内存，`free`释放内存。不要让这段简单的代码限制了你的想象力。这种 `try alloc` + `defer free` 的模式很常见，这是有原因的：在我们分配内存的地方附近释放相对来说是万无一失的。但同样常见的是在一个地方分配，而在另一个地方释放。正如我们之前所说，堆没有内置的生命周期管理。你可以在 HTTP 处理程序中分配内存，然后在后台线程中释放，这是代码中两个完全独立的部分。
 
-## [defer 和 errdefer]($section.id('defer 和 errdefer'))
+# [defer 和 errdefer]($section.id('defer-and-errdefer'))
 
 说句题外话，上面的代码介绍了一个新的语言特性：`defer`，它在退出作用域时执行给定的代码。『作用域退出』包括到达作用域的结尾或从作用域返回。严格来说， `defer` 与分配器或内存管理并无严格关系；你可以用它来执行任何代码。但上述用法很常见。
 
@@ -100,7 +100,7 @@ pub const Game = struct {
 
 > `init` 和 `deinit` 的名字并不特殊。它们只是 Zig 标准库使用的，也是社区采纳的名称。在某些情况下，包括在标准库中，会使用 `open` 和 `close`，或其他更适当的名称。
 
-## [双重释放和内存泄漏]($section.id('双重释放和内存泄漏'))
+# [双重释放和内存泄漏]($section.id('double-free-and-memory-leak'))
 
 上面提到过，没有规则规定什么时候必须释放什么东西。但事实并非如此，还是有一些重要规则，只是它们不是强制的，需要你自己格外小心。
 
@@ -159,7 +159,7 @@ fn isSpecial(allocator: Allocator, name: [] const u8) !bool {
 
 至少在双重释放的情况下，我们的程序会遭遇严重崩溃。内存泄漏可能很隐蔽。不仅仅是根本原因难以确定。真正的小泄漏或不常执行的代码中的泄漏甚至很难被发现。这是一个很常见的问题，Zig 提供了帮助，我们将在讨论分配器时看到。
 
-## [创建与销毁]($section.id('创建与销毁'))
+# [创建与销毁]($section.id('create-and-destroy'))
 
 `std.mem.Allocator`的`alloc`方法会返回一个切片，其长度为传递的第二个参数。如果想要单个值，可以使用 `create` 和 `destroy` 而不是 `alloc` 和 `free`。
 
@@ -233,7 +233,7 @@ fn init(allocator: std.mem.Allocator, id: u64, power: i32) !*User{
 
 请记住，`create` 返回一个 `!*User`，所以我们的 `user` 是 `*User` 类型。
 
-## [分配器 Allocator]($section.id('分配器 Allocator'))
+# [分配器 Allocator]($section.id('allocator'))
 
 Zig 的核心原则之一是无隐藏内存分配。根据你的背景，这听起来可能并不特别。但这与 C 语言中使用标准库的 malloc 函数分配内存的做法形成了鲜明的对比。在 C 语言中，如果你想知道一个函数是否分配内存，你需要阅读源代码并查找对 malloc 的调用。
 
@@ -254,7 +254,7 @@ defer allocator.free(say);
 
 如果你正在构建一个库，那么最好接受一个 `std.mem.Allocator`，然后让库的用户决定使用哪种分配器实现。否则，你就需要选择正确的分配器，正如我们将看到的，这些分配器并不相互排斥。在你的程序中创建不同的分配器可能有很好的理由。
 
-## [通用分配器 GeneralPurposeAllocator]($section.id('通用分配器 GeneralPurposeAllocator'))
+# [通用分配器 GeneralPurposeAllocator]($section.id('general-purpose-allocator'))
 
 顾名思义，`std.heap.GeneralPurposeAllocator` 是一种通用的、线程安全的分配器，可以作为应用程序的主分配器。对于许多程序来说，这是唯一需要的分配器。程序启动时，会创建一个分配器并传递给需要它的函数。我的 HTTP 服务器库中的示例代码就是一个很好的例子：
 
@@ -299,7 +299,7 @@ var gpa = std.heap.GeneralPurposeAllocator(.{}){};
 
 类型是什么，字段在哪里？类型其实是 `std.heap.general_purpose_allocator.Config`，但它并没有直接暴露出来，这也是我们没有显式给出类型的原因之一。没有设置字段是因为 Config 结构定义了默认值，我们将使用默认值。这是配置、选项的中常见的模式。事实上，我们在下面几行向 `init` 传递 `.{.port = 5882}` 时又看到了这种情况。在本例中，除了端口这一个字段外，我们都使用了默认值。
 
-## [std.testing.allocator]($section.id('std.testing.allocator'))
+# [std.testing.allocator]($section.id('std-testing-allocator'))
 
 希望当我们谈到内存泄漏时，你已经足够烦恼，而当我提到 Zig 可以提供帮助时，你肯定渴望了解更多这方面内容。这种帮助来自 `std.testing.allocator`，它是一个 `std.mem.Allocator` 实现。目前，它基于通用分配器（GeneralPurposeAllocator）实现，并与 Zig 的测试运行器进行了集成，但这只是实现细节。重要的是，如果我们在测试中使用 `std.testing.allocator`，就能捕捉到大部分内存泄漏。
 
@@ -423,7 +423,7 @@ self.allocator.free(self.items);
 
 将`items`复制到我们的 `larger` 切片中后, 添加最后一行`free`可以解决泄漏的问题。如果运行 `zig test learning.zig`，便不会再有错误。
 
-## [ArenaAllocator]($section.id('ArenaAllocator'))
+# [ArenaAllocator]($section.id('arena-allocator'))
 
 通用分配器（GeneralPurposeAllocator）是一个合理的默认设置，因为它在所有可能的情况下都能很好地工作。但在程序中，你可能会遇到一些固定场景，使用更专业的分配器可能会更合适。其中一个例子就是需要在处理完成后丢弃的短期状态。解析器（Parser）通常就有这样的需求。一个 `parse` 函数的基本轮廓可能是这样的
 
@@ -508,7 +508,7 @@ defer list.deinit();
 
 最后举个简单的例子，我上面提到的 HTTP 服务器在响应中暴露了一个 `ArenaAllocator`。一旦发送了响应，它就会被清空。由于`ArenaAllocator`的生命周期可以预测（从请求开始到请求结束），因此它是一种高效的选择。就性能和易用性而言，它都是高效的。
 
-## [固定缓冲区分配器 FixedBufferAllocator]($section.id('固定缓冲区分配器 FixedBufferAllocator'))
+# [固定缓冲区分配器 FixedBufferAllocator]($section.id('fixed-buffer-allocator'))
 
 我们要讨论的最后一个分配器是 `std.heap.FixedBufferAllocator`，它可以从我们提供的缓冲区（即 `[]u8`）中分配内存。这种分配器有两大好处。首先，由于所有可能使用的内存都是预先创建的，因此速度很快。其次，它自然而然地限制了可分配内存的数量。这一硬性限制也可以看作是一个缺点。另一个缺点是，`free` 和 `destroy` 只对最后分配/创建的项目有效（想想堆栈）。调用释放非最后分配的内存是安全的，但不会有任何作用。
 

content/learn/index.smd

@@ -6,25 +6,25 @@
 .draft = false,
 ---
 
-## [《学习 Zig》 目录]($section.id('table-of-contents'))
-
-- [前言](./01-preface)
-- [安装 Zig](./02-installing-zig)
-- [语言概述 - 第一部分](./03-language-overview-1)
-- [语言概述 - 第二部分](./04-language-overview-2)
-- [编码风格](./05-style-guide)
-- [指针](./06-pointers)
-- [栈内存](./07-stack-memory)
-- [堆内存和分配器](./08-heap-memory)
-- [泛型](./09-generics)
-- [实战](./10-coding-in-zig)
-- [总结](./11-conclusion)
+# [《学习 Zig》 目录]($section.id('table-of-contents'))
+
+- [前言](./preface)
+- [安装 Zig](./installing-zig)
+- [语言概述 - 第一部分](./language-overview-1)
+- [语言概述 - 第二部分](./language-overview-2)
+- [编码风格](./style-guide)
+- [指针](./pointers)
+- [栈内存](./stack-memory)
+- [堆内存和分配器](./heap-memory)
+- [泛型](./generics)
+- [实战](./coding-in-zig)
+- [总结](./conclusion)
 
 [《学习 Zig》](https://www.openmymind.net/learning_zig/)系列教程最初由 [Karl Seguin](https://github.com/karlseguin) 编写，该教程行文流畅，讲述的脉络由浅入深，深入浅出，是入门 Zig 非常不错的选择。因此，[Zig 中文社区](https://ziglang.cc)将其翻译成中文，便于在中文用户内阅读与传播。
 
 初次接触 Zig 的用户可以按序号依次阅读，对于有经验的 Zig 开发者可按需阅读感兴趣的章节。
 
-## [关于原作者]($section.id('关于原作者'))
+# [关于原作者]($section.id('about-original-author'))
 
 [Karl Seguin](https://www.linkedin.com/in/karlseguin/) 在多个领域有着丰富经验，前微软 MVP，他撰写了大量文章，是多个微软公共新闻组的活跃成员。现居新加坡。他还是以下教程的作者：
 
@@ -34,13 +34,13 @@
 
 可以在 <http://openmymind.net> 找到他的博客，或者通过 [@karlseguin](http://twitter.com/karlseguin) 在 Twitter 上关注他。
 
-## [翻译原则]($section.id('翻译原则'))
+# [翻译原则]($section.id('translation-principles'))
 
 技术文档的翻译首要原则是准确，但在准确的前提下如何保证『信、达、雅』？这是个挑战，在翻译本教程时，在某些情况下会根据上下文进行意译，便于中文读者阅读。
 
 最后，感谢翻译者的无私贡献。❤️️
 
-## [离线阅读]($section.id('离线阅读'))
+# [离线阅读]($section.id('offline-reading'))
 
 在本仓库的 [release 页面](https://github.com/zigcc/zigcc.github.io/releases)会定期将本教程导出为 PDF 格式，读者可按需下载。
 
@@ -49,7 +49,7 @@
 <!-- 读者也可以使用右侧导航栏中的『[整节打印](_print)』将当前版本教程保存为 PDF 格式。 -->
 ```
 
-## [其他学习资料]($section.id('其他学习资料'))
+# [其他学习资料]($section.id('other-learning-resources'))
 
 由于 Zig 目前还处于快速迭代，因此最权威的资料无疑是官方的 [Zig Language Reference](https://ziglang.org/documentation/master/)，遇到语言的细节问题，基本都可以在这里找到答案。 其次是社区的一些高质量教程，例如：
 

content/learn/02-installing-zig.smd content/learn/installing-zig.smdcontent/learn/02-installing-zig.smd renamed to content/learn/installing-zig.smd

@@ -1,6 +1,6 @@
 ---
 .title = "安装 Zig",
-.date = @date("2024-01-01T00:00:00"),
+.date = @date("2024-01-02T00:00:00"),
 .author = "Karl Seguin; ZigCC",
 .layout = "learn.shtml",
 .draft = false,
@@ -25,7 +25,7 @@ EOF
 
 asdf plugin-add zig https://github.com/zigcc/asdf-zig.git
 
-## [安装最新版]($section.id('安装最新版'))
+# [安装最新版]($section.id('install-latest-version'))
 asdf install zig latest
 asdf global zig latest
 zig version