From 9223ec0779648aff7ee8f6316c2716089826c250 Mon Sep 17 00:00:00 2001 From: Matthew Knight Date: Sat, 11 Jul 2026 00:13:35 -0700 Subject: [PATCH] Update zine --- .github/workflows/ci.yml | 2 +- .github/workflows/publish-github-pages.yml | 2 +- website/.zine.ziggy-schema | 158 ++++++++++++++++++ website/build.zig | 22 ++- website/build.zig.zon | 5 +- website/content/.smd.ziggy-schema | 72 ++++++++ website/content/community.smd | 4 +- website/content/devlog.smd | 6 +- website/content/docs.smd | 4 +- website/content/docs/boilerplate.smd | 4 +- website/content/docs/contributing.smd | 4 +- website/content/docs/getting-started.smd | 4 +- .../content/docs/how-to-regz-standalone.smd | 4 +- website/content/docs/internals.smd | 4 +- website/content/docs/mmio.smd | 4 +- website/content/docs/one-import.smd | 4 +- website/content/index.smd | 4 +- .../content/tutorials/01-embedded-basics.md | 4 +- .../tutorials/02-embedded-programming.md | 4 +- website/zine.ziggy | 15 +- 20 files changed, 289 insertions(+), 41 deletions(-) create mode 100644 website/.zine.ziggy-schema create mode 100644 website/content/.smd.ziggy-schema diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ccddcfa85..437c76cca 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -218,7 +218,7 @@ jobs: - name: Setup Zig uses: mlugg/setup-zig@v2 with: - version: 0.15.2 + version: 0.17.0-dev.857+2b2b85c5f - name: Build Website run: zig build working-directory: website diff --git a/.github/workflows/publish-github-pages.yml b/.github/workflows/publish-github-pages.yml index 3f646d281..fb57045d2 100644 --- a/.github/workflows/publish-github-pages.yml +++ b/.github/workflows/publish-github-pages.yml @@ -17,7 +17,7 @@ jobs: - name: Setup Zig uses: mlugg/setup-zig@v2 with: - version: 0.15.2 + version: 0.17.0-dev.857+2b2b85c5f - name: Download and install GitHub CLI run: | diff --git a/website/.zine.ziggy-schema b/website/.zine.ziggy-schema new file mode 100644 index 000000000..0c33ab013 --- /dev/null +++ b/website/.zine.ziggy-schema @@ -0,0 +1,158 @@ +$ = Config + +/// This is the schema of a Zine website config file, usually named 'zine.ziggy'. +struct Config { + /// A semver string representing the version of Zine that your website + /// requires. Used by GitHub / Forgejo actions to select automatically + /// the right version of Zine to fetch, see the 'Deploying' section of + /// https://zine-ssg.io/docs/. + zine_version: bytes, + /// Should external links generated by SuperMD automatically add + /// `target="_blank"`? Defaults to `false`. + /// + /// Note: you can override this setting on each link by using explicit + /// syntax (e.g. `[my link]($link.url(https://example.com).new(true))`) + auto_target_blank: ?bool, + /// Your website definition + site: Site, + /// User-defined properties that you can reference from SuperHTML via + /// '$site.custom'. + custom: {:}any, +} + +union Site { + simple: Simple, + multilingual: Multilingual, + + struct Simple { + title: bytes, + /// URL where the website will be hosted. + /// It must not contain a subpath, see `url_path_prefix`. + host_url: bytes, + /// Set this value if your website is hosted under a subpath of `host_url`. + /// + /// `host_url` and `url_prefix_path` are split to allow the development + /// server to generate correct relative paths when serving the website + /// locally. + url_path_prefix: ?bytes, + + /// Directory containing your SuperHTML layouts. + layouts_dir_path: bytes, + /// Directory containing your SuperMD content. + content_dir_path: bytes, + /// Directory containing your site-wide assets. + assets_dir_path: bytes, + + /// Subpaths in `assets_dir_path` that will be installed unconditionally. + /// All other assets will be installed only if referenced by a content file + /// or a layout by calling `$site.asset('foo').link()`. + /// + /// Examples of incorrect usage of this field: + /// - site-wide CSS files (should be `link`ed by templates) + /// - RSS feeds (should be generated by defining `alternative` pages) + /// + /// Examples of correct usage of this field: + /// - `favicon.ico` and other similar assets auto-discovered by browsers + /// - Font files only referenced inside of CSS files. + static_assets: []bytes, + /// When enabled, Zine will automatically add 'width' and 'height' + /// attributes to elements for local assets. + /// Be aware that setting 'width' and 'heigth' of an image will in some + /// circumstances cause browsers to distort images. + /// + /// This problem can be solved by adding the following CSS code to your + /// site: + /// + /// img { height: auto; } + /// + image_size_attributes: ?bool, + } + + struct Multilingual { + /// URL where the website will be hosted. + /// It must not contain a subpath, see `Locale.output_prefix_override`. + host_url: bytes, + /// Directory that contains mappings from placeholders to translations, + /// expressed as Ziggy files. + /// + /// Each Ziggy file must be named after the locale it's meant to offer + /// translations for. + i18n_dir_path: bytes, + /// Directory containing your SuperHTML layouts. + layouts_dir_path: bytes, + /// Directory containing your site-wide assets. + assets_dir_path: bytes, + /// Location where site- and build- assets will be installed. By default + /// assets will be installed directly in the output location. + /// + /// In mulitilingual websites Zine will create a single copy of + /// site assets which will then be installed at this location. It + /// will be your duty to then copy this directory elsewhere if + /// needed in your deployment setup (e.g. when deploying different + /// localized variants to different hosts). + /// + /// NOTE: *page* assets will still be installed next to their + /// relative page. + assets_prefix_path: ?bytes, + /// Subpaths in `assets_dir_path` that will be installed unconditionally. + /// All other assets will be installed only if referenced by a content file + /// or a layout by using `$site.asset('foo').link()`. + /// + /// Examples of incorrect usage of this field: + /// - site-wide CSS files (should be `link`ed by templates) + /// - RSS feeds (should be generated by defining `alternative` pages) + /// + /// Examples of correct usage of this field: + /// - `favicon.ico` and other similar assets auto-discovered by browsers + /// - Font files only referenced inside of CSS files. + static_assets: []bytes, + /// A list of locales of this website. + /// + /// For each entry the following values must be unique: + /// - `code` + /// - `output_prefix_override` (if not null) + `host_url_override` + locales: []Locale, + /// When enabled, Zine will automatically add 'width' and 'height' + /// attributes to elements for local assets. + /// Be aware that setting 'width' and 'heigth' of an image will in some + /// circumstances cause browsers to distort images. + /// + /// This problem can be solved by adding the following CSS code to your + /// site: + /// + /// img { height: auto; } + /// + image_size_attributes: ?bool, + + struct Locale { + /// A language-NATION code, e.g. 'en-US', used to identify each + /// individual localized variant of the website. + /// + /// Must be unique. + code: bytes, + /// A name that identifies this locale, e.g. 'English' + name: bytes, + /// Content dir for this locale, + content_dir_path: bytes, + /// Site title for this locale. + site_title: bytes, + /// Set to a non-null value when deploying this locale from a dedicated + /// host (e.g. 'https://us.site.com', 'http://de.site.com'). + /// + /// It must not contain a path other than '/'. + host_url_override: ?bytes, + /// | output_ | host_ | resulting | resulting | + /// | prefix_ | url_ | url | path | + /// | override | override | prefix | prefix | + /// | -------- | ------------- | ---------------- | --------------- | + /// | null | null | site.com/en-US/ | zig-out/en-US/ | + /// | null | "us.site.com" | us.site.com/ | zig-out/en-US/ | + /// | "foo" | null | site.com/foo/ | zig-out/foo/ | + /// | "foo" | "us.site.com" | us.site.com/foo/ | zig-out/foo/ | + /// | "" | null | site.com/ | zig-out/ | + /// + /// The last case is how you create a default locale. + output_prefix_override: ?bytes, + } + } +} diff --git a/website/build.zig b/website/build.zig index 21697abf9..efddbfa52 100644 --- a/website/build.zig +++ b/website/build.zig @@ -2,9 +2,25 @@ const std = @import("std"); const zine = @import("zine"); pub fn build(b: *std.Build) !void { - b.getInstallStep().dependOn(&zine.website(b, .{}).step); + // Override the version Zine reports about itself so it matches + // `.zine_version` in zine.ziggy, bypassing the version check. + // Zine's build.zig exposes a `-Dversion` option for exactly this. + const zine_dep = b.dependencyFromBuildZig(zine, .{ + .optimize = .ReleaseFast, + .@"no-git-version" = true, + .version = "0.12.0", + }); + // Release build (replaces zine.website) + const run_release = b.addRunArtifact(zine_dep.artifact("zine")); + run_release.setCwd(b.path(".")); + run_release.addArg("release"); + run_release.addPrefixedFileArg("--output=", b.graph.path(.install_prefix, "")); + b.getInstallStep().dependOn(&run_release.step); + + // Dev server (replaces zine.serve) const serve = b.step("serve", "Start the Zine dev server"); - const run_zine = zine.serve(b, .{}); - serve.dependOn(&run_zine.step); + const run_serve = b.addRunArtifact(zine_dep.artifact("zine")); + run_serve.setCwd(b.path(".")); + serve.dependOn(&run_serve.step); } diff --git a/website/build.zig.zon b/website/build.zig.zon index 12a21d013..3da093d2a 100644 --- a/website/build.zig.zon +++ b/website/build.zig.zon @@ -2,6 +2,7 @@ .name = .mz_website, .fingerprint = 0xf41bcd0e071e6f03, .version = "0.2.0", + .minimum_zig_version = "0.17.0-dev.857+2b2b85c5f", .paths = .{ "README.md", "build.zig", @@ -13,8 +14,8 @@ }, .dependencies = .{ .zine = .{ - .url = "git+https://github.com/kristoff-it/zine#b96e930630f8237aa4927fe14b9cb227061155d3", - .hash = "zine-0.11.1-ou6nIBB5FgAaYePTyiT2__fkGVNfImMOnpc_xKNXsYpF", + .url = "git+https://github.com/kristoff-it/zine#7689a27d78d206ed9297987998d2472c42904d75", + .hash = "zine-0.12.1-ou6nIC85FwCLi6UIsJNHXrE05AMYNfYKJPkNc4Qlo79H", }, }, } diff --git a/website/content/.smd.ziggy-schema b/website/content/.smd.ziggy-schema new file mode 100644 index 000000000..99941ba45 --- /dev/null +++ b/website/content/.smd.ziggy-schema @@ -0,0 +1,72 @@ +$ = Page + +/// This is the schema of a SuperMD document frontmatter. +/// +/// As a reminder, optionals ('?'), slices ('[]'), and dictionaries ('{:}') +/// can all be omitted, see https://ziggy-lang.io for more info. +/// +/// Note that while some fields here are defined as optional, +/// in SuperHTML they will instead be non-optional with a default value. +/// For example '?bytes' fields will default to an empty string, while +/// slices and dictionaries will instead default to empty containers. +/// +/// Make sure to read the SuperHTML reference to know how to properly +/// access these fields (https://zine-ssg.io/docs/superhtml/scripty/). +struct Page { + /// The title of this page. + title: ?bytes, + /// A short description of the page. + description: ?bytes, + /// The publishing date of this page. + date: Date, + /// The author(s) of this page. + authors: []bytes, + /// A list of tags for this page. + tags: []bytes, + /// Path to a layout file inside of the configured layouts directory. + layout: bytes, + /// Alternative paths where this content will also be made available. + /// + /// Note that the copies will be 100% identical to the main version, + /// if you need minor (or major) changes to other variants of this page, + /// you will want to use `alternatives`. + aliases: []bytes, + /// Alternative versions of this page, created by rendering the content + /// using a different layout and placed at a different URL. + /// + /// Useful for creating RSS feeds, for example. + alternatives: []Alternative, + /// In multilingual sites can be set to match corresponding pages that + /// don't have identical URLs. See 'i18n' docs for more info. + translation_key: ?bytes, + /// Ignore other SuperMD files in this directory and any sub-directory. + /// Can only be meaningfully set to true for 'index.smd' pages. + skip_subdirs: ?bool, + /// When set to true this file will be ignored when bulding the website, + /// unless the '--drafts' option has been passed to Zine. + draft: ?bool, + /// User-defined properties that you can reference from SuperHTML via + /// '$page.custom' + custom: {:}any, + + union Date { + /// A RFC3339 date string, e.g. "1990/01/01" or "1990/01/01T00:00:00". + date: bytes, + /// An epoch UNIX timestamp (seconds), e.g. 631148400. + unix: int, + } + + struct Alternative { + /// A name that can be used to refer to this alternative version + /// of the page from SuperHTML. + name: bytes, + /// Path to a layout file inside of the configured layouts + /// directory. + layout: bytes, + /// Output path, relative to the current directory. Use an absolute + /// path to refer to the website's root directory. + output: bytes, + /// Useful when generating `` elements. + type: ?bytes, + } +} diff --git a/website/content/community.smd b/website/content/community.smd index dca9a7fca..75cd2d83d 100644 --- a/website/content/community.smd +++ b/website/content/community.smd @@ -1,7 +1,7 @@ --- .title = "Community", -.date = @date("2024-11-02T00:00:00"), -.author = "Matthew Knight", +.date = .date("2024-11-02T00:00:00"), +.authors = ["Matthew Knight"], .draft = false, .layout = "index.shtml", .description = "MicroZig: Community", diff --git a/website/content/devlog.smd b/website/content/devlog.smd index 3e30887f5..544e29708 100644 --- a/website/content/devlog.smd +++ b/website/content/devlog.smd @@ -1,9 +1,9 @@ --- .title = "Devlog", -.date = @date("2021-07-06T00:00:00"), -.author = "ZEG contributors", +.date = .date("2021-07-06T00:00:00"), +.authors = ["ZEG contributors"], .layout = "devlog.shtml", -.alternatives = [{ +.alternatives = [.{ .name = "rss", .layout = "devlog.xml", .output = "devlog/rss.xml", diff --git a/website/content/docs.smd b/website/content/docs.smd index 3f3e28a96..e2b2d4ca7 100644 --- a/website/content/docs.smd +++ b/website/content/docs.smd @@ -1,7 +1,7 @@ --- .title = "Documentation", -.date = @date("2024-11-02T00:00:00"), -.author = "Matthew Knight", +.date = .date("2024-11-02T00:00:00"), +.authors = ["Matthew Knight"], .draft = false, .layout = "index.shtml", .description = "MicroZig: Documentation", diff --git a/website/content/docs/boilerplate.smd b/website/content/docs/boilerplate.smd index 9f4ca087e..07dc7c925 100644 --- a/website/content/docs/boilerplate.smd +++ b/website/content/docs/boilerplate.smd @@ -1,7 +1,7 @@ --- .title = "Application Boilerplate", -.date = @date("2026-05-01T00:00:00"), -.author = "Matthew Knight", +.date = .date("2026-05-01T00:00:00"), +.authors = ["Matthew Knight"], .draft = false, .layout = "index.shtml", .description = "MicroZig: Application Boilerplate", diff --git a/website/content/docs/contributing.smd b/website/content/docs/contributing.smd index 458129620..ffecd071c 100644 --- a/website/content/docs/contributing.smd +++ b/website/content/docs/contributing.smd @@ -1,7 +1,7 @@ --- .title = "Contributing Guide", -.date = @date("2024-11-02T00:00:00"), -.author = "Matthew Knight", +.date = .date("2024-11-02T00:00:00"), +.authors = ["Matthew Knight"], .draft = false, .layout = "index.shtml", .description = "MicroZig: Contributing", diff --git a/website/content/docs/getting-started.smd b/website/content/docs/getting-started.smd index 0353101eb..91ade1b9c 100644 --- a/website/content/docs/getting-started.smd +++ b/website/content/docs/getting-started.smd @@ -1,7 +1,7 @@ --- .title = "Getting Started", -.date = @date("2024-11-02T00:00:00"), -.author = "Matthew Knight", +.date = .date("2024-11-02T00:00:00"), +.authors = ["Matthew Knight"], .draft = false, .layout = "index.shtml", .description = "MicroZig: Getting Started", diff --git a/website/content/docs/how-to-regz-standalone.smd b/website/content/docs/how-to-regz-standalone.smd index b9b573978..f6dcdfa07 100644 --- a/website/content/docs/how-to-regz-standalone.smd +++ b/website/content/docs/how-to-regz-standalone.smd @@ -1,7 +1,7 @@ --- .title = "How to Use Regz for Standalone Projects", -.date = @date("2024-11-02T00:00:00"), -.author = "Matthew Knight", +.date = .date("2024-11-02T00:00:00"), +.authors = ["Matthew Knight"], .draft = false, .layout = "index.shtml", .description = "MicroZig: How to Use Regz for Standalone Projects", diff --git a/website/content/docs/internals.smd b/website/content/docs/internals.smd index d739b9636..ecb8d5d48 100644 --- a/website/content/docs/internals.smd +++ b/website/content/docs/internals.smd @@ -1,7 +1,7 @@ --- .title = "Internals", -.date = @date("2020-07-06T00:00:00"), -.author = "Matthew Knight", +.date = .date("2020-07-06T00:00:00"), +.authors = ["Matthew Knight"], .draft = false, .layout = "index.shtml", .description = "MicroZig Internals", diff --git a/website/content/docs/mmio.smd b/website/content/docs/mmio.smd index de3433209..a2a871e07 100644 --- a/website/content/docs/mmio.smd +++ b/website/content/docs/mmio.smd @@ -1,7 +1,7 @@ --- .title = "The MMIO Interface", -.date = @date("2024-11-02T00:00:00"), -.author = "Matthew Knight", +.date = .date("2024-11-02T00:00:00"), +.authors = ["Matthew Knight"], .draft = true, .layout = "index.shtml", .description = "The MMIO Interface", diff --git a/website/content/docs/one-import.smd b/website/content/docs/one-import.smd index 373e315a4..d666186d9 100644 --- a/website/content/docs/one-import.smd +++ b/website/content/docs/one-import.smd @@ -1,7 +1,7 @@ --- .title = "One Import to Rule Them All", -.date = @date("2024-11-02T00:00:00"), -.author = "Matthew Knight", +.date = .date("2024-11-02T00:00:00"), +.authors = ["Matthew Knight"], .draft = true, .layout = "index.shtml", .description = "MicroZig: Contributing", diff --git a/website/content/index.smd b/website/content/index.smd index 3ea4eb4fd..264e201f6 100644 --- a/website/content/index.smd +++ b/website/content/index.smd @@ -1,7 +1,7 @@ --- .title = "Home", -.date = @date("2020-07-06T00:00:00"), -.author = "Matthew Knight", +.date = .date("2020-07-06T00:00:00"), +.authors = ["Matthew Knight"], .draft = false, .layout = "index.shtml", .description = "MicroZig Homepage", diff --git a/website/content/tutorials/01-embedded-basics.md b/website/content/tutorials/01-embedded-basics.md index e64a2415a..a760eaf09 100644 --- a/website/content/tutorials/01-embedded-basics.md +++ b/website/content/tutorials/01-embedded-basics.md @@ -1,7 +1,7 @@ --- .title = "Embedded Basics", -.date = @date("2020-07-06T00:00:00"), -.author = "Felix Queißner", +.date = .date("2020-07-06T00:00:00"), +.authors = "Felix Queißner", .draft = false, .layout = "tutorial.shtml", .tags = [] diff --git a/website/content/tutorials/02-embedded-programming.md b/website/content/tutorials/02-embedded-programming.md index b7d747e43..688bd8254 100644 --- a/website/content/tutorials/02-embedded-programming.md +++ b/website/content/tutorials/02-embedded-programming.md @@ -1,7 +1,7 @@ --- .title = "Embedded Basics", -.date = @date("2020-07-06T00:00:00"), -.author = "Felix Queißner", +.date = .date("2020-07-06T00:00:00"), +.authors = "Felix Queißner", .draft = false, .layout = "tutorial.shtml", .tags = [] diff --git a/website/zine.ziggy b/website/zine.ziggy index 7cd636f13..c48390f43 100644 --- a/website/zine.ziggy +++ b/website/zine.ziggy @@ -1,7 +1,8 @@ -Site { - .title = "MicroZig", - .host_url = "https://microzig.tech", - .content_dir_path = "content", - .layouts_dir_path = "layouts", - .assets_dir_path = "assets", -} +.zine_version = "0.12.0", +.site = .simple(.{ + .title = "MicroZig", + .host_url = "https://microzig.tech", + .content_dir_path = "content", + .layouts_dir_path = "layouts", + .assets_dir_path = "assets", +}),