docs: phase 9 â nav polish + About section + collapsible-table fix#11
Merged
Conversation
Three independent docs-site improvements bundled into one PR because
all three touch properdocs.yml.
== Material navigation upgrade ==
theme.features picks up:
* navigation.tabs — top-level sections render as a sticky
tab bar always visible in the header
* navigation.tabs.sticky — tabs stay pinned on scroll
* navigation.path — breadcrumbs above every page heading
* navigation.tracking — URL hash follows the active heading on
scroll so deep-links remain accurate
after a refresh / share
* navigation.indexes — section names link to per-section
index.md landing pages instead of being
inert headers
To back navigation.indexes, four new section landing pages:
docs/{overview,comparisons,explanation,reference}/index.md, each a
30-second TOC for that section. (examples/index.md predates this PR.)
properdocs.yml nav reordered to put each section's index.md first so
the section name itself becomes the landing-page link.
== About section ==
New top-level "About" section in the nav exposing the repo-root
governance files on the docs site without duplicating content:
* docs/about/index.md — section TOC + framing
* docs/about/contributing.md — ``--8<-- "CONTRIBUTING.md"``
* docs/about/changelog.md — ``--8<-- "CHANGELOG.md"``
* docs/about/security.md — ``--8<-- "SECURITY.md"``
* docs/about/code-of-conduct.md — ``--8<-- "CODE_OF_CONDUCT.md"``
Each page is a single-line ``pymdownx.snippets`` directive that
re-renders the corresponding root file inline at build time. Single
source of truth: the repo root.
``pymdownx.snippets`` joins markdown_extensions with
``base_path: ["."]`` so the snippet base is the repo root, not the
docs_dir.
Two relative ``SECURITY.md`` links in CONTRIBUTING.md and
CODE_OF_CONDUCT.md become absolute GitHub URLs so they resolve
correctly under both renderings (GitHub-native and snippet-included
into docs/about/).
rumdl MD041 is per-file-ignored for the four snippet-wrapper files
since the H1 lives in the included file, not the wrapper.
== Compliance report: collapsible tables now render ==
scripts/generate_compliance_report.py emitted ``<details>`` which
wrapped per-suite case tables in a block-level HTML element — per
CommonMark, the content of such an element is *not* re-parsed as
Markdown, so the inner ``| col | col |`` tables stayed as text. The
``md_in_html`` extension (already in our markdown_extensions list)
re-enters Markdown parsing when the element has ``markdown="1"``;
we now emit ``<details markdown='1'>``.
Built site goes from 1 ``<table>`` (the summary at top of
/wpt-compliance/) to 6 (summary + 5 per-suite case tables).
Confirmed locally.
github-actions
Bot
added
the
documentation
…ismatch actions/download-artifact@v8 changed the default digest-mismatch behavior to 'error' (it was 'warn' in earlier versions). The wpt-corpus artifact includes a sparse-checkout .git/ directory (HEAD ref, refs/, packed objects, occasional symlinks) which is a known source of chunked-archive digest mismatches on Windows runners — small files + special git entries trip the v8 strict digest check intermittently. Windows / Python 3.14 hit it on the Phase 9 PR run; Windows / Python 3.12 and 3.13 did not. Fix: exclude .git from the *artifact* via upload-artifact's path filter syntax. The actions/cache step still saves .git for the next workflow run, so cache-hits keep their git rev-parse HEAD verification path. Only the artifact (which matrix consumers read) is .git-less — and they don't need it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three independent docs-site improvements bundled because all three touch
properdocs.yml.1. Material navigation upgrade
theme.featurespicks up:navigation.tabsnavigation.tabs.stickynavigation.pathnavigation.trackingnavigation.indexesindex.mdlanding pagesFour new section landing pages back
navigation.indexes:docs/{overview,comparisons,explanation,reference}/index.md. (examples/index.mdpredates this PR.)Nav reordered so each section's
index.mdis first — the section name itself becomes the landing-page link.2. About section
New top-level About section exposing repo-root governance files on the docs site without duplicating content:
docs/about/contributing.md—--8<-- "CONTRIBUTING.md"docs/about/changelog.md—--8<-- "CHANGELOG.md"docs/about/security.md—--8<-- "SECURITY.md"docs/about/code-of-conduct.md—--8<-- "CODE_OF_CONDUCT.md"Single source of truth: the repo root.
pymdownx.snippetsjoinsmarkdown_extensionswithbase_path: ["."]. Two relativeSECURITY.mdlinks inCONTRIBUTING.mdandCODE_OF_CONDUCT.mdbecome absolute GitHub URLs so they resolve correctly under both renderings.3. Compliance-report table fix
scripts/generate_compliance_report.pyemitted<details>which wrapped per-suite case tables in a block-level HTML element — per CommonMark, the content stays as raw text. Themd_in_htmlextension (already configured) re-enters Markdown parsing when the element hasmarkdown="1"; the generator now emits<details markdown='1'>.Built site goes from 1
<table>(the summary at top of/wpt-compliance/) to 6 (summary + 5 per-suite case tables).Audit completeness
Verified the nav covers every file under
docs/:index.md,wpt-compliance.mdTest plan
just docsstrict build cleanjust lintall 11 tools pass/wpt-compliance/index.htmlcontains 6<table>blocks (was 1)/about/contributing/renders the full CONTRIBUTING content