Website for Zig
How to run locally
- A build of kristoff-it/hugo
- A build of kristoff-it/zig-doctest
- Latest Zig (the website tracks master branch)
Hugo needs to be built with CSS support:
CGO_ENABLED=1 go build --tags extended
Finally, Hugo expects to find both
Running the development server
hugo serve. On first launch it will use doctest to run all code snippets present in the website. Any error at this stage will either be about missing doctest, Zig being outdated (thus erroneously failing correct tests), or a code snippet failing a test for legitimate reasons.
After Hugo is launched you can use it to preview in realtime changes to the content. Right now Hugo has a limitation where changing a code snippet will not cause a re-render unless the page that lists it changes too (or you restart Hugo).
Tests are cached so you should not worry about having to sit through the entire testing routine after restarting Hugo.
Writing a translation
Translations rely on three main Hugo-specific conventions:
- The presence of the corresponding language in
themes/ziglang-original/i18ndirectory, which contains translations for menu elements, the download page and a few other miscelanneous strings.
content/, the presence of markdown files for the specific language you're translating to.
Let's say that you're working on a Japanese translation.
The two-letter ISO code for Japanese is
Start by adding the new translation to
DefaultContentLanguage = "en" [languages] [languages.en] weight = 1 [languages.it] weight = 2 [languages.ja] weight = 2
content/_index.ja.md and apply a small change to be able to distinguish the two versions.
hugo serve (or reload it); at this point you can go in your browser to
localhost:PORT/ja/ to preview your translation.
Translate all files in
content/ that have a
.en.md extension, and translate
themes/ziglang-original/i18n/en.toml to translate some menu items, the downloads page, and a few other miscelanneous strings.
Finally, add your translation to
Crafting a translation is not a straight-forward proceess. You have to think about adaptation, spatial constraints (in the front page especially), and other Hugo-specific issues that might not be immediately obvious.
If you don't mind instant messaging, please consider joining one of the Zig Discord communities, where you will be able to communicate with other contributors and share some knowledge.
If you prefer asynchronous communication, feel free to open a draft PR, we will make sure to engage with you pronto.
Keep in mind that it's possible that the current setup doesn't allow you correctly implement a translation without making ulterior changes to Hugo's configuration or how the content is organized. Don't hesitate to reach out for help to avoid getting stuck in a problem that can't be solved without larger-scale changes.
How to update documentation
The docs here are actually generated using a tool written in zig. Here's where the source files are:
How to update release notes
Edit files in src/.
export ZIG_DOCGEN=/home/andy/dev/zig/zig-cache/docgen ./build
Both the source and the output are committed to this repo because docgen is
likely to change in the future. The
build script will only build the
release notes for the latest release.