The anchor step hard-codes check-anchors site — no --exclude, no site
directory override — and the workflow exposes one input, runs-on.
halos-org/docs already runs mkdocs-print-site-plugin, whose single-page
export accounts for 690 broken fragments there while the content pages are
clean; the documented remedy is --exclude 'print_page/*'. A translated docs
repo that adds the same plugin gets a red job on every pull request and every
push, for something no author can fix in content.
The escape routes are: fork the workflow, remove the plugin, or stop requiring
the check. The third is cheapest, and because the anchor check and the
translation gate share one job, it disables the gate this workflow exists to
add.
Same shape for site_dir. The README lists "leaves site_dir at its default"
as an unvalidated requirement; a consumer that changes it gets check-anchors
exit 2 on every run.
Two candidate fixes, not exclusive:
- Add
anchor-exclude and site-dir inputs, defaulted to today's behaviour.
Additive, breaks nobody.
- Split the site build and anchor check into their own reusable workflow, so
disabling one does not disable the other — and so a monolingual docs repo can
call the anchor check without writing it by hand, which today it must.
Both were raised on #39,
by the adversarial and maintainability reviewers respectively. Deliberately not
done there: the first consumer needs neither, and inputs are additive later.
Worth settling before a second consumer is wired.
See also halos-org/docs-tools#9
for reading site_dir from mkdocs.yml, which would remove half of this.
The anchor step hard-codes
check-anchors site— no--exclude, no sitedirectory override — and the workflow exposes one input,
runs-on.halos-org/docsalready runsmkdocs-print-site-plugin, whose single-pageexport accounts for 690 broken fragments there while the content pages are
clean; the documented remedy is
--exclude 'print_page/*'. A translated docsrepo that adds the same plugin gets a red job on every pull request and every
push, for something no author can fix in content.
The escape routes are: fork the workflow, remove the plugin, or stop requiring
the check. The third is cheapest, and because the anchor check and the
translation gate share one job, it disables the gate this workflow exists to
add.
Same shape for
site_dir. The README lists "leavessite_dirat its default"as an unvalidated requirement; a consumer that changes it gets
check-anchorsexit 2 on every run.
Two candidate fixes, not exclusive:
anchor-excludeandsite-dirinputs, defaulted to today's behaviour.Additive, breaks nobody.
disabling one does not disable the other — and so a monolingual docs repo can
call the anchor check without writing it by hand, which today it must.
Both were raised on #39,
by the adversarial and maintainability reviewers respectively. Deliberately not
done there: the first consumer needs neither, and inputs are additive later.
Worth settling before a second consumer is wired.
See also halos-org/docs-tools#9
for reading
site_dirfrommkdocs.yml, which would remove half of this.