QNTX Sitegen

This documentation site is generated by sitegen.nix, a pure Nix static site generator. No external tools or build steps required beyond Nix itself.

Features

Feature	Description
Pure Nix	Entire generator written in Nix - no shell scripts, no external build tools
Markdown to HTML	Converts `docs/*.md` to HTML using pulldown-cmark
SEG Symbol Navigation	Categories marked with semantic symbols: ⍟ Getting Started, ⌬ Architecture, ⨳ Development, ≡ Types, ⋈ API
Dark Mode	Automatic dark/light theme via `prefers-color-scheme`
GitHub Releases	Dynamic release downloads fetched client-side from GitHub API
Provenance	Every page shows commit, tag, date, CI user, and pipeline info
Self-documenting Infra	Nix packages, apps, and containers documented from flake metadata
Incremental Builds	Each markdown file is a separate derivation for faster rebuilds

Generated Structure

This structure is generated dynamically from the actual sitegen outputs (56 documentation files discovered):

qntx-docs-site/ ├── build-info.json # Provenance metadata ├── downloads.html # Release downloads (GitHub API) ├── index.html # Main documentation index ├── infrastructure.html # Nix build documentation ├── qntx.jpg # Logo ├── sitegen.html # This page ├── css/ │ ├── core.css │ ├── docs.css │ ├── prism.css │ └── utilities.css ├── js/ │ ├── prismAutoloader.js │ ├── prismCore.js │ └── releases.js ├── api/ │ ├── README.html │ ├── configuration.html │ ├── grpc-plugin.html │ ├── health-status.html │ ├── plugins.html │ ├── prose-documents.html │ ├── pulse-executions.html │ ├── pulse-jobs.html │ ├── pulse-schedules.html │ └── websocket.html ├── architecture/ │ ├── ADR-001-domain-plugin-architecture.html │ ├── ADR-002-plugin-configuration.html │ ├── ADR-003-plugin-communication.html │ ├── bounded-storage.html │ ├── budget-tracking.html │ ├── config-system.html │ ├── pulse-async-ix.html │ ├── pulse-resource-coordination.html │ └── two-phase-jobs.html ├── development/ │ ├── config-panel.html │ ├── design-philosophy.html │ ├── domain-plugin-api-reference.html │ ├── external-plugin-guide.html │ ├── grace.html │ ├── migrating-to-plugins.html │ ├── pulse-execution-history.html │ ├── task-logging.html │ └── verbosity.html ├── getting-started/ │ └── local-inference.html ├── plans/ │ └── phase-2-qntx-crate.html ├── security/ │ └── ssrf-protection.html ├── testing/ │ ├── pr-241-manual-test-checklist.html │ └── pulse-inline-scheduling-tests.html ├── types/ │ ├── README.html │ ├── async.html │ ├── budget.html │ ├── git.html │ ├── github.html │ ├── graph.html │ ├── schedule.html │ ├── server.html │ ├── sym.html │ └── types.html └── vision/ └── tile-based-semantic-ui.html

How It Works

1. Markdown Discovery

Uses lib.filesystem.listFilesRecursive to find all .md files in docs/:

markdownFiles = lib.filter (path: lib.hasSuffix ".md" (toString path)) (lib.filesystem.listFilesRecursive ./docs);

2. Per-file Derivations

Each markdown file becomes its own Nix derivation, enabling incremental builds:

mkHtmlDerivation = fileInfo: pkgs.runCommand "qntx-doc-${fileInfo.name}" { nativeBuildInputs = [ pkgs.pulldown-cmark ]; } '' pulldown-cmark input.md > $out/output.html '';

3. Compositional Assembly

All derivations combined with symlinkJoin:

pkgs.symlinkJoin { name = "qntx-docs-site"; paths = [ staticAssets ] ++ lib.attrValues outputs ++ htmlDerivations; }

Provenance Parameters

Sitegen accepts these parameters for build provenance:

Parameter	Type	Description
`gitRevision`	string	Full commit hash
`gitShortRev`	string	Short commit hash (displayed)
`gitTag`	string?	Release tag (e.g., "v1.0.0")
`buildDate`	string?	Build date (e.g., "2025-01-08")
`ciUser`	string?	CI actor (e.g., "github-actions")
`ciPipeline`	string?	Workflow name
`ciRunId`	string?	GitHub Actions run ID (links to run)

Infrastructure Metadata

Pass Nix infrastructure metadata to generate the infrastructure page:

Parameter	Type	Description
`nixPackages`	[{name, description}]	List of buildable packages
`nixApps`	[{name, description}]	List of runnable apps
`nixContainers`	[{name, description, image, architectures, ports}]	List of container images

Building the Site

# Build docs site nix build .#docs-site # Copy to web/site/ for serving nix run .#build-docs-site # Serve locally (example with Python) cd result && python -m http.server 8000

Adding Documentation

To add new documentation:

Create a markdown file in docs/ (e.g., docs/guides/my-guide.md)
The file will be automatically discovered and converted to HTML
Category is determined by the first directory (e.g., guides/)
Links between docs: use .md extension (auto-rewritten to .html)

SEG Category Mapping

Directories are mapped to SEG symbols for semantic navigation (8 categories defined):

Directory	Symbol	Meaning
`getting-started/`	⍟	Entry points
`architecture/`	⌬	System design
`development/`	⨳	Workflows
`types/`	≡	Type reference
`api/`	⋈	API reference
`security/`	+	Security
`testing/`	✦	Test guides
`vision/`	⟶	Future direction

Documentation Generator