linuxcnc-doc-search

Adds in-browser search to the LinuxCNC HTML documentation, as a post-processing step that lives outside the LinuxCNC source tree.

The LinuxCNC build stays minimalist and pulls in nothing extra: it just leaves a generic extension point in the docs topbar. This project takes the docs that LinuxCNC CI already produces, builds a pagefind search index, plugs the search box into that extension point, and emits the result as a downloadable artifact. Nothing here runs during the LinuxCNC build.

How it works

1. Download the linuxcnc-doc artifact (the built html/ tree) from LinuxCNC CI.
2. scripts/inject.py adds, to every page that carries the topbar:
   • data-pagefind-ignore on the topbar so the nav/switcher/search box are not indexed as content,
   • the search box (into the in-tree slot data-lcnc-slot="topbar-end" if present, otherwise just before the language switcher),
   • a <link> to search.css. The page-relative path to the html root is computed per file, so links work under any deployment prefix.
3. pagefind builds one isolated index per language subtree (en/_pagefind, de/_pagefind, ...), so results stay in the page's own language.
4. The search-enabled html/ tree is uploaded as the linuxcnc-doc-search artifact.

Search is a progressive enhancement: with JavaScript disabled the docs are unchanged and fully usable.

Running it

In CI: .github/workflows/build.yml runs every 6 hours, on every push to main, and on demand. Scheduled runs first compare the sha256 digest of the newest linuxcnc-doc.tar.gz artifact against the one the last build consumed (stored as a tiny doc-search-state artifact) and skip when it is unchanged, so a busy master with unchanged docs causes no rebuild and nothing new for the webserver to republish.

The workflow needs a secret SOURCE_TOKEN to read LinuxCNC's Actions artifacts: either a fine-grained PAT scoped to LinuxCNC/linuxcnc with Actions: Read-only (what the org repo uses), or a classic PAT with the public_repo scope. The repo's default GITHUB_TOKEN cannot read another repository's artifacts.

Locally, against an extracted html/ tree:

./scripts/build.sh html      # fetches the pinned pagefind binary if needed

Then serve html/ over HTTP (search needs fetch, not file://):

python3 -m http.server -d html 8000

The in-tree contract

The only thing LinuxCNC needs to carry is the extension point: a generic, empty slot in the topbar that post-processors can fill. The injector also works without it (it falls back to inserting before the language switcher), so it runs against today's docs unchanged.

Pinning

The pagefind version is pinned in scripts/build.sh (PAGEFIND_VERSION).