Ferret Website

Built with Hugo

Prerequisites

• Go
• Hugo
• Node.js
• Mage for building the website.

Getting Started

Installing dependencies

go mod tidy && mage install

Dev server

mage serve

The standard development server does not generate the Pagefind search bundle.

Production build

Build the static site and its client-side search index:

mage build

The generated site, including Pagefind assets under public/pagefind/, is written to public/.

Search preview

Build the site and search index, then serve the generated static output with Pagefind's preview server:

mage serveSearch

Tool documentation

When adding or reorganizing first-party tool pages, follow the tool documentation conventions.

Generating the Standard Library reference

The website generates the Standard Library reference from the published Ferret Core API Reference selected by runtime.v2 in data/versions.yaml. The selected release must include its sibling API Catalog, whose ordered categories drive the reference navigation.

mage generateStdlib

mage generate runs the same target. Normal development and production builds generate the reference automatically; contributors do not download API files by hand. See Standard Library reference generation for the publication, validation, and generated-file contracts.

Published Ferret tool releases update data/versions.yaml through a website-owned pull-request workflow. See Release version updates for the dispatch contract, manual retry procedure, and GitHub App setup.

Deployment

GitHub Actions builds, tests, and deploys the site to GitHub Pages when changes are pushed to main. Pull requests targeting main run the same checks without deploying, and maintainers can also start the workflow manually from main in the Actions tab.

The Pages source must be set to GitHub Actions in the repository settings. The custom domain remains ferretlang.org; configure it and HTTPS in the Pages settings rather than relying on the generated CNAME file alone.