Flake Module Reference

The Docyard flake-parts module adds perSystem.docyard options and emits apps.docs-serve, apps.docs-build, and apps.docs-preview.

Import

inputs.docyard = {
  url = "github:khwstolle/docyard";
  inputs.nixpkgs.follows = "nixpkgs";
};

# In mkFlake:
imports = [ inputs.docyard.flakeModules.default ];

Site modes

Docyard supports two ways of providing the documentation site:

• Managed (site.managed = true) — Docyard materializes the entire Nuxt app under .docyard/site in your repository (kept out of version control automatically). Your project provides only a directory of content files (site.content) plus the identity options below. Recommended.
• Explicit (site.managed = false, the default) — your project owns a full Nuxt app at site.directory that extends the Docyard theme. Use this when you need custom pages, components, or Nuxt configuration.

Core options

docyard.enable

Type: bool · Default: false

Enable the Docyard documentation tooling.

docyard.core

Type: package · Default: inputs'.docyard.packages.docyard-core

The Docyard Go CLI binary. Override when self-referencing the repo:

docyard.core = config.packages.docyard-core;

docyard.themePath

Type: str · Default: "${inputs.docyard}/packages/docyard-theme"

Filesystem path to the Nuxt theme layer. Override for self-referencing:

docyard.themePath = toString ./packages/docyard-theme;

docyard.sitePath

Type: str · Default: "${inputs.docyard}/templates/site"

Managed mode: path to the site app template that gets materialized.

Managed mode options

docyard.site.managed

Type: bool · Default: false

Materialize the site app under .docyard/site. Add .docyard/ to your .gitignore (Docyard also drops a .gitignore inside it as a safety net).

docyard.site.content

Type: str · Default: "docs"

Directory of Markdown / Quarto content, relative to the repo root. Point this at a dedicated directory — every .md / .qmd file below it becomes a page.

docyard.site.assets

Type: str · Default: ""

Optional directory overlaid onto the site's public/ directory: favicon, logos, images referenced from content, and references.bib for citations.

docyard.site.title / docyard.site.description

Type: str · Defaults: "Docs" / ""

Site title (header, SEO, llms.txt) and one-line description.

docyard.site.url / docyard.site.repo

Type: str · Default: ""

Canonical site URL (SEO and llms.txt) and repository URL (linked from the header when set).

docyard.site.output

Type: str · Default: "docs/dist"

Where docs-build copies the generated static site, relative to the repo root. Point your deploy step (GitHub Pages, Cloudflare Pages, …) at this directory.

docyard.site.theme

The theme ships one opinionated look (forest-green accent, Source Serif 4 / DM Sans, softened corners) plus three unused accent ramps (secondary/ tertiary/quaternary). Managed-mode projects have no Nuxt app of their own to override it in, so these options generate a small CSS override file instead — no package.json, no main.css fork required.

secondary/tertiary/quaternary are real Nuxt UI color slots (usable via color="secondary" etc. on any component in a consuming site), not just inert CSS — same as primary.

docyard.site.theme = {
  plate = 257; # or: preset = "blueViolet"; or: primaryHue = 264;
  radius = "0.75rem";
  fonts = {
    display = "Fraunces";
    sans = "Inter";
    link = "https://fonts.googleapis.com/css2?family=Fraunces&family=Inter&display=swap";
  };
};

docyard.site.theme.plate / preset

Both draw on the Sanzo Wada "A Dictionary of Color Combinations" dataset: 159 named colors grouped into 348 numbered plates of 2-4 colors each, baked into the repo as theme-colors.nix (no network access needed at build time).

• plate (e.g. plate = 257;) assigns that plate's colors, in the dataset's own order, to primaryHue/secondaryHue/tertiaryHue/ quaternaryHue. Plates with fewer than 4 colors are padded by repeating the last one — a 2-color plate [a b] becomes [a b b b], a 3-color plate [a b c] becomes [a b c c].
• preset (e.g. preset = "blueViolet";) picks one named color and applies its hue to all four slots — the one-color-everywhere case (a single-element list padded the same way: [a] becomes [a a a a]).
• Any explicit *Hue option always wins over both, per slot.

There's no practical way to list all 159 preset names or 348 plates in a table here — see theme-colors.nix in the repo root for the full catalog: themeColors names each color (with its hex value in a comment) and themePlates lists every plate's hues (with the color names in a comment).

The mono code font (JetBrains Mono) isn't overridable — it's self-hosted specifically so OG-image generation has real font data to render with, and overriding it would silently break that.

Explicit-mode projects own their Nuxt app already and can achieve the same effect directly: add a CSS file to your own css: [] array with a plain (unlayered) :root { --color-primary-hue: 264; --font-sans: "Inter", sans-serif; } block — main.css's own tokens live in @theme/@layer blocks, which lose to any unlayered declaration regardless of import order — and control font loading via your own <link> tags or fonts.families config.

Explicit mode options

docyard.site.directory

Type: str · Default: "docs/site"

Path to your Nuxt docs site, relative to the repo root.

docyard.site.outDir

Type: str · Default: "public/docyard"

Output directory for extracted API docs, relative to site.directory.

Shared options

docyard.site.apis

Type: list of submodule · Default: []

API extraction targets. Each item supports:

When any API is Python, griffe is added to the extraction environment automatically. src accepts either the package directory itself (src/mylib) or the directory containing it (src).

TypeScript extraction uses the TypeScript compiler API; the compiler is provided automatically (and is also resolved from the target project's own node_modules when present). JavaScript entry files with JSDoc comments work too.

Rust extraction runs cargo rustdoc against the crate, which needs a Rust toolchain (and any native build inputs your crate requires) on PATH — provide them via extraRuntimeInputs:

docyard.extraRuntimeInputs = [ pkgs.cargo pkgs.rustc pkgs.stdenv.cc ];

docyard.site.python.packages

Type: list of submodule · Default: []

Python distributions to build with uv build and host at a PEP 503 "simple" index alongside the docs. Each item supports:

Unlike site.apis (whose src is a package directory), this src is the project root — the directory uv build runs in. When any package is declared, uv is added to the build environment automatically.

docs-build, docs-preview, and docs-deploy build the wheels and sdists, compute their sha256, and write the index into public/<indexPath>/ so it ships with the generated site. Consumers install with:

pip install --index-url https://<site>/simple/ mylib        # docyard as the primary index
pip install --extra-index-url https://<site>/simple/ mylib  # docyard alongside PyPI

docyard.site.python.packages = [
  { name = "mylib"; src = "."; }
];

docyard.site.python.indexPath

Type: str · Default: "simple"

Base path under the site root that hosts the index (produces /simple/).

docyard.site.port

Type: int · Default: 3000

Default dev-server port (nix run .#docs-serve -- 8080 overrides it).

docyard.site.preHook

Type: lines · Default: ""

Shell commands run before extraction (CWD is the repo root) — e.g. generating benchmark JSON consumed by the site.

docyard.site.extraEnv

Type: attrsOf str · Default: {}

Extra environment variables exported for the dev/build commands.

docyard.site.search.backend

Type: "content" \| "pagefind" \| "algolia" · Default: "content"

Selects the search backend. "content" uses Nuxt Content's built-in SQLite search; "pagefind" builds a static index after the site is prerendered (the theme runs Pagefind automatically); "algolia" uses a hosted DocSearch index configured below.

docyard.site.search.algolia.{appId,apiKey,indexName}

Type: str · Default: ""

Algolia DocSearch credentials, used when search.backend = "algolia". The apiKey is the public, search-only key (safe to commit).

docyard.site.search = {
  backend = "algolia";
  algolia = {
    appId = "XXXXXXXXXX";
    apiKey = "0000000000search-only-key";
    indexName = "my-project";
  };
};

docyard.nodejs / docyard.bun / docyard.python

Type: package · Defaults: pkgs.nodejs_24 / pkgs.bun / pkgs.python3

Toolchain overrides. python is the interpreter used for Python API extraction.

docyard.extraRuntimeInputs

Type: list of package · Default: []

Extra packages on PATH for all docs apps (e.g. tools used by preHook).

Apps