Docbuilder

A Nix package providing a pandoc-based documentation builder that converts markdown files into a static HTML site with full-text search via Stork.

Designed to be used as a flake input in multiple repositories.

Usage

As a Nix package

1. Build the docbuilder package:

nix build .#docbuilder

2. Use the package to build documentation:

./result/bin/build-docs <docs-dir> [output-dir]

• <docs-dir> - Path to directory containing markdown files (required)
• [output-dir] - Path to output directory (default: www)

As a flake input

1. Add as a flake input in your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    docbuilder = {
      url = "git+ssh://git@git.simple.fast/simplefast/docbuilder.git?shallow=1";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, docbuilder, ... }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
    in
    {
      packages.${system}.site = pkgs.stdenv.mkDerivation {
        name = "my-site";
        src = self;
        nativeBuildInputs = [ docbuilder.packages.${system}.default ];
        buildPhase = ''
          build-docs docs $out
        '';
        installPhase = "true";
      };
    };
}

Markdown Format

Documents should be markdown files with YAML frontmatter:

---
title: My Document
state: published
author: Author Name
labels:
  - label1
  - label2
freshness: fresh
inspired-by:
  - 1
  - 2
---

# My Document

Content goes here...

Supported metadata fields

• title - Document title (required)
• state - Document state (e.g., published, draft, etc.)
• author - Author name(s)
• labels - List of labels
• freshness - Freshness status (fresh, stale, rotten)
• inspired-by - List of document numbers this document is inspired by

Output

The build produces:

• {number}.html - Individual document pages
• index.html - Index page listing all documents
• index.st - Stork search index
• Static assets (CSS, JS, fonts)

Requirements

• pandoc
• stork
• jq
• (Optional) oils-for-unix for osh shell

These are provided in the Nix devShell:

nix develop