Skip to content

Commit 36ecac8

Browse files
committed
Standardize section titles across multiple SMD files to improve content structure and readability. Update headings to include links for better navigation and consistency throughout the documentation.
1 parent 26ca0a8 commit 36ecac8

Some content is hidden

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

49 files changed

+235
-235
lines changed

content/about.smd

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
.draft = false,
77
---
88

9-
## About Zine
9+
## [About Zine]($section.id('About Zine'))
1010
Zine is an MIT-licensed project created by [Loris Cro](https://kristoff.it) and
1111
other contributors listed on the [official repository](https://github.com/kristoff-it/zine/contributors).
1212

@@ -34,7 +34,7 @@ of authoring languages:
3434
># [NOTE]($block)
3535
>The correct file extension for SuperMD pages is `.smd`.
3636

37-
## Zine is alpha software
37+
## [Zine is alpha software]($section.id('Zine is alpha software'))
3838

3939
Zine is not yet complete. The main functionality is present and you will be able
4040
to build even moderately complex static websites without issue.

content/community.smd

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
TODO: issue
99
[让我们一起探索 Zig 的魅力,推动 Zig 在中文社区内的发展!]($text.attrs('center','large','bold'))
1010

11-
## 网站更新日志
11+
## [网站更新日志]($section.id('网站更新日志'))
1212

1313
- **2025-06-30:** 切换到 [zine](https://zine-ssg.io/)
1414
- **2024-08-18:** 切换主题 [docsy](https://github.com/google/docsy)

content/contributing.smd

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Zig 中文社区是一个开放的组织,我们致力于推广 Zig 在中文
1212
2. 改进 zigcc 组织下的开源项目,这是 [open issues](https://github.com/search?q=state%3Aopen+org%3Azigcc++NOT+%E6%97%A5%E6%8A%A5&type=issues&ref=advsearch)
1313
3. 参与不定期的线上会议 TODO
1414

15-
## 供稿方式
15+
## [供稿方式]($section.id('供稿方式'))
1616

1717
1. Fork 仓库 https://github.com/zigcc/zigcc.github.io
1818
2. 在 `content/post` 内添加自己的文章(md 或 org 格式均可),文件命名为: `${YYYY}-${MM}-${DD}-${SLUG}.md`
@@ -26,13 +26,13 @@ date: '2023-09-05T16:13:13+0800'
2626
---
2727
```
2828

29-
## 本地预览
29+
## [本地预览]($section.id('本地预览'))
3030
TODO
3131
```bash
3232
zine
3333
```
3434

35-
## 发布平台
35+
## [发布平台]($section.id('发布平台'))
3636

3737
- [ZigCC 网站](https://ziglang.cc)
3838
- [ZigCC 公众号](https://github.com/zigcc/.github/raw/main/zig_mp.png)

content/learn/02-installing-zig.smd

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ EOF
2525

2626
asdf plugin-add zig https://github.com/zigcc/asdf-zig.git
2727

28-
## 安装最新版
28+
## [安装最新版]($section.id('安装最新版'))
2929
asdf install zig latest
3030
asdf global zig latest
3131
zig version

content/learn/07-stack-memory.smd

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818

1919
> 三块内存区域实际上没有真正的物理差别。操作系统和可执行文件创造了"内存区域"这个概念。
2020

21-
## 栈帧
21+
## [栈帧]($section.id('栈帧'))
2222

2323
迄今为止,我们所见的所有数据都是常量,存储在二进制的全局数据部分或作为局部变量。局部表示该变量只在其声明的范围内有效。在 Zig 中,范围从花括号开始到结束。大多数变量的范围限定在一个函数内,包括函数参数,或一个控制流块,比如 if。但是,正如所见,你可以创建任意块,从而创建任意范围。
2424

@@ -92,7 +92,7 @@ main: user -> ------------- (id: 1043368d0)
9292

9393
与全局数据一样,调用栈也由操作系统和可执行文件管理。程序启动时,以及此后启动的每个线程,都会创建一个调用栈(其大小通常可在操作系统中配置)。调用栈在程序的整个生命周期中都存在,如果是线程,则在线程的整个生命周期中都存在。程序或线程退出时,调用栈将被释放。我们的全局数据包含所有程序的全局数据,而调用栈只包含当前执行的函数层次的栈帧。这样做既能有效利用内存,又能简化堆栈帧的管理。
9494

95-
## 悬空指针
95+
## [悬空指针]($section.id('悬空指针'))
9696

9797
栈帧的简洁和高效令人惊叹。但它也很危险:当函数返回时,它的任何本地数据都将无法访问。这听起来似乎很合理,毕竟这是本地数据,但却会带来严重的问题。请看这段代码:
9898

content/learn/08-heap-memory.smd

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ fn getRandomCount() !u8 {
5252

5353
一般来说,每次 `alloc` 都会有相应的 `free`。`alloc`分配内存,`free`释放内存。不要让这段简单的代码限制了你的想象力。这种 `try alloc` + `defer free` 的模式很常见,这是有原因的:在我们分配内存的地方附近释放相对来说是万无一失的。但同样常见的是在一个地方分配,而在另一个地方释放。正如我们之前所说,堆没有内置的生命周期管理。你可以在 HTTP 处理程序中分配内存,然后在后台线程中释放,这是代码中两个完全独立的部分。
5454

55-
## defer 和 errdefer
55+
## [defer 和 errdefer]($section.id('defer 和 errdefer'))
5656

5757
说句题外话,上面的代码介绍了一个新的语言特性:`defer`,它在退出作用域时执行给定的代码。『作用域退出』包括到达作用域的结尾或从作用域返回。严格来说, `defer` 与分配器或内存管理并无严格关系;你可以用它来执行任何代码。但上述用法很常见。
5858

@@ -100,7 +100,7 @@ pub const Game = struct {
100100

101101
> `init` 和 `deinit` 的名字并不特殊。它们只是 Zig 标准库使用的,也是社区采纳的名称。在某些情况下,包括在标准库中,会使用 `open` 和 `close`,或其他更适当的名称。
102102

103-
## 双重释放和内存泄漏
103+
## [双重释放和内存泄漏]($section.id('双重释放和内存泄漏'))
104104

105105
上面提到过,没有规则规定什么时候必须释放什么东西。但事实并非如此,还是有一些重要规则,只是它们不是强制的,需要你自己格外小心。
106106

@@ -159,7 +159,7 @@ fn isSpecial(allocator: Allocator, name: [] const u8) !bool {
159159

160160
至少在双重释放的情况下,我们的程序会遭遇严重崩溃。内存泄漏可能很隐蔽。不仅仅是根本原因难以确定。真正的小泄漏或不常执行的代码中的泄漏甚至很难被发现。这是一个很常见的问题,Zig 提供了帮助,我们将在讨论分配器时看到。
161161

162-
## 创建与销毁
162+
## [创建与销毁]($section.id('创建与销毁'))
163163

164164
`std.mem.Allocator`的`alloc`方法会返回一个切片,其长度为传递的第二个参数。如果想要单个值,可以使用 `create` 和 `destroy` 而不是 `alloc` 和 `free`。
165165

@@ -233,7 +233,7 @@ fn init(allocator: std.mem.Allocator, id: u64, power: i32) !*User{
233233

234234
请记住,`create` 返回一个 `!*User`,所以我们的 `user` 是 `*User` 类型。
235235

236-
## 分配器 Allocator
236+
## [分配器 Allocator]($section.id('分配器 Allocator'))
237237

238238
Zig 的核心原则之一是无隐藏内存分配。根据你的背景,这听起来可能并不特别。但这与 C 语言中使用标准库的 malloc 函数分配内存的做法形成了鲜明的对比。在 C 语言中,如果你想知道一个函数是否分配内存,你需要阅读源代码并查找对 malloc 的调用。
239239

@@ -254,7 +254,7 @@ defer allocator.free(say);
254254

255255
如果你正在构建一个库,那么最好接受一个 `std.mem.Allocator`,然后让库的用户决定使用哪种分配器实现。否则,你就需要选择正确的分配器,正如我们将看到的,这些分配器并不相互排斥。在你的程序中创建不同的分配器可能有很好的理由。
256256

257-
## 通用分配器 GeneralPurposeAllocator
257+
## [通用分配器 GeneralPurposeAllocator]($section.id('通用分配器 GeneralPurposeAllocator'))
258258

259259
顾名思义,`std.heap.GeneralPurposeAllocator` 是一种通用的、线程安全的分配器,可以作为应用程序的主分配器。对于许多程序来说,这是唯一需要的分配器。程序启动时,会创建一个分配器并传递给需要它的函数。我的 HTTP 服务器库中的示例代码就是一个很好的例子:
260260

@@ -299,7 +299,7 @@ var gpa = std.heap.GeneralPurposeAllocator(.{}){};
299299

300300
类型是什么,字段在哪里?类型其实是 `std.heap.general_purpose_allocator.Config`,但它并没有直接暴露出来,这也是我们没有显式给出类型的原因之一。没有设置字段是因为 Config 结构定义了默认值,我们将使用默认值。这是配置、选项的中常见的模式。事实上,我们在下面几行向 `init` 传递 `.{.port = 5882}` 时又看到了这种情况。在本例中,除了端口这一个字段外,我们都使用了默认值。
301301

302-
## std.testing.allocator
302+
## [std.testing.allocator]($section.id('std.testing.allocator'))
303303

304304
希望当我们谈到内存泄漏时,你已经足够烦恼,而当我提到 Zig 可以提供帮助时,你肯定渴望了解更多这方面内容。这种帮助来自 `std.testing.allocator`,它是一个 `std.mem.Allocator` 实现。目前,它基于通用分配器(GeneralPurposeAllocator)实现,并与 Zig 的测试运行器进行了集成,但这只是实现细节。重要的是,如果我们在测试中使用 `std.testing.allocator`,就能捕捉到大部分内存泄漏。
305305

@@ -423,7 +423,7 @@ self.allocator.free(self.items);
423423

424424
将`items`复制到我们的 `larger` 切片中后, 添加最后一行`free`可以解决泄漏的问题。如果运行 `zig test learning.zig`,便不会再有错误。
425425

426-
## ArenaAllocator
426+
## [ArenaAllocator]($section.id('ArenaAllocator'))
427427

428428
通用分配器(GeneralPurposeAllocator)是一个合理的默认设置,因为它在所有可能的情况下都能很好地工作。但在程序中,你可能会遇到一些固定场景,使用更专业的分配器可能会更合适。其中一个例子就是需要在处理完成后丢弃的短期状态。解析器(Parser)通常就有这样的需求。一个 `parse` 函数的基本轮廓可能是这样的
429429

@@ -508,7 +508,7 @@ defer list.deinit();
508508

509509
最后举个简单的例子,我上面提到的 HTTP 服务器在响应中暴露了一个 `ArenaAllocator`。一旦发送了响应,它就会被清空。由于`ArenaAllocator`的生命周期可以预测(从请求开始到请求结束),因此它是一种高效的选择。就性能和易用性而言,它都是高效的。
510510

511-
## 固定缓冲区分配器 FixedBufferAllocator
511+
## [固定缓冲区分配器 FixedBufferAllocator]($section.id('固定缓冲区分配器 FixedBufferAllocator'))
512512

513513
我们要讨论的最后一个分配器是 `std.heap.FixedBufferAllocator`,它可以从我们提供的缓冲区(即 `[]u8`)中分配内存。这种分配器有两大好处。首先,由于所有可能使用的内存都是预先创建的,因此速度很快。其次,它自然而然地限制了可分配内存的数量。这一硬性限制也可以看作是一个缺点。另一个缺点是,`free` 和 `destroy` 只对最后分配/创建的项目有效(想想堆栈)。调用释放非最后分配的内存是安全的,但不会有任何作用。
514514

content/learn/index.smd

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424

2525
初次接触 Zig 的用户可以按序号依次阅读,对于有经验的 Zig 开发者可按需阅读感兴趣的章节。
2626

27-
## 关于原作者
27+
## [关于原作者]($section.id('关于原作者'))
2828

2929
[Karl Seguin](https://www.linkedin.com/in/karlseguin/) 在多个领域有着丰富经验,前微软 MVP,他撰写了大量文章,是多个微软公共新闻组的活跃成员。现居新加坡。他还是以下教程的作者:
3030

@@ -34,13 +34,13 @@
3434

3535
可以在 <http://openmymind.net> 找到他的博客,或者通过 [@karlseguin](http://twitter.com/karlseguin) 在 Twitter 上关注他。
3636

37-
## 翻译原则
37+
## [翻译原则]($section.id('翻译原则'))
3838

3939
技术文档的翻译首要原则是准确,但在准确的前提下如何保证『信、达、雅』?这是个挑战,在翻译本教程时,在某些情况下会根据上下文进行意译,便于中文读者阅读。
4040

4141
最后,感谢翻译者的无私贡献。❤️️
4242

43-
## 离线阅读
43+
## [离线阅读]($section.id('离线阅读'))
4444

4545
在本仓库的 [release 页面](https://github.com/zigcc/zigcc.github.io/releases)会定期将本教程导出为 PDF 格式,读者可按需下载。
4646

@@ -49,7 +49,7 @@
4949
<!-- 读者也可以使用右侧导航栏中的『[整节打印](_print)』将当前版本教程保存为 PDF 格式。 -->
5050
```
5151

52-
## 其他学习资料
52+
## [其他学习资料]($section.id('其他学习资料'))
5353

5454
由于 Zig 目前还处于快速迭代,因此最权威的资料无疑是官方的 [Zig Language Reference](https://ziglang.org/documentation/master/),遇到语言的细节问题,基本都可以在这里找到答案。 其次是社区的一些高质量教程,例如:
5555

content/monthly/202207.smd

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
.draft = false,
77
---
88

9-
## 观点/教程
9+
## [观点/教程]($section.id('观点/教程'))
1010

1111
- [Zig 初体验 - Keep
1212
Coding](https://liujiacai.net/blog/2022/07/16/zig-intro/)
@@ -28,7 +28,7 @@
2828
before starting with Zig? :
2929
Zig](https://www.reddit.com/r/Zig/comments/w63x6r/is_it_necessary_to_know_c_or_another_systems/)
3030

31-
## 项目/工具
31+
## [项目/工具]($section.id('项目/工具'))
3232

3333
- [Release bun v0.1.5 ·
3434
oven-sh/bun](https://github.com/oven-sh/bun/releases/tag/bun-v0.1.5)

content/monthly/202208.smd

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
.draft = false,
77
---
88

9-
## 观点/教程
9+
## [观点/教程]($section.id('观点/教程'))
1010

1111
- [Growing a {{mustache}} with
1212
Zig](https://zig.news/batiati/growing-a-mustache-with-zig-di4)
@@ -29,7 +29,7 @@
2929
devlog](https://devlog.hexops.com/2022/packed-structs-in-zig/)。使用
3030
Zig 的 `packet struct` 实现 bit set 功能
3131

32-
## 项目/工具
32+
## [项目/工具]($section.id('项目/工具'))
3333

3434
- [Virtual tables by vrischmann · Pull Request \#100 ·
3535
vrischmann/zig-sqlite](https://github.com/vrischmann/zig-sqlite/pull/100)。zig-sqlite

content/monthly/202209.smd

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
.draft = false,
77
---
88

9-
## Zig VS Rust 火花
9+
## [Zig VS Rust 火花]($section.id('Zig VS Rust 火花'))
1010

1111
在 9/10 号左右,在 Twitter 上牵起了一小波关于 Zig VS Rust
1212
的小火花,以至于最后 Zig 创始人 Andrew Kelley
@@ -16,7 +16,7 @@ Let us exist。这里稍微整理下这件事情的过程: 本次事件主要
1616
- Rust 核心贡献者: Patrick Walton
1717
- Zig 社区 VP: Loris Cro
1818

19-
### 时间线
19+
### [时间线]($section.id('时间线'))
2020

2121
- 8/26 号,一篇关于 wasm 2 Game Jam
2222
的[分析报告](https://wasm4.org/blog/jam-2-results/)中,使用 Zig
@@ -57,7 +57,7 @@ Let us exist。这里稍微整理下这件事情的过程: 本次事件主要
5757
这里[提到的](https://github.com/tigerbeetledb/tigerbeetle/blob/main/docs/DESIGN.md)。而且即便内存安全,也可能发生
5858
OOM
5959

60-
### 总结
60+
### [总结]($section.id('总结'))
6161

6262
上面的链接比较多,这里稍微总结下这次争论的问题:
6363

@@ -69,7 +69,7 @@ Zig,笔者觉得大概率就是本次争论的观点,Rust
6969
过于复杂,导致程序员不仅仅要考虑业务行为,还需要按照 Rust
7070
的风格来编程,这加剧了程序出错的可能性。
7171

72-
## 观点/教程
72+
## [观点/教程]($section.id('观点/教程'))
7373

7474
- [How (memory) safe is
7575
zig?](https://www.scattered-thoughts.net/writing/how-safe-is-zig/)
@@ -102,7 +102,7 @@ Zig,笔者觉得大概率就是本次争论的观点,Rust
102102
- [Zig ⚡ Improving the User Experience for Unused
103103
Variables](https://vimeo.com/748218307)
104104

105-
## 项目/工具
105+
## [项目/工具]($section.id('项目/工具'))
106106

107107
- [Zig
108108
开发常用类库](https://github.com/zigcc/forum/discussions/28),如果读者的

0 commit comments

Comments
 (0)