Table of Contents

Docbuilder

Asciidoctor-based static site generator with stork search.

1. Overview

Docbuilder converts .adoc files into a static HTML site with:

Asciidoctor with diagram and HTML5s extensions
Stork search — client-side full-text search (WASM)
Niccup landing page — generated HTML index when no index.adoc exists
Graphviz — diagram rendering

2. Building

Docbuilder is not a standalone build. It is used as a library by other packages to build their documentation sites.

# Build docbuilder's own docs
nix build .#docbuilder-site

3. Usage as library

Pass docbuilder to another package and call mkSite:

{
  docbuilder,
  src,
}:

docbuilder.mkSite {
  docs-src = "${src}/docs";
}

3.1. Site configuration

Place a site.nix in the docs directory:

{
  site-title = "My Documentation";
  site-subtitle = "Project Name";
  search-placeholder = "Search docs…";
}

3.2. Landing page

If index.adoc exists in the docs source, asciidoctor converts it to index.html as the landing page. Otherwise, a niccup-generated landing page is used with the site title, subtitle, and search box.

4. Packages using docbuilder

Package Attribute Docs source

RFD .#rfd rfd-src/docs/

Nix Packages .#nixpkgs-docs docs/ (this site)

Docbuilder .#docbuilder-site docbuilder-src/docs/

5. Source

pkgs/docbuilder/default.nix — builds from the docbuilder-src git input. Provides mkSite and default (docbuilder’s own docs).