- Nix 87%
- CSS 5.8%
- JavaScript 4%
- HTML 3.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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 |
||
| .forgejo/workflows | ||
| npins | ||
| specs | ||
| templates | ||
| tests/sidebar-tree/specs | ||
| .envrc | ||
| .gitignore | ||
| check-describe.nix | ||
| default.nix | ||
| docs-zoom-mermaid.js | ||
| docs-zoom.css | ||
| docs.nix | ||
| flake.lock | ||
| flake.nix | ||
| LICENSE | ||
| README.md | ||
| shell.nix | ||
| treefmt.nix | ||
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.
Link to the source repository
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.