[nlohmann]

Summary

This removes six independent pieces of documentation-infrastructure debt identified in the #5718 tech-debt review: math formulas silently rendering as raw TeX on the published site, a docs-publish workflow that misses several embedded source files and persists unneeded git credentials, an example build that hides accidental deprecated-API calls, a structure checker with a parsing bug that silently disables NOLINT for several section names, a docset README/Info.plist pointing at a dead target and a stale URL, and two orphaned Doxygen-era files. Each commit is exactly one checklist item of #5718 and can be reviewed and merged on its own. Note that the math-formula fix (item 1) removes MathJax entirely and rewrites the 10 affected formulas as plain HTML (<sup>, <i>) rather than repairing the MathJax configuration or migrating to MathJax 3 — a reviewer may prefer keeping MathJax and fixing the config/privacy-plugin interaction instead. The follow-up commits listed under "Remaining checklist items" implement every item that was left open, so this PR now closes #5718; see "Public API" for their effects.

Changes

• Remove pymdownx.arithmatex and the MathJax extra_javascript entry from mkdocs.yml, and rewrite the 10 affected formulas across 6 pages as plain HTML (<sup>, <i>); the privacy plugin was dropping MathJax's ?config= query, so the formulas rendered as raw TeX on the published site (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 1)
• Extend publish_documentation.yml's path filter to the seven files embedded via pymdownx.snippets (.clang-tidy, CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, cmake/clang_flags.cmake, cmake/gcc_flags.cmake, tests/fmt_formatter/project/main.cpp, tools/astyle/.astylerc), switch its runner from the long-pinned ubuntu-22.04 to ubuntu-latest, and add persist-credentials: false to the ci_icpx/ci_nvhpc (ubuntu.yml) and msvc-vs2026/msvc-arm64 (windows.yml) checkouts, none of which push with git (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 2)
• Fix docs/Makefile's debug echo (a space instead of a comma left it printing an empty standard), deduplicate the example compile flags into EXAMPLE_CPPFLAGS/EXAMPLE_WARNFLAGS, and build with -Werror=deprecated-declarations by default so an accidental deprecated-API call in an example is no longer silently hidden, except for the three examples that intentionally document deprecated API (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 3)
• Fix check_structure.py's NOLINT parsing, which used str.strip(chars) and silently mangled any section name starting with N, O, L, I or T (e.g. "Notes", "Iterator invalidation") instead of stripping a literal prefix, by switching to a regex; also fix the admonition_title report, which used a 0-based line index while every other report in the file uses lineno+1 (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 4)
• Point the docset README at the real JSON_for_Modern_C++.docset make target and folder name instead of the non-existent nlohmann_json.docset, and update Info.plist's DashDocSetFallbackURL to the canonical https://json.nlohmann.me/ (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 5)
• Remove parse__iterator_pair.link and parse__pointers.link, two orphaned Doxygen-era permalink files left over from before Consolidate documentation #3071's cleanup, unreferenced by any page, script or config (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 7)

Tests

• make check_output_portable -j3 -k was run over all 480 docs/Makefile examples with -Werror=deprecated-declarations: every example compiled cleanly except the three in DEPRECATED_EXAMPLES, which compiled with -Wno-deprecated-declarations as intended; the only failures were pre-existing unordered_map iteration-order flakiness in three unrelated example tests, confirmed to fail identically on unmodified develop
• make style_check (docs/mkdocs) gave 0 warnings before and after the check_structure.py fix; the regex fix was also verified directly against <!-- NOLINT Notes -->, which previously mangled to 'otes'
• The site was built locally with mkdocs build; the built site/ contains no MathJax/arithmatex references, and the rewritten formulas (e.g. 2<sup>53</sup>, <i>n</i>) appear in the built HTML
• All three edited workflow YAML files were validated with yaml.safe_load
• git grep confirmed the two removed .link files and the docset's old make target/URL are unreferenced anywhere else in the tree
• make check-amalgamation passes; no include/ files are touched by this branch, so single_include/nlohmann/json.hpp is unchanged
• CI must confirm: the full CI compiler matrix (GCC/Clang/MSVC/ICC/NVHPC) and ci_test_documentation/ci_test_examples/actionlint/zizmor jobs; that the extended publish_documentation.yml path filter actually triggers a real run for the newly added file patterns; and that no artipacked finding remains for the workflow checkouts

Public API

No breaking changes. This PR touches only documentation content and infrastructure (docs/mkdocs/**, .github/workflows/publish_documentation.yml, .github/workflows/ubuntu.yml, .github/workflows/windows.yml, docs/Makefile, docs/mkdocs/scripts/check_structure.py, docs/docset/README.md, docs/docset/Info.plist) and two unreferenced example .link files. No file under include/ or single_include/ is changed, so the public API, ABI and compile-time behavior of the library are unaffected.

Follow-up commits:

• Docs infrastructure only.

Remaining checklist items (follow-up commits)

The parts that were left open are now implemented here as well, so this PR closes #5718.

• 5b249592d Make the MacPorts CMake example include its own snippet files instead of the Homebrew ones (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 6)
• c0aa5f0e5 Add persist-credentials: false to publish_documentation.yml's own checkout (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 2)
• 45dc218a1 Replace the quadratic shell loops of the docset Makefile's list_missing_pages/list_removed_paths with a comm(1) diff of two sorted lists (Docs infrastructure: MathJax formulas render as raw TeX, publish workflow misses snippet sources, example build hides deprecations, check script and docset fixes #5718 item 5)

Tests for these commits:

• list_missing_pages/list_removed_paths give byte-identical output to the old loops against the real docSet.sql and docs tree, with GNU Make 3.81 and 4.4.1 and in two locales
• publish_documentation.yml parses

c0aa5f0e5 overlaps #5638, which edits the same checkout step. #5718 item 5 suggested removing the two targets once #5638's check_docset() exists; until then they are kept, but fixed.

Closes #5718

---

This PR was written by Claude Code on behalf of @nlohmann.

🤖 Generated with Claude Code