feat(render): add automatic heading ID generation

Provide navigation anchors by generating slugs for headings and Table of
Contents links. This resolves broken links resulting from missing directives
while maintaining support for manual ID overrides.

Author: jiacai2050

.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-linux
+          - os: ubuntu-latest
+            target: aarch64-linux
+          - os: macos-latest
+            target: aarch64-macos
+          - os: macos-latest
+            target: x86_64-macos
+
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Zig
+        uses: mlugg/setup-zig@v2
+
+      - name: Build
+        run: zig build -Doptimize=ReleaseFast -Dtarget=${{ matrix.target }}
+
+      - name: Package
+        run: |
+          mkdir -p dist
+          cp zig-out/bin/zine dist/zine
+          cd dist
+          tar -czvf ../zine-${{ github.ref_name }}-${{ matrix.target }}.tar.gz zine
+
+      - name: Upload Release Assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: zine-${{ github.ref_name }}-${{ matrix.target }}.tar.gz
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GEMINI.md

@@ -0,0 +1,49 @@
+# Zine: Static Site Generator
+
+Zine is a fast, scalable, and flexible Static Site Generator (SSG) written in Zig. It is designed for performance and provides a modern development experience with live reloading and advanced templating.
+
+## Project Overview
+
+- **Language:** Zig (Minimum version 0.15.0)
+- **Markdown Engine:** [supermd](https://github.com/kristoff-it/supermd)
+- **HTML Engine:** [superhtml](https://github.com/kristoff-it/superhtml)
+- **Data Format:** [ziggy](https://github.com/kristoff-it/ziggy)
+- **Core Architecture:**
+  - `src/main.zig`: Entry point, dispatches CLI subcommands.
+  - `src/root.zig`: Core logic for configuration loading, content scanning, and site building.
+  - `src/worker.zig`: Handles concurrent tasks for scaling.
+  - `src/cli/`: Implementation of subcommands (`init`, `release`, `debug`, `serve`).
+  - `src/render/`: HTML rendering logic for Markdown content.
+  - `src/context/`: Data models for Site, Page, Assets, etc., available in templates.
+
+## Building and Running
+
+### Development Commands
+
+- **Build Zine:** `zig build`
+- **Check Build:** `zig build check` (faster than full build, only checks the executable)
+- **Run Tests:** `zig build test` (runs snapshot tests in `tests/`)
+- **Run on Test Site:** `zig build run` (runs `zine` against the `standalone-test` directory)
+
+### CLI Usage
+
+Once built, you can use the `zine` executable (found in `zig-out/bin/`):
+
+- **Initialize a new site:** `zine init` (optionally with `--multilingual`)
+- **Start dev server:** `zine` (default command, serves on `localhost:8000`)
+- **Build for release:** `zine release` (outputs to `public/` by default)
+- **Version info:** `zine version`
+
+## Development Conventions
+
+- **Snapshot Testing:** Zine relies heavily on snapshot tests located in `tests/`. These tests compare actual output against `snapshot.txt` files to prevent regressions.
+- **Strict Typing:** Uses Zig's type system extensively to ensure correctness, particularly with `ziggy` schemas for configuration and frontmatter.
+- **Performance:** Designed to be multi-threaded; `worker.zig` manages parallel processing of pages.
+- **Template System:** Uses `superhtml` for layouts. Templates have access to `$site`, `$page`, and custom properties defined in frontmatter.
+
+## Key Files
+
+- `zine.ziggy`: The main configuration file for a Zine project.
+- `frontmatter.ziggy-schema`: Defines the schema for page metadata.
+- `src/root.zig`: Contains the `Site` and `Config` structs which define the project structure.
+- `build.zig`: Defines the build process and test runners.

build.zig.zon

@@ -2,7 +2,7 @@
     .name = .zine,
     .version = "0.11.2",
     .fingerprint = 0xa466bcb520a7eea2,
-    .minimum_zig_version = "0.15.0",
+    .minimum_zig_version = "0.16.0",
     .dependencies = .{
         .lsp_kit = .{
             .url = "git+https://github.com/zigtools/lsp-kit#ec325a3c33d1da7708cf513355208f74d9560580",

src/context/Page.zig

@@ -1782,7 +1782,7 @@ pub const Builtins = struct {
             const w = &aw.writer;
 
             const ast = p._parse.ast;
-            render.htmlToc(ast, w) catch return error.OutOfMemory;
+            render.htmlToc(gpa, ast, w) catch return error.OutOfMemory;
 
             return String.init(aw.written());
         }

src/render/html.zig

@@ -17,6 +17,34 @@ const HtmlSafe = @import("superhtml").HtmlSafe;
 
 const log = std.log.scoped(.render);
 
+fn renderSlug(gpa: std.mem.Allocator, node: supermd.Node, w: *Writer) !void {
+    _ = gpa;
+    const text = try node.renderPlaintext();
+
+    var last_was_dash = false;
+    var first = true;
+    for (text) |byte| {
+        // Allow alphanumeric ASCII and all non-ASCII (UTF-8) characters
+        const is_alphanumeric = std.ascii.isAlphanumeric(byte);
+        const is_non_ascii = byte >= 128;
+
+        if (is_alphanumeric or is_non_ascii) {
+            if (last_was_dash and !first) try w.writeByte('-');
+            if (is_alphanumeric) {
+                try w.writeByte(std.ascii.toLower(byte));
+            } else {
+                // Pass UTF-8 bytes through as-is
+                try w.writeByte(byte);
+            }
+            last_was_dash = false;
+            first = false;
+        } else {
+            // ASCII symbols and whitespace become dashes
+            last_was_dash = true;
+        }
+    }
+}
+
 pub fn html(
     gpa: std.mem.Allocator,
     ctx: *const context.Template,
@@ -191,7 +219,7 @@ pub fn html(
                         else => {},
                         .heading => {
                             try w.print("<h{}", .{node.headingLevel()});
-                            try w.print(" id=\"{s}\"", .{d.id.?});
+                            if (d.id) |id| try w.print(" id=\"{s}\"", .{id});
                             if (d.attrs) |attrs| {
                                 try w.print(" class=\"", .{});
                                 for (attrs) |attr| try w.print("{s} ", .{attr});
@@ -207,7 +235,7 @@ pub fn html(
                             }
                             open_div = true;
                             try w.print("<div", .{});
-                            try w.print(" id=\"{s}\"", .{d.id.?});
+                            if (d.id) |id| try w.print(" id=\"{s}\"", .{id});
                             if (d.attrs) |attrs| {
                                 try w.print(" class=\"", .{});
                                 for (attrs) |attr| try w.print("{s} ", .{attr});
@@ -218,7 +246,10 @@ pub fn html(
                         },
                     };
 
-                    try w.print("<h{}>", .{node.headingLevel()});
+                    try w.print("<h{}", .{node.headingLevel()});
+                    try w.writeAll(" id=\"");
+                    try renderSlug(gpa, node, w);
+                    try w.writeAll("\">");
                 },
                 .exit => {
                     if (node.parent()) |p| if (p.getDirective()) |pd| switch (pd.kind) {
@@ -759,7 +790,7 @@ fn renderLink(
     }
 }
 
-pub fn htmlToc(ast: Ast, w: *Writer) !void {
+pub fn htmlToc(gpa: std.mem.Allocator, ast: Ast, w: *Writer) !void {
     try w.print("<ul>\n", .{});
     var lvl: i32 = 1;
     var first_item = true;
@@ -777,21 +808,21 @@ pub fn htmlToc(ast: Ast, w: *Writer) !void {
                 try w.print("<ul><li>\n", .{});
             }
 
-            try tocRenderHeading(n, w, true);
+            try tocRenderHeading(gpa, n, w, true);
         } else if (new_lvl < lvl) {
             try w.print("</li>", .{});
             while (new_lvl < lvl) : (lvl -= 1) {
                 try w.print("</ul></li>", .{});
             }
             try w.print("<li>", .{});
-            try tocRenderHeading(n, w, true);
+            try tocRenderHeading(gpa, n, w, true);
         } else {
             if (first_item) {
                 try w.print("<li>", .{});
-                try tocRenderHeading(n, w, true);
+                try tocRenderHeading(gpa, n, w, true);
             } else {
                 try w.print("</li><li>", .{});
-                try tocRenderHeading(n, w, true);
+                try tocRenderHeading(gpa, n, w, true);
             }
         }
     }
@@ -803,7 +834,7 @@ pub fn htmlToc(ast: Ast, w: *Writer) !void {
     try w.print("</ul>", .{});
 }
 
-fn tocRenderHeading(heading: supermd.Node, w: *Writer, link: bool) !void {
+fn tocRenderHeading(gpa: std.mem.Allocator, heading: supermd.Node, w: *Writer, link: bool) !void {
     var it = Iter.init(heading);
     while (it.next()) |ev| {
         const node = ev.node;
@@ -814,18 +845,22 @@ fn tocRenderHeading(heading: supermd.Node, w: *Writer, link: bool) !void {
             ),
             .HEADING => switch (ev.dir) {
                 .enter => {
-                    const dir = node.getDirective() orelse continue;
-                    if (dir.id) |id| {
-                        std.debug.assert(id.len > 0);
-                        std.debug.assert(std.mem.trim(u8, id, "\t\n\r ").len > 0);
-                        if (link) try w.print("<a href=\"#{s}\">", .{id});
+                    if (link) {
+                        try w.writeAll("<a href=\"#");
+                        if (node.getDirective()) |d| {
+                            if (d.id) |id| {
+                                try w.writeAll(id);
+                            } else {
+                                try renderSlug(gpa, node, w);
+                            }
+                        } else {
+                            try renderSlug(gpa, node, w);
+                        }
+                        try w.writeAll("\">");
                     }
                 },
                 .exit => {
-                    const dir = node.getDirective() orelse continue;
-                    if (dir.id != null) {
-                        if (link) try w.print("</a>", .{});
-                    }
+                    if (link) try w.print("</a>", .{});
                 },
             },
             .TEXT => switch (ev.dir) {
@@ -861,7 +896,7 @@ fn tocRenderHeading(heading: supermd.Node, w: *Writer, link: bool) !void {
     }
 }
 
-pub fn htmlTocDetails(ast: Ast, w: *Writer) !void {
+pub fn htmlTocDetails(gpa: std.mem.Allocator, ast: Ast, w: *Writer) !void {
     var lvl: i32 = 1;
     var first_item = true;
     var node: ?supermd.Node = ast.md.root.firstChild();
@@ -880,7 +915,7 @@ pub fn htmlTocDetails(ast: Ast, w: *Writer) !void {
             }
 
             // if (lvl == 1) try w.print("<summary>\n", .{});
-            try tocRenderHeading(n, w, true);
+            try tocRenderHeading(gpa, n, w, true);
             // if (lvl == 1) try w.print("</summary>\n", .{});
         } else if (new_lvl < lvl) {
             try w.print("</li>", .{});
@@ -889,30 +924,30 @@ pub fn htmlTocDetails(ast: Ast, w: *Writer) !void {
             }
             if (lvl == 1) {
                 try w.print("</details><details><summary>", .{});
-                try tocRenderHeading(n, w, false);
+                try tocRenderHeading(gpa, n, w, false);
                 try w.print("</summary>", .{});
             } else {
                 try w.print("<li>", .{});
-                try tocRenderHeading(n, w, true);
+                try tocRenderHeading(gpa, n, w, true);
             }
         } else {
             if (first_item) {
                 if (lvl == 1) {
                     try w.print("<details><summary>", .{});
-                    try tocRenderHeading(n, w, false);
+                    try tocRenderHeading(gpa, n, w, false);
                     try w.print("</summary>", .{});
                 } else {
                     try w.print("<li>", .{});
-                    try tocRenderHeading(n, w, true);
+                    try tocRenderHeading(gpa, n, w, true);
                 }
             } else {
                 if (lvl == 1) {
                     try w.print("</details><details><summary>", .{});
-                    try tocRenderHeading(n, w, false);
+                    try tocRenderHeading(gpa, n, w, false);
                     try w.print("</summary>", .{});
                 } else {
                     try w.print("</li><li>", .{});
-                    try tocRenderHeading(n, w, true);
+                    try tocRenderHeading(gpa, n, w, true);
                 }
             }
         }

tests/drafts/simple/snapshot/archive/2024/index.html

@@ -6,6 +6,6 @@
   </head>
   <body>
     <h1>2024</h1>
-    <div><h1>2024</h1><p>Lorem ipsum</p></div>
+    <div><h1 id="2024">2024</h1><p>Lorem ipsum</p></div>
   </body>
 </html>

tests/drafts/simple/snapshot/archive/2025/index.html

@@ -6,6 +6,6 @@
   </head>
   <body>
     <h1>2025</h1>
-    <div><h1>2025</h1><p>Lorem ipsum</p></div>
+    <div><h1 id="2025">2025</h1><p>Lorem ipsum</p></div>
   </body>
 </html>

tests/drafts/simple/snapshot/index.html

@@ -6,6 +6,6 @@
   </head>
   <body>
     <h1>Homepage</h1>
-    <div><p>Your <strong>SuperMD</strong> content goes here.</p><h1>H1</h1><p>Lorem Ipsum 1</p><h2>H2</h2><p>Lorem Ipsum 2</p><h4>H3</h4><p>Lorem Ipsum 3</p></div>
+    <div><p>Your <strong>SuperMD</strong> content goes here.</p><h1 id="h1">H1</h1><p>Lorem Ipsum 1</p><h2 id="h2">H2</h2><p>Lorem Ipsum 2</p><h4 id="h3">H3</h4><p>Lorem Ipsum 3</p></div>
   </body>
 </html>

tests/drafts/simple/snapshot/sections/index.html

@@ -15,15 +15,15 @@ <h2>-- TABLE OF CONTENTS --</h2>
     </div>
     <div>
       <h2>-- SECTION BEGIN --</h2>
-      <div><div id="h1"><h1><a class="" href="#h1">H1</a></h1><p>Lorem Ipsum 1</p></div></div>
+      <div><div id="h1"><h1 id="h1"><a class="" href="#h1">H1</a></h1><p>Lorem Ipsum 1</p></div></div>
       <h2>-- SECTION END --</h2>
 
       <h2>-- SECTION BEGIN --</h2>
-      <div><div id="h2"><h2><a class="" href="#h2">H2</a></h2><p>Lorem Ipsum 2</p></div></div>
+      <div><div id="h2"><h2 id="h2"><a class="" href="#h2">H2</a></h2><p>Lorem Ipsum 2</p></div></div>
       <h2>-- SECTION END --</h2>
 
       <h2>-- SECTION BEGIN --</h2>
-      <div><div id="h3"><h3><a class="" href="#h3">H3</a></h3><p>Lorem Ipsum 3</p><p>This is a footnote<sup class="footnote-ref"><a href="#fn-1" id="fn-1-ref-1">1</a></sup></p></div></div>
+      <div><div id="h3"><h3 id="h3"><a class="" href="#h3">H3</a></h3><p>Lorem Ipsum 3</p><p>This is a footnote<sup class="footnote-ref"><a href="#fn-1" id="fn-1-ref-1">1</a></sup></p></div></div>
       <h2>-- SECTION END --</h2>
     </div>
   </body>

tests/rendering/multi/snapshot/about/index.html

@@ -21,7 +21,7 @@ <h1 class="site-title">Test</h1>
     </nav>
 
   <h1>About</h1>
-  <div><h2>About Page (en-US)</h2></div>
+  <div><h2 id="about-page-en-us">About Page (en-US)</h2></div>
 
     <div style="font-size: 2em;">
       <a href="/about/">en-US</a>