Article notes links: explicit notes: field targeting the Notes tree, dev-only rendering

Motivation

Working notes for articles currently live in sibling .d/ folders inside docs/Articles/, auto-detected by _generate_article_listing (scan for <stem>.d/). Decision (2026-07-19): all notes live in the Notes tree (docs/Notes/...); articles link to their notes cluster explicitly. Notes links are a dev-environment affordance and must not appear on the production site.

Design

1. Frontmatter field

notes: "Notes/130 NCG/100 Paper Notes/"   # docs-relative path into the Notes tree

Explicit, one per article, replaces .d autodetection. During migration the .d scan stays as a fallback (used only when notes: is absent); remove it once all articles are migrated.

2. Rendering (both driven by the same field)

• Article page: a notes link in the article-links row of the header template (next to DOI/publications), styled like the other links.
• Listing ({{ARTICLES}} / {{FLAT_ARTICLES}}): notes entry per article, as today, but resolved from notes: instead of the .d scan.
• Link target: <notes-path>/index.md when it exists (so mkdocs validates the link), else the folder URL. This also fixes the current unvalidatable-directory-link warning (... contains a link '2026-07-12-Noncommutative-Calculus.d', but the target ... is not found).

3. Dev/prod gating — config, not post-processing

New plugin option:

- mkdocs-math:
    notes_links: true   # default; set false on production builds

plus environment override MKDOCS_MATH_NOTES_LINKS=0 (mirrors the existing MKDOCS_SEARCH_OVERRIDE pattern) so the publish pipeline can disable without touching mkdocs.yml. When disabled, neither the header link nor the listing entries render. Gating at render time is preferred over stripping HTML in the publish pipeline: no post-processor to maintain, no risk of leaking links in feeds/search indexes.

(Production additionally excludes the Notes tree by content selection in the prod repo — the flag only guarantees no dead links.)

4. Lint

• Warn when notes: is set but the path does not exist under docs.
• Warn (migration aid) when an article has a sibling .d/ folder but no notes: field.

Acceptance

• notes: field renders header + listing links in dev; nothing in prod (notes_links: false / env override)
• .d fallback behind the same flag, marked deprecated
• Directory-link validation warning gone (index.md targeting)
• Lint checks above

Start with _generate_article_listing and the article header template, then trace the existing MKDOCS_SEARCH_OVERRIDE configuration path. Implement the shared notes: resolution, dev-only gating, index.md target handling, and both lint warnings; done means the acceptance checks pass for dev, production, fallback, link validation, and linting.