Skip to content

docs: fix the strict-mode Pages build - #566

Merged
singaraiona merged 1 commit into
devfrom
fix/unpublish-engineering-docs
Sep 18, 2026
Merged

singaraiona merged 1 commit into
devfrom
fix/unpublish-engineering-docs

Conversation

@singaraiona

@singaraiona singaraiona commented Sep 17, 2026

Copy link
Copy Markdown
Collaborator

What & why

The v2.8.0 release job failed at the Pages step with Aborted with 10 warnings in strict mode!. (The red mkdocs-material "MkDocs 2.0" banner in the same log is a red herring.)

Reproduced locally against origin/dev: all ten warnings are dangling links out of docs/grouping-engine-scaling-results.md into bench/groupby_shapes/results/... and test/test_agg_contract.c — paths outside docs_dir, so mkdocs cannot resolve them. The five top-level engineering docs missing from nav were only INFO, not warnings, but they were orphan pages either way.

Removed

Raw measurement dumps belong with the benchmark harness, not the published site:

  • aggregation-fast-path-results.md
  • grouping-engine-scaling-results.md

The two references to the scaling results in grouping-engine-scaling-plan.md now point at bench/groupby_shapes/ instead of the deleted page.

Published

New "Design Notes" nav section, so the plans are reachable rather than orphaned:

  • aggregation-fast-path-plan.md
  • grouping-engine-scaling-plan.md
  • multicast-implementation-plan.md

Also listed multicast-usage.md under the .mc namespace — it was an orphan page too.

Verification

mkdocs build --strict run locally with .github/requirements-docs.txt:

  • origin/dev: Aborted with 10 warnings in strict mode! (exit 1)
  • this branch: Documentation built in 3.19 seconds (exit 0)

Also checked: no remaining references to either removed doc in docs/ or mkdocs.yml, and every top-level docs/*.md is now in nav or not_in_nav.

Note

pages.yml only triggers on pushes to master, so PR CI never builds the docs — this class of failure can currently only surface during a release. Worth a separate PR-triggered strict-build job.

The v2.8.0 Pages deploy failed with "Aborted with 10 warnings in strict
mode": several top-level engineering docs lived in docs/ but were absent
from nav, and grouping-engine-scaling-plan.md linked to a results doc
that nav never listed either.

- Add a "Design Notes" nav section for the three design plans.
- List multicast-usage.md under the .mc namespace; it was an orphan too.
- Delete aggregation-fast-path-results.md and grouping-engine-scaling-results.md:
  raw measurement dumps belong with the benchmark harness, not the
  published site. The two references to them in the scaling plan now
  point at bench/groupby_shapes/.
@singaraiona
singaraiona force-pushed the fix/unpublish-engineering-docs branch from 2fe5944 to 17bc874 Compare September 17, 2026 21:57
@singaraiona singaraiona changed the title docs: drop the engineering plan/results docs from the published site docs: fix the strict-mode Pages build Sep 17, 2026
@singaraiona
singaraiona merged commit 8a4fc85 into dev Sep 18, 2026
9 checks passed
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