carbon6

The website

Status: built (2026-10-15); not yet published. The pages repository, its token and the DNS records (§4) are still to do.

carbon6.dev is a static site, generated by a Rust program with Leptos and served by GitHub Pages from a repository of its own.

1. Decisions

  • Rendered on the build machine. Every page is a Leptos view rendered to HTML (ssr). The site ships no wasm and no JavaScript, so pages load at once, work everywhere and need nothing but a static file host.

  • The code lives here, in site/, a Cargo workspace of its own. In the main workspace its Leptos ssr would unify with the web UI's csr; on its own it also keeps the generator's dependencies out of Cargo.lock.

  • Content comes from the repository, so the site can't drift from the code:

    • the design docs, from docs/*.md (the list, order and groups are in site/src/docs.rs);
    • the guide, from the README's sections from "Run" up to "Local development";
    • the changelog, from CHANGELOG.md;
    • the version on every page and in the install commands, from the workspace Cargo.toml.

    Links between those files become links between pages, links to other repository files go to GitHub, and headings get GitHub's ids, so os.md#3-realms works on both. A link within the site to a page, file or heading it doesn't have fails the build.

  • Published to a separate repository, carbon6-dev/carbon6.dev, which GitHub Pages serves from its main branch. The site repository holds only built files: one commit per publish, naming the carbon6 commit it was built from.

2. Layout

PathIs
site/src/main.rsthe build: arguments, rendering, the output directory, CNAME, sitemap.xml, robots.txt
site/src/pages.rsthe pages, as Leptos components, and the shell (header, footer, metadata) around them
site/src/docs.rswhich docs the site publishes, under which names and groups
site/src/markdown.rsmarkdown to HTML: heading ids, tables of contents, link rewriting
site/static/copied as they are: the stylesheet and the icons
site/publish.shpushes a built site to the pages repository

Pages: / (home), /install/, /guide/, /docs/ and /docs/<doc>/, /changelog/, and /404.html, which GitHub Pages serves for any missing page.

3. Commands

CommandDoes
make sitebuilds the site into dist/site
make site-servebuilds it and serves it on http://127.0.0.1:8000 (SITE_PORT)
make site-checkclippy (no warnings) and the generator's tests
make site-publishbuilds it and pushes it to the pages repository (SITE_REPOSITORY, SITE_BRANCH)

make site-publish pushes with your own SSH key, or with SITE_TOKEN over HTTPS when it is set. An unchanged site pushes nothing.

The Site workflow (.github/workflows/site.yml) runs make site-check and make site for pull requests that touch the site's sources, and also make site-publish for pushes to main, after each successful Release workflow, and by hand. The push of a release commit (Release x.y.z) only builds: the install page would link to packages the Release workflow hasn't uploaded yet. So a version reaches the site only once its packages are up, and a failed release never reaches it. Without the SITE_TOKEN secret it builds and warns instead of publishing.

4. Setting it up

Once, by hand:

  1. The pages repository. Create carbon6-dev/carbon6.dev, public and empty. Publish the first time with make site-publish, from your machine.
  2. GitHub Pages. In that repository: Settings → Pages → Source: Deploy from a branch, main, / (root). The custom domain comes from the published CNAME file (carbon6.dev); once DNS resolves, tick Enforce HTTPS.
  3. DNS for carbon6.dev, at its registrar:
    • A records for carbon6.dev: 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153;
    • AAAA records: 2606:50c0:8000::153, 2606:50c0:8001::153, 2606:50c0:8002::153, 2606:50c0:8003::153;
    • CNAME for www.carbon6.dev: carbon6-dev.github.io (GitHub redirects it to carbon6.dev).
  4. Verify the domain for the organization (carbon6-dev → Settings → Pages → Add a domain, a TXT record), so no other GitHub account can serve a page on it.
  5. The token. A fine-grained personal access token with Contents: read and write on carbon6-dev/carbon6.dev only, saved as the SITE_TOKEN Actions secret of carbon6-dev/carbon6. The same kind of token as TAP_TOKEN (docs/releases.md).

5. Not done

  • Search. The docs have no search box; it would take JavaScript (a prebuilt index, as Pagefind makes).
  • Docs for each release. The site shows main's docs, which can describe features newer than the latest release.

docs/site.md on GitHub