docs

The go-mlkit documentation site, published at https://go-mlkit.github.io/docs/.

A Hugo site with the tannevaled/hextra fork of the Hextra theme (pinned to v0.16.0), built the same way as the go-numerics documentation, with go-mlkit's branding. go-mlkit is planned, wave 3 (PLAN.md): no library is released, so the pages state the scope, the plan and the references of each planned library.

Versions

params.libraries in hugo.yaml names the release of each library the pages describe, or main while it has no tag. A version of the documentation is the newest minor version among the tagged ones, or main while none is tagged:

Source	Published under
branch main, with params.libraries in hugo.yaml	https://go-mlkit.github.io/docs/<MAJOR.MINOR>/, or /docs/main/
the newest version (else main)	also https://go-mlkit.github.io/docs/latest/

https://go-mlkit.github.io/docs/ redirects to latest/. Each push to main replaces the directory of the version it describes, and nothing else. No library is tagged yet, so the pages are published under main/ (also latest/).

Pages

Page	What
home	the scope, the plan and the status
mlkit	Machine learning: what is planned, the references, the oracles and the criteria

A library's page will become its own documentation, summarised, once the library exists. A comment at the top of each page names the source: here, the roadmap. Change the text in the roadmap first, then here.

Layout

Path	What
content/en/	the pages; _index.md is the home, one directory per library, weight orders the sidebar
i18n/en.yaml	the site's strings, beside the theme's
hugo.yaml	baseURL, the library versions described, the navbar (version › theme › search › GitHub), the brand mounts
layouts/_partials/custom/content-begin.html	the outdated-version banner (reads versions.json)
layouts/_partials/favicons.html	the brand's favicons
assets/css/custom.css	the brand gold as Hextra's primary colour, the table headers
themes/hextra	submodule: tannevaled/hextra, pinned to v0.16.0
branding	submodule: go-mlkit/brand (the mark, its PNGs and ICO)
scripts/publish-version.sh	puts one build into a gh-pages checkout and rewrites versions.json, latest and the root redirect

Working locally

git clone --recurse-submodules https://github.com/go-mlkit/docs.git
cd docs
mkdir -p data && go run github.com/tannevaled/hextra/cmd/pagehistory@v0.21.0 > data/pagehistory.json
hugo server --baseURL http://localhost:1313/docs/main/

then open http://localhost:1313/docs/main/. Hugo 0.146 or later; no Python, no Node.

Publication

.github/workflows/docs.yml:

Job	When	What
build	pull requests, main	builds with --baseURL …/docs/<version>/, checks internal links and anchors (lychee, offline), uploads the site
links	pull requests, main	fetches every external URL the pages name
deploy	main	scripts/publish-version.sh into gh-pages (started empty on the first deploy), then a commit and a push

GitHub Pages serves the gh-pages branch.

Licence

BSD-3-Clause.