DOCS

Getting Started

Set up Docyard in your project.

Getting Started

Docyard turns a directory of Markdown / Quarto files into a full documentation site, driven entirely from your Nix flake. In managed mode your project contributes only content and a few lines of configuration — Docyard owns the web app, its dependencies, and the build pipeline.

Prerequisites

A Nix flake using flake-parts
Python and/or Rust sources (optional — docs-only sites work too)

1. Add the input

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  flake-parts.url = "github:hercules-ci/flake-parts";
  docyard = {
    url = "github:khwstolle/docyard";
    inputs.nixpkgs.follows = "nixpkgs";
  };
};

2. Import the module

outputs = inputs@{ flake-parts, ... }:
  flake-parts.lib.mkFlake { inherit inputs; } {
    imports = [
      inputs.docyard.flakeModules.default
      # ...
    ];
    systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
    # ...
  };

3. Configure

In the perSystem block:

perSystem = { ... }: {
  docyard = {
    enable = true;
    site = {
      managed = true;
      title = "My Project";
      description = "One-line description of the project.";
      repo = "https://github.com/me/my-project";
      url = "https://me.github.io/my-project";
      content = "docs";

      # Optional: API reference extraction from source code.
      apis = [
        { language = "python"; name = "mylib"; src = "src/mylib"; }
        # { language = "rust"; name = "mycrate"; crate = "."; }
        # { language = "typescript"; name = "mylib"; src = "src/index.ts"; }
      ];
    };
  };
};

Add the generated directories to your .gitignore:

.docyard/
docs/dist/

4. Write content

Put Markdown (.md) or Quarto (.qmd) files in docs/:

docs/
├── index.md            # landing page (path /)
├── 1.getting-started.md
└── 2.guide/
    ├── index.md
    └── 1.usage.qmd

Numeric prefixes (1., 2., …) order the sidebar and are stripped from URLs. See Authoring for the supported syntax — citations, callouts, cross-references, math, and more.

5. Run

nix run .#docs-serve     # dev server with live reload (port 3000)
nix run .#docs-build     # static site → docs/dist
nix run .#docs-preview   # build, then serve the production output

The first run materializes the site app under .docyard/site and installs its dependencies; subsequent runs reuse them.

See Deployment for ready-to-use GitHub Actions workflows for GitHub Pages and Cloudflare Pages.

Templates

Start a new project from a template:

nix flake init -t github:khwstolle/docyard#python    # python | rust | node | combined

Custom sites (explicit mode)

If you need custom pages, components, or Nuxt configuration beyond what the options express, set site.managed = false (the default) and own a full Nuxt app at site.directory that extends the Docyard theme. The flake module reference describes both modes.

Documentation

Flake Module