docs: phase 9 � nav polish + About section + collapsible-table fix (#11)

* docs: phase 9 — nav polish, About section, collapsible-table fix

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.

* ci(artifact): exclude .git/ from wpt-corpus to avoid Windows digest-mismatch

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.

---------

Co-authored-by: chad-loder <26261238+chad-loder@users.noreply.github.com>

Author: chad-loder

.github/workflows/ci.yml

@@ -166,7 +166,19 @@ jobs:
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: wpt-corpus
-          path: reference/wpt
+          # Sparse-checkout leaves a populated ``.git/`` (HEAD ref, refs/,
+          # packed objects, occasional symlinks) — used by the SHA-verify
+          # step above but unused by matrix consumers, and a known source
+          # of digest-mismatch errors under ``download-artifact@v8`` on
+          # Windows runners (small files + special git entries trip the
+          # chunked archive digest check, which v8 defaults to ``error``).
+          # Excluding ``.git`` from the artifact (but not from the cache!)
+          # keeps the next workflow run's cache-hit fast while making the
+          # cross-OS download deterministic.
+          path: |
+            reference/wpt
+            !reference/wpt/.git
+            !reference/wpt/.git/**
           retention-days: 1
           if-no-files-found: error
 

CODE_OF_CONDUCT.md

@@ -15,7 +15,7 @@ project's maintainers represent it publicly.
 ## Enforcement
 
 Please report concerns to the maintainers via GitHub's private reporting
-channels (see [`SECURITY.md`](SECURITY.md) for the disclosure link,
+channels (see [`SECURITY.md`](https://github.com/chad-loder/yarlpattern/blob/main/SECURITY.md) for the disclosure link,
 which doubles as a private contact path until a dedicated address is
 published).
 

CONTRIBUTING.md

@@ -167,5 +167,5 @@ you push.
 
 ## Reporting security issues
 
-See [`SECURITY.md`](SECURITY.md) for scope and how to report (including
+See [`SECURITY.md`](https://github.com/chad-loder/yarlpattern/blob/main/SECURITY.md) for scope and how to report (including
 **public PRs or issues** if you prefer an open fix).

docs/about/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

docs/about/code-of-conduct.md

@@ -0,0 +1 @@
+--8<-- "CODE_OF_CONDUCT.md"

docs/about/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

docs/about/index.md

@@ -0,0 +1,18 @@
+# About
+
+Project governance, contribution guide, change log, security policy,
+and code of conduct.
+
+- [**Contributing**](contributing.md) — how to set up a dev
+  environment, run the linters and the full WPT corpus locally, the
+  commit-message convention, and what `just check` runs.
+- [**Changelog**](changelog.md) — release notes (Keep a Changelog
+  format; auto-stamped by python-semantic-release).
+- [**Security policy**](security.md) — the threat model, what's in
+  and out of scope, and how to report a vulnerability privately.
+- [**Code of Conduct**](code-of-conduct.md) — the community standards
+  for contributors and maintainers.
+
+These pages are rendered directly from the corresponding files at the
+repo root, so what you see here is the same content `git clone`
+shows. No second copy to drift.

docs/about/security.md

@@ -0,0 +1 @@
+--8<-- "SECURITY.md"

docs/comparisons/index.md

@@ -0,0 +1,22 @@
+# Comparisons
+
+Where yarlpattern fits next to the routing tools Python developers
+already know.
+
+- [**vs. `aiohttp.web.UrlDispatcher`**](aiohttp.md) — yarlpattern is a
+  predicate (the pattern *is* the API; no server context needed) and
+  matches across all eight URL components, not just the path.
+  `UrlDispatcher` is the right choice if you're building an aiohttp
+  service; yarlpattern is the right choice outside one — or when you
+  need hostname / port / scheme constraints alongside path.
+- [**vs. yarl**](yarl.md) — yarl is a URL parser/builder; yarlpattern
+  is a URLPattern matcher built on top of it. Covers the three places
+  yarlpattern is *stricter* than yarl (case-preserving `%XX`,
+  U+FFFD substitution, hostname truncation), the component-name
+  mapping (`scheme`/`host`/`path` → `protocol`/`hostname`/`pathname`),
+  and the yarl-style ergonomics (`yarl.URL` accepted directly,
+  `with_*` derivers).
+
+If you want to see yarlpattern *replace* a hand-rolled solution from
+some other framework — FastAPI, Starlette, Django, MCP servers,
+LiteLLM, KServe — those live under [Examples](../examples/index.md).

docs/explanation/index.md

@@ -0,0 +1,12 @@
+# Explanation
+
+How yarlpattern is built and why it's built that way.
+
+- [**Architecture**](architecture.md) — module layout, the
+  compile-time and match-time pipelines, the pluggable
+  regex-engine `Protocol` seam (stdlib `re` is the default; opt
+  into the `regex` package for full WPT conformance; a future
+  PyO3-backed engine plugs in next to those), and the three
+  places yarlpattern's implementation deliberately diverges from
+  the simplest possible shape (`yarl.URL` fast path, `with_*`
+  derivers, the WHATWG-strictness rules).