Skip to content

docs: move the manual to MkDocs Material (#501) - #505

Merged
q-soriarty merged 33 commits into
developfrom
feature/501-docs-mkdocs-material
Nov 16, 2026
Merged

q-soriarty merged 33 commits into
developfrom
feature/501-docs-mkdocs-material

Conversation

@q-soriarty

@q-soriarty q-soriarty commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Moves the manual from Jekyll to MkDocs Material with the Qubernetic docs theme. The theme is the private submodule docs/site/brand (qubernetic/brand), pinned to its develop merge commit 7f030a6. The installation guides move to the site as well, and docs.yml now builds the site with mkdocs build --strict.

Closes #501

Changes

  • docs/site/: the MkDocs project (mkdocs.yml, requirements.in, hashed requirements.txt, hooks/commands_nav.py) and the hand-written pages (home, getting started, install/linux|macos|windows|source).
  • internal/docs, script/gen-docs.go: the generator writes MkDocs pages for the 88 commands and commands-nav.json, which the hook splices into the navigation.
  • .github/workflows/docs.yml: runs on pushes to main and on manual dispatch. build generates the pages, fetches the theme with the read-only deploy key BRAND_DEPLOY_KEY in a checkout of its own, installs with pip3 install --require-hashes, and builds strict. Pages upload and deploy run from main only. A dispatch from another branch uploads the build as the artifact docs-site.
  • test/workflows/docs_test.go: six tests pin those rules (triggers, main-only deploy, the key in exactly one step, strict build, hashed requirements with mkdocs-material==9.7.6, the path filter).
  • justfile: docs-build and docs-serve build from the pinned requirements, so a local build uses the versions CI uses.
  • README.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, docs/project-layout.md, docs/install_*.md: describe the new site and link to it.

Packaging does not fetch the submodule

Checked file by file, because the submodule is private and a release must not need it:

  • release.yml, snap.yml, copr.yml, aur.yml, ci.yml: no checkout sets submodules:, and no step runs git submodule.
  • .goreleaser.yml: no before: hooks. It builds ./cmd/copia-cli, which imports nothing under docs/site. An uninitialised gitlink leaves git status --porcelain empty, so the dirty-tree check is not tripped.
  • snap/snapcraft.yaml: plugin: go with source: .; override-build runs only git describe and go build.
  • rpmbuild/copia-cli.spec: Source0/Source1 are the release tarballs, so no git is involved.
  • A grep -i submodule over .github/, .goreleaser.yml, snap/, rpmbuild/, justfile and script/ finds only the comment in docs.yml.
  • A scratch clone without --recurse-submodules had a clean git status and an empty docs/site/brand.

Rehearsal

gh workflow run docs.yml --ref feature/501-docs-mkdocs-material: https://github.com/qubernetic/copia-cli/actions/runs/43863565328

  • build succeeded, deploy was skipped, and the artifact docs-site was uploaded.
  • The artifact holds 155 files. The local strict build has the same 155, and every file is byte-identical.
  • The run fetched the theme with the deploy key and installed the hashed requirements on the runner.

Automated checks

  • go test ./... and golangci-lint run ./... were green at 8625926; the only commit since, b3ba857, moves the submodule pin
  • mkdocs build --strict passes locally at b3ba857
  • the docs.yml rehearsal above passes at b3ba857
  • documentation updated in this PR

Test plan

  • After the release merge publishes the site, the old addresses answer: /copia-cli/manual/, /copia-cli/manual/copia-cli_completion, /copia-cli/manual/copia-cli_pr_create.
  • The README's installation and manual links resolve on the published site.
  • The footer link https://docs.twincatmcp.qubernetic.com answers.
  • Quick start step 5 (copia-cli pr create --fill) reads correctly; it changed after the checkpoint review.

Notes for reviewer

  • docs.yml has two checkouts on purpose: the repository without credentials, then the theme with the key. test/workflows fails if they are merged.
  • BRAND_DEPLOY_KEY is a repository secret. build declares no environment, so an environment secret would be empty there.
  • Without access to the theme a local site build fails. The CLI, the tests and just docs do not need it.
  • Known and left as is: on the api command page the list of field rules runs together into one paragraph. The fix is in the command's Long text under pkg/cmd.
  • The commit messages of ac26b23 and b537820 are imprecise. The branch is pushed, so they stay as they are.

CommandsNav and WriteNav build the MkDocs nav for the Commands section
from the cobra tree and write it as docs/site/commands-nav.json.
GenMarkdownTree and the navigation share one visible() rule, so the
pages and the entries cannot drift. gen-docs takes the pages directory
and the navigation file, and .gitignore covers the new generated paths.

Refs #501
Pinned to the tip of feature/4b-copia-cli-docs (d79086b); the MkDocs
site uses its theme through custom_dir.

Refs #501
…theme

Add mkdocs.yml with the theme from the brand submodule, a hook that
puts the generated command navigation under Commands, hash-pinned
requirements, stub pages for the hand-written navigation (Task 6 fills
them) and the docs, docs-serve, docs-build and docs-clean recipes.

Refs #501
go test ./test/docs/ generates the manual and its navigation into a
temporary directory and checks that the generated pages link only to each
other, that the navigation lists each of them once, and that they carry no
Jekyll markup. It also checks that the hand-written site pages link only
to command pages that exist, that the copia-cli lines in their shell
blocks name real commands, and that every page in mkdocs.yml's nav exists.

Refs #501
The Linux, macOS, Windows and source guides move to docs/site/docs/install/
with every heading kept, so the anchors the README links to still exist.
GitHub note blocks become admonitions, and the Go version of the source
build now matches go.mod. The overview page lists every method per
platform. The old files point to the site, and docs/README.md says where
the user documentation lives.

Refs #501
The site's authentication page covers creating a token, auth login, the
keyring and its config-file fallback, COPIA_TOKEN with COPIA_HOST, several
accounts and auth switch, auth status, auth setup-git and the precedence
(#auth-precedence). docs/authentication.md links to it and keeps the
developer details; its Auth Precedence heading points to the user page.

Refs #501
cobra's Find stops at a command group such as issue and returns the
unknown word as an argument, so copia-cli issue lst passed the guard. A
line now fails when the command it resolves to does not run and words are
left over, which catches a subcommand that was renamed or removed.

Refs #501
config.DefaultPath uses $XDG_CONFIG_HOME/copia/config.yml when that is
set, and ~/.config/copia/config.yml otherwise, on macOS and Windows too;
both pages now say so. auth switch picks from the accounts that match its
flags, or all of them: one match is switched to, of two the one not in
use, and only when it cannot decide does it fail with the list.

Refs #501
The manual is now built with MkDocs Material and the Qubernetic docs
theme instead of Jekyll. The build job checks out this repository
without a key and without submodules, reads the pinned brand commit
from the gitlink, and fetches qubernetic/brand at that SHA into
docs/site/brand in a second checkout with BRAND_DEPLOY_KEY: with an
ssh-key, actions/checkout would fetch this repository with that key
too, and the brand deploy key is not valid for it.

MkDocs Material is installed from the hash-pinned
docs/site/requirements.txt and the site is built with --strict. Pushes
to main deploy as before; a manual dispatch from another branch uploads
the build as the artifact docs-site and does not deploy. The trigger
paths now cover the generator and the submodule pin.

Refs #501
Six tests keep docs.yml off pull requests, deploy it from main only,
keep the brand deploy key in the one checkout that fetches the theme,
require a strict build, keep MkDocs Material pinned by hash at the
theme's version and make the trigger paths cover the generator.

Refs #501
The README links the installation guides on the site and says how the
site is built and what a local build needs. CLAUDE.md and
CONTRIBUTING.md describe docs.yml and the site layout, the changelog
records the move, and docs/project-layout.md no longer names Jekyll.

Refs #501
The docs workflow shared one concurrency group, "pages", with
cancel-in-progress, so a rehearsal dispatched from a branch cancelled a
main run that was building or deploying, and the live site stayed on
the old version without a report. The group is now
pages-${{ github.ref }}: a newer run still cancels an older one on the
same ref, but two refs never share a group. A test keeps github.ref in
the group.

Refs #501
CLAUDE.md lists what test/workflows enforces in docs.yml instead of
claiming all of it, and both CLAUDE.md and CONTRIBUTING.md describe the
per-ref concurrency group. CONTRIBUTING.md no longer says the install
matches copr's: both are hash-pinned, but docs needs neither
--no-build-isolation nor apt's setuptools and wheel. The project layout
says which manual pages are generated.

Refs #501
Break the Example lines that ran past the 66-character column of the
generated manual at a flag with a backslash, and split long comment
lines in two. Behaviour, flags and help text are unchanged.

Refs #501
Shorten the pr create example on the home page and in the quick start:
the head is the current branch and the base defaults to main. Shorten
the setup-git comment in the authentication guide.

Refs #501
printFlags escaped the usage text and appended the default afterwards, so
a default such as <none> would vanish from the page as an HTML tag. The
usage and the default are now escaped together.

Refs #501
The link checks saw inline links only, so a reference definition such as
[x]: ../manual/copia-cli_gone.md passed go test and failed only the
strict site build. They now read reference definitions too.

escapeAngles knows only backtick fences and code spans within one line.
A new check classifies the lines of each generated page the way MkDocs
reads them and fails on "&lt;" in a fenced or indented code block or in
a code span, also one a line break splits. Definition continuation lines,
which printFlags indents by four spaces, are prose, not code.

Refs #501
pkg/cmdutil defines the text of shared flags shown on the command pages
(--json, --jq, --template), and a cobra or pflag bump in go.mod and go.sum
can change the pages too. Add the three to push.paths of docs.yml and to
TestDocsPathsCoverTheGenerator.

Refs #501
The secret checks counted the literal "secrets.", so secrets['X'] or
toJSON(secrets) in another step slipped by; they now match the secrets
context as a word. TestDocsBuildIsStrict was a substring match that
passed with "|| true" or continue-on-error; the build step must now run
the one mkdocs command and neither the step nor the build job may set
continue-on-error. The concurrency group must be exactly
pages-${{ github.ref }}, not any group that contains github.ref.

Refs #501
pr create defaults the head to the current branch only with --web or
--fill; with --title alone it sends an empty head. Home and the quick
start now show copia-cli pr create --fill and say what --fill takes from
the commits, and Home links to the releases page.

Refs #501
curl does not expand *, so the latest/download URLs of the .deb and .rpm
returned 404. The package names hold the version (.goreleaser.yml sets
no nfpm file name template, so goreleaser's default
copia-cli_<version>_linux_<arch> applies), and no stable latest/download
name exists. The page now sends the reader to the latest release and
shows the install command with a <version> placeholder.

Refs #501
just docs-build and docs-serve resolved mkdocs-material==9.7.6 and its
dependencies freely, while CI installs the hashed set of
docs/site/requirements.txt. Both recipes now run
uv run --with-requirements requirements.txt from docs/site, so a local
strict build uses the versions CI uses.

Refs #501
The docs/site/brand submodule pointed at cf6e122 on the brand
repository's feature branch. That branch is now merged, so the pin moves
to the merge commit 7f030a6 on develop, the commit the brand remote will
serve to CI. The theme files are unchanged between the two commits.

Refs #501
@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.73684% with 11 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
script/gen-docs.go 0.00% 10 Missing ⚠️
internal/docs/nav.go 95.83% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

# Conflicts:
#	CHANGELOG.md
#	CLAUDE.md
#	docs/site/_includes/sidebar.html
Fetch qubernetic/brand over HTTPS and set update = none, so
git clone --recursive and a bare git submodule update --init no longer
fail without access to the private theme. The site build fetches it
with git submodule update --init --checkout docs/site/brand.
The ubuntu-24.04 runner already has pip3, so the apt-get update only
made the deploy on main depend on the apt mirrors.
The extensionless Jekyll addresses redirect to the new pages, the .html
ones do not. Link the completion page with its trailing slash.
@q-soriarty
q-soriarty merged commit c249c8b into develop Nov 16, 2026
13 of 14 checks passed
@q-soriarty
q-soriarty deleted the feature/501-docs-mkdocs-material branch November 16, 2026 18:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant