Shared documentation-site machinery based on ndg
  • Nix 87%
  • CSS 5.8%
  • JavaScript 4%
  • HTML 3.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
cinereal 30128117d7
All checks were successful
checks-treefmt / treefmt (push) Successful in 8s
checks-smoke / smoke (push) Successful in 7m38s
checks-mermaid / mermaid (push) Successful in 7m38s
npins: update ndg for the content width and table breaks (#30)
The ndg pin moves to the branch `nix-docs-lib` of the fork (`a74934f1`), which adds kiaragrouwstra/ndg@3e05f00c (branch `content-width`) on top of `f5eca204`.

On wide screens, the content is wider: it follows the free space between the sidebar toggle and the page-toc, from 800px to 1100px. The side arrows stay clear of the content. A table is not wider than the content, and a table that does not fit scrolls. A script adds a `<wbr>` after each `.` and `/` in table code, so that long names such as `services.foo.settings.bar` can break and do not make their column wide.

Tests: `nix flake check` passes. The ndg JS tests pass. On the hosting provider guide of Fediversity, from 900px to 2560px with the sidebar open and collapsed, no table scrolls and the arrows stay clear of the sidebar toggle and the page-toc.

Assisted-by: Claude:claude-fable-5-2
Reviewed-on: #30
2026-11-11 16:51:02 +01:00
.forgejo/workflows docs: let mkSite render Mermaid diagrams (#18) 2026-10-04 11:20:40 +02:00
npins npins: update ndg for the content width and table breaks (#30) 2026-11-11 16:51:02 +01:00
specs mkSite: show sidebarOrder and specs/ as a tree that folds (#28) 2026-11-10 22:32:15 +01:00
templates docs: let mkSite link to the source repository (#17) 2026-10-02 22:02:02 +02:00
tests/sidebar-tree/specs mkSite: show sidebarOrder and specs/ as a tree that folds (#28) 2026-11-10 22:32:15 +01:00
.envrc Initial import: shared nix docs library (ndg site machinery + describeCheck) 2026-07-12 13:33:20 +02:00
.gitignore add Spec Kit, a constitution and the specifications of the current helpers (#8) 2026-09-22 23:21:55 +02:00
check-describe.nix Initial import: shared nix docs library (ndg site machinery + describeCheck) 2026-07-12 13:33:20 +02:00
default.nix npins: update ndg for links to the previous and next pages (#29) 2026-11-11 11:55:03 +01:00
docs-zoom-mermaid.js docs-zoom: open a large diagram on its center (#25) 2026-10-28 11:12:41 +01:00
docs-zoom.css docs-zoom: open a large diagram on its center (#25) 2026-10-28 11:12:41 +01:00
docs.nix npins: update ndg for links to the previous and next pages (#29) 2026-11-11 11:55:03 +01:00
flake.lock Initial import: shared nix docs library (ndg site machinery + describeCheck) 2026-07-12 13:33:20 +02:00
flake.nix flake: instantiate the entrypoint once per system (#3) 2026-08-12 23:47:27 +02:00
LICENSE Add LICENSE (EUPL-1.2) to match the fediversity monorepo 2026-07-13 10:07:32 +02:00
README.md mkSite: show sidebarOrder and specs/ as a tree that folds (#28) 2026-11-10 22:32:15 +01:00
shell.nix Initial import: shared nix docs library (ndg site machinery + describeCheck) 2026-07-12 13:33:20 +02:00
treefmt.nix Initial import: shared nix docs library (ndg site machinery + describeCheck) 2026-07-12 13:33:20 +02:00

nix-docs-lib

Shared ndg-based documentation machinery for rendering per-component option/prose sites, plus the describeCheck helper used to read each check's meta.description when building a flake-attributes page.

Extracted from the fediversity monorepo so its core/api/panel doc sites and the standalone nix-module-form widget can share one definition, each consuming it via an npins pin.

Usage

lib.docs is a function of { basePath ? null, repoPath ? "", ... } (pkgs, sources and lib default internally). Each consumer passes its own repo root (basePath) and Forgejo source URL (repoPath) so transformOptions rewrites option declarations into links on the consumer's own instance:

inherit
  ((import "${sources.nix-docs-lib}" { }).lib.docs {
    basePath = ./..;
    repoPath = "https://git.fediversity.eu/fediversity/fediversity/src/branch/main";
  })
  mkSite
  optionsCommonMark
  optionPage
  flakeAttributesPage
  ;

describeCheck lives in check-describe.nix (also re-exported from default.nix):

inherit ((import "${sources.nix-docs-lib}" { }).lib) describeCheck;

Specifications

Pass specs to mkSite to render a Spec Kit specs/ directory in the site:

mkSite {
  title = "Example";
  inputDir = ./docs;
  sidebarOrder = [ "index" ];
  specs = ./specs;
}

Each .md file of the tree becomes the page specs/<relative path>. ndg always shows a README.md first in the sidebar, thus specs/README.md becomes specs/overview.md, and the links to it go to the new name. The sidebar shows these pages after the sidebarOrder pages, as a tree. The overview is the root. Below it are the constitution and then the feature directories in path order. A directory shows as its spec.md, or else its index.md, with the other pages of the directory below that page. A directory that has neither gets a generated index.md that lists its pages.

specsTitle is a function from the name and the title of a specs/ page to its title in the sidebar. The default removes the prefix Feature Specification: of Spec Kit:

specsTitle = _page: title: lib.removePrefix "Feature Specification: " title;

To give the overview another place or title, name it in sidebarOrder:

sidebarOrder = [
  "index"
  {
    page = "specs/overview";
    title = "Specifications";
  }
  "changelog"
];

Sidebar tree

An entry of sidebarOrder is a page name, or an attribute set with the page name and its children:

docsLib.mkSite {
  title = "my-component";
  inputDir = ./md;
  sidebarOrder = [
    "index"
    {
      page = "guides/index";
      title = "Guides";
      children = [
        "guides/install"
        "guides/update"
      ];
    }
  ];
}

The sidebar shows the children below their page, to any depth. title is optional and replaces the title of the page in the sidebar. A page with children folds, and only the chain to the current page is open. Pass collapsible = false to show all pages at all times.

Sidebar groups

Pass groupByDir = true to mkSite to show the pages of each top-level directory of inputDir as one group in the sidebar:

mkSite {
  title = "Example";
  inputDir = ./docs;
  sidebarOrder = [
    "index"
    "guides/install"
    "guides/update"
  ];
  groupByDir = true;
}

The reader can close a group. The pages at the root come first, then the groups in the order of the directory names. The label of a group is the name of its directory with an upper-case first letter. sidebarOrder gives the order of the pages in each group. With specs, the specs/ pages are the group Specs, as a flat list. ndg does not accept children together with groupByDir.

Pass repoUrl to mkSite to show an icon link to the source repository in the header of each page:

mkSite {
  title = "Example";
  inputDir = ./docs;
  sidebarOrder = [ "index" ];
  repoUrl = "https://git.fediversity.eu/fediversity/nix-docs-lib";
}

The header stays in view when the page scrolls, thus the link does too. Without repoUrl, the header has no such link.

Click to enlarge an image

Every site mkSite builds carries docs-zoom.css. An image is scaled down to the width of the page, and a page makes it click-to-enlarge with:

<label class="zoom"><input class="zoom-toggle" type="checkbox" /><img
  src="assets/example.png" alt="..." /></label>

A click then lays the image over the page at the size of the window, and a click on the backdrop puts it back. For an image with a light and a dark version, put a picture in the label. The browser then shows the version that agrees with the theme of the page, also when the image is enlarged:

<label class="zoom"><input class="zoom-toggle" type="checkbox" /><picture><source
  srcset="assets/example-dark.png" media="(prefers-color-scheme: dark)" /><img
  src="assets/example-light.png" alt="..." /></picture></label>

The page header has a theme toggle. A click selects the light or the dark theme, and the browser keeps the selection. When the selected theme is the same as the color scheme of the browser, the page follows the color scheme of the browser again.

Pass stylesheets to mkSite for CSS of your own; ndg concatenates it into the site's assets/style.css.

Diagrams

With mermaid = true, mkSite draws each mermaid fenced code block as a Mermaid diagram:

```mermaid
flowchart LR
  request --> policy --> resource
```

The site publishes the Mermaid library in its assets/, so it needs no third-party host. It takes the library from the source of mdbook-mermaid in nixpkgs, so the library updates with the nixpkgs pin. A page loads the library only if it has a diagram. The diagram follows the light or dark theme of the page.

A code span in a quoted label, such as a["Run `nix build`"], shows as inline code in flowchart, class, state, requirement and kanban diagrams. A label that is fully in one pair of backticks is a Mermaid Markdown string, not a code span.

A diagram is scaled down to the width of the page, and is click-to-enlarge without markup of its own. A click lays the diagram over the page at its natural size. When the diagram is larger than the window, the backdrop opens on the center of the diagram, and scrolls to show the remainder. A click on the diagram or the backdrop puts it back.

Development

nix flake show
nix build .#checks.x86_64-linux.treefmt
nix build .#checks.x86_64-linux.smoke
nix build .#checks.x86_64-linux.mermaid
nix build .#checks.x86_64-linux.theme-toggle

Specifications

specs/ contains the specifications and the principles for all changes. specs/README.md tells how to use them.