peter/infix
1
0
Fork 0
mirror of https://github.com/kernelkit/infix.git synced 2026-07-22 01:13:00 +02:00
Code Issues Packages Projects Releases Wiki Activity

webui: bundle on-device User's Guide

Browse Source 
Build the mkdocs User's Guide into WebUI images and surface it in the UI.
post-build.sh runs `mkdocs build` from the top-level mkdocs.yml into
/var/www/guide when the webui package is selected and mkdocs is on the
build host; nginx serves it read-only at /guide/.  The build is
best-effort — a missing mkdocs warns and ships without the guide rather
than failing — and minimal images (no webui) skip it.

The WebUI gates a book icon in the topbar and a User Guide item in the
user menu on the docs being present on disk (os.Stat, fail-closed), both
opening /guide/ in a new tab.

CI: a local setup-mkdocs composite action installs mkdocs and the
plugins from mkdocs.yml; the build and release workflows run it before
the build so images produced in CI include the guide.  developers-guide
documents the new build dependency and restores the missing
mkdocs-glightbox plugin.

Fixes #633

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2026-06-15 19:45:25 +02:00
parent 3ccbdf2f0b
commit e412c28c37
10 changed files with 104 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/developers-guide.md
+13 -5
View File
@@ -122,13 +122,21 @@ recommend using `pipx` to install the necessary tooling:
```bash
$ sudo apt install pipx
$ pipx install mkdocs
$ pipx inject mkdocs mkdocs-material pymdown-extensions mkdocs-callouts mike mkdocs-to-pdf
$ pipx inject mkdocs mkdocs-material pymdown-extensions mkdocs-callouts mike mkdocs-to-pdf mkdocs-glightbox
```
The last two packages, `mike` and `mkdocs-to-pdf`, are used for online
versioning and PDF generation by GitHub Actions, but since they are in
the `mkdocs.yml` file, everyone who wants to preview the documentation
have to install all the tooling.
The `mike` and `mkdocs-to-pdf` packages are used for online versioning
and PDF generation by GitHub Actions, but since every plugin is listed
in `mkdocs.yml`, anyone who wants to preview the documentation has to
install all the tooling.
> [!IMPORTANT]
> MkDocs is also required to **build a WebUI image**. The build bundles
> the User's Guide into the image (served on-device at `/guide/`), so
> `make` runs `mkdocs build` from `post-build.sh` when the `webui`
> package is selected. If MkDocs is missing the build still succeeds,
> but the image ships without the on-device guide. Minimal images and
> any build without the `webui` package skip this step entirely.
Preview with: