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
Category Navigation	Documentation organized by topic: Getting Started, Architecture, Development, Types, API, Testing, Security, Vision
Dark Mode	Automatic dark/light theme via `prefers-color-scheme`
GitHub Releases	Static release downloads fetched at build time via Nix fixed-output derivation
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
OpenGraph & Twitter Cards	Social media preview cards with per-page titles, descriptions, and images
RSS Feed	Subscribe to documentation updates via `/feed.xml` with autodiscovery
Sitemap with XSLT	Human-readable sitemap at `/sitemap.xml` with browser-viewable styling
Canonical URLs	Every page has a canonical URL for proper SEO indexing
JSON-LD	TechArticle, BreadcrumbList, and SoftwareApplication schemas for rich search snippets
Edit on GitHub	Every documentation page links to its source for easy contributions
Quantum 404	Custom error page with Schrödinger's cat - state collapses on observation

Generated Structure

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

qntx-docs-site/ ├── 404.html # Quantum 404 page ├── build-info.json # Provenance metadata ├── downloads.html # Release downloads (GitHub API) ├── feed.xml # RSS feed ├── index.html # Main documentation index ├── infrastructure.html # Nix build documentation ├── qntx.jpg # Logo ├── sitegen.html # This page ├── sitemap.xml # XML sitemap ├── sitemap.xsl # Sitemap stylesheet ├── css/ │ ├── core.css │ ├── docs.css │ ├── prism.css │ └── utilities.css ├── js/ │ ├── prismAutoloader.js │ └── prismCore.js ├── adr/ │ ├── ADR-001-domain-plugin-architecture.html │ ├── ADR-002-plugin-configuration.html │ ├── ADR-003-plugin-communication.html │ ├── ADR-004-plugin-pulse-integration.html │ ├── ADR-005-wasm-integration.html │ ├── ADR-006-proto-as-source-of-truth.html │ ├── ADR-007-typescript-proto-interfaces-only.html │ ├── ADR-008-rust-proto-separation.html │ └── ADR-009-edge-based-composition-dag.html ├── analysis/ │ └── mobile-canvas-ux.html ├── api/ │ ├── README.html │ ├── configuration.html │ ├── grpc-plugin.html │ ├── health-status.html │ ├── other.html │ ├── plugins.html │ ├── prompt.html │ ├── prose-documents.html │ ├── pulse-executions.html │ ├── pulse-jobs.html │ ├── pulse-schedules.html │ └── websocket.html ├── architecture/ │ ├── bounded-storage.html │ ├── budget-tracking.html │ ├── client-state-storage.html │ ├── config-system.html │ ├── plugin-custom-ui.html │ ├── plugin-pulse-integration-phase1.html │ ├── plugin-pulse-integration.html │ ├── pulse-async-ix.html │ ├── pulse-resource-coordination.html │ └── two-phase-jobs.html ├── development/ │ ├── canvas-export.html │ ├── config-panel.html │ ├── domain-plugin-api-reference.html │ ├── external-plugin-guide.html │ ├── glyph-attestation-flow.html │ ├── grace.html │ ├── migrating-to-plugins.html │ ├── multi-glyph-meld.html │ ├── pulse-execution-history.html │ ├── pulse-survey-2026-02.html │ ├── python-plugin.html │ ├── reduce-plugin.html │ ├── task-logging.html │ ├── ts-plugin.html │ └── verbosity.html ├── getting-started/ │ └── local-inference.html ├── glyphs/ │ ├── doc.html │ ├── prompt.html │ ├── result.html │ ├── semantic.html │ └── subcanvas.html ├── glyphs/manifestations/ │ ├── canvas-placed.html │ └── window.html ├── plans/ │ ├── glyph-persistence-visual-sync.html │ └── phase-2-qntx-crate.html ├── prompts/ │ ├── README.html │ └── recipegen.html ├── research/ │ └── social-layer.html ├── security/ │ └── ssrf-protection.html ├── types/ │ ├── README.html │ ├── async.html │ ├── budget.html │ ├── git.html │ ├── github.html │ ├── graph.html │ ├── schedule.html │ ├── server.html │ ├── sym.html │ ├── syscap.html │ └── types.html └── vision/ ├── clusters.html ├── continuous-intelligence.html ├── fractal-workspace.html ├── glyph-melding.html ├── glyphs.html ├── identity.html ├── mobile.html ├── plugin-glyph-meldability.html ├── reticulum.html └── time-travel.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)

Documentation Categories

Directories organized by topic (8 categories defined):

Directory	Description
`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