nix.tools

The umbrella website for the nix-tools projects. A front page that gives every project a card and a section of its own, plus the roadmap graph that nix-roadmaps links to; built with Hugo and a theme that lives in this repo rather than being vendored.

Getting started

nix develop        # or `direnv allow`; installs the git hooks on entry
serve              # http://localhost:1313

Outside the dev shell:

nix run .#serve    # live preview
nix build          # ./result is the rendered site
nix flake check    # formatting + hooks + a full render

just --list shows the rest.

Layout

nix/                  dendritic flake-parts modules, one aspect per file
content/              the copy; projects are page bundles that render no page of their own
content/roadmap/      the one page that is not the front page, graph and all
themes/nix-tools/     the theme — committed here, not a submodule or a Hugo module
mockup/               the original design export, kept for reference; excluded from the build

Adding a project

Create content/projects/<name>/ with an index.md, an icon.svg, and the snippet the code panel shows. The project appears both as a card in the matrix and as a section of its own, ordered by weight:

+++
title = "example"
weight = 40
badge = "Category"
tagline = "One line for the card."
font = "monoton"                       # omit to use the default face
repo = "https://github.com/nix-tools/example"

[code]
file = "flake.nix"                     # shown in the panel's title bar
lang = "nix"                           # Chroma lexer, also the panel's tag
resource = "snippet.nix"
mode = "source"                        # or "terminal" for a transcript
+++

The paragraph shown in the project's own section.

Use the wordmark shortcode to set the project's own name in its own face inside that paragraph.

A project can also carry [[actions]] (label, url, variant, icon), rendered as buttons under that paragraph — that is how nix-roadmaps sends the reader to the roadmap page.

Terminal transcripts (mode = "terminal") are rendered with two things dimmed: a leading $, > or → prompt marker, and any trailing column separated from the rest of the line by two or more spaces.

The roadmap page

content/roadmap/index.md is the whole page: the intro is its body, and the graph is [[steps]] in its front matter, top to bottom. Each step is a trunk milestone with the supporting topics that hang off either side of it:

[[steps]]
title = "Reproducible builds"
left = [
  { text = "The Nix store and closures" },
]
right = [
  { text = "Sandboxing and purity" },
  { text = "Cross compilation", optional = true },
]

optional draws the dashed, dimmed node the key describes. Branch text is inline Markdown, so backticks set a name in the mono face. A side with no topics is simply omitted; the trunk stays in the middle column regardless. Below 900px the columns unfold under the step they belong to.

Design system

hugo.toml is the control surface. Nothing in the CSS hardcodes a color or a shadow.

Colors — every key under [params.colors] becomes a --<key> custom property. Override one key or all of them; anything omitted falls back to the theme's default.

Glow — [params.glow] level is one of off, small, medium, large. medium reproduces the mockup's own calibration; the others scale blur and opacity together. HUGO_GLOW=large hugo server (or just glow large) overrides it without editing the file, and a project can set glow in its own front matter to override the level for its section alone. glow-tint colors the glow.

Syntax — [params.syntax] scheme is one of mono (greyscale, the mockup's own), neon (cyan and pink) or phosphor (tiers of green). HUGO_SYNTAX=neon hugo server (or just syntax neon) tries one without editing the file. A scheme names nine roles, and [params.syntax.colors] repaints single ones the same way [params.colors] does. Chroma's Nix lexer sets the ceiling on what a scheme can say: it separates keywords, import, builtins, constants, strings, numbers, comments and punctuation, but lumps every other identifier together — so an attribute's definition and a reference to it cannot be told apart.

Fonts — each entry under [params.fonts] is a wordmark face: the family, the woff2 to load, and that face's own sizes and tracking. The sizes live with the face rather than with the project because they are optical compensation for the typeface — a wide outline face and a narrow bookhand cannot share a size and still look like the same weight on the page. Projects reference a face by key.

The components live in themes/nix-tools/layouts/_partials/components/; each one documents its own parameters at the top of the file. Nothing outside a component writes that component's CSS classes.

Fonts

All four faces are self-hosted, converted from nixpkgs#google-fonts:

nix build --no-link --print-out-paths nixpkgs#google-fonts
nix run nixpkgs#woff2 -- woff2_compress <ttf>

Space Grotesk is a variable font, so one file covers the 300–700 range the design uses.

All four are OFL-1.1, one license per family, since the copyright notices differ and Monoton and Smythe declare Reserved Font Names. They live in themes/nix-tools/static/fonts/OFL/ so the build serves them at /fonts/OFL/, next to the fonts they cover — the deployed site redistributes the fonts, so the license has to travel with them. See themes/nix-tools/assets/fonts/README.md.

License

The site and theme are MIT; see LICENSE. The bundled fonts are OFL-1.1 and keep their own licenses, as described above. The mockup/ directory is the original design-tool export, kept for reference and excluded from the build.