Review and extend the documentation, and check it in CI

A review of all documentation pages found factual errors, dead links,
missing cross-references, and gaps in examples. This fixes them and adds
checks so the same problems are caught automatically.

Fixes:
- wrong signatures and version histories (operator!= C++20 member,
  binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...)
- stale descriptions (number parsing since #5283, UBJSON table, SAX
  example that no longer compiled, tsl::ordered_map advice)
- dead internal and external links; repology.org badges (the domain is
  suspended) replaced by badges that query the registries directly
- deprecation notes link the migration guide; the guide itself fixed

Additions:
- "See also" sections, cross-references, 25 runnable examples, 12
  Mermaid diagrams, new API pages for json_pointer::operator<=> and
  byte_container_with_subtype::operator==/!=
- landing page, guides for untrusted input and performance
- "unreleased" badge after versions newer than the latest release

Checks:
- strict documentation build (broken links/anchors fail it); CI and
  the publish workflow fetch the full history the build needs
- weekly external link check, Mermaid syntax check in CI
- check_structure.py: example titles, heading levels, alt texts,
  header links, docset index coverage; its unused-example check works
  again
- all examples produce the same output on every platform

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/mkdocs.yml

@@ -85,12 +85,14 @@ nav:
       - features/modules.md
       - 'nlohmann Namespace': features/namespace.md
       - features/object_order.md
+      - features/performance.md
       - Parsing:
           - features/parsing/index.md
           - features/parsing/json_lines.md
           - features/parsing/parse_exceptions.md
           - features/parsing/parser_callbacks.md
           - features/parsing/sax_interface.md
+          - features/parsing/untrusted_input.md
       - features/assertions.md
       - features/serialization.md
       - features/enum_conversion.md
@@ -233,6 +235,8 @@ nav:
           - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md
           - 'clear_subtype': api/byte_container_with_subtype/clear_subtype.md
           - 'has_subtype': api/byte_container_with_subtype/has_subtype.md
+          - 'operator==': api/byte_container_with_subtype/operator_eq.md
+          - 'operator!=': api/byte_container_with_subtype/operator_ne.md
           - 'set_subtype': api/byte_container_with_subtype/set_subtype.md
           - 'subtype': api/byte_container_with_subtype/subtype.md
       - adl_serializer:
@@ -249,6 +253,7 @@ nav:
           - 'operator string_t': api/json_pointer/operator_string_t.md
           - 'operator==': api/json_pointer/operator_eq.md
           - 'operator!=': api/json_pointer/operator_ne.md
+          - 'operator<=>': api/json_pointer/operator_spaceship.md
           - 'operator/': api/json_pointer/operator_slash.md
           - 'operator/=': api/json_pointer/operator_slasheq.md
           - 'parent_pointer': api/json_pointer/parent_pointer.md
@@ -287,7 +292,7 @@ nav:
           - 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md
           - 'JSON_DIAGNOSTIC_POSITIONS': api/macros/json_diagnostic_positions.md
           - 'JSON_DISABLE_ENUM_SERIALIZATION': api/macros/json_disable_enum_serialization.md
-          - 'JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20': api/macros/json_has_cpp_11.md
+          - 'JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26': api/macros/json_has_cpp_11.md
           - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM, JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md
           - 'JSON_HAS_RANGES': api/macros/json_has_ranges.md
           - 'JSON_HAS_STATIC_RTTI': api/macros/json_has_static_rtti.md
@@ -379,8 +384,21 @@ markdown_extensions:
       auto_append:
         - ../includes/glossary.md
 
+# report broken links, anchors, and nav entries as warnings, so that `mkdocs build --strict` (make build) fails
+validation:
+  nav:
+    omitted_files: warn
+    not_found: warn
+    absolute_links: warn
+  links:
+    not_found: warn
+    anchors: warn
+    absolute_links: warn
+    unrecognized_links: warn
+
 hooks:
   - hooks/copy_markdown_source.py
+  - hooks/unreleased_versions.py
 
 plugins:
   - search:
@@ -388,7 +406,8 @@ plugins:
       lang: en
   - minify:
       minify_html: true
-  - git-revision-date-localized
+  - git-revision-date-localized:
+      strict: false  # log "has no git logs" for uncommitted pages as info, not as a warning
   - redirects:
       redirect_maps:
         'api/basic_json/operator_gtgt.md': api/operator_gtgt.md
@@ -399,9 +418,18 @@ plugins:
         'home/code_of_conduct.md': community/code_of_conduct.md
   - htmlproofer: # see https://github.com/manuzhang/mkdocs-htmlproofer-plugin
       enabled: !ENV [ENABLED_HTMLPROOFER, False]
+      raise_error_after_finish: true   # log every broken link, then fail
+      skip_downloads: true             # check headers only (customers.md links large PDFs)
+      raise_error_excludes:            # integer status codes, fnmatch patterns
+        403: ['*']                     # bot protection against the plugin's "Bot <uuid>" user agent
+        429: ['*']                     # rate limiting (hundreds of github.com URLs)
+        502: ['*']
+        503: ['*']
+        504: ['*']                     # timeouts are reported as 504
+        -1: ['https://repology.org/*'] # connection errors; repology.org is suspended since 2026-09
+        401: ['https://fossies.org/*']        # answers the plugin's user agent with 401, browsers and curl with 200
+        404: ['https://gitlab.b-data.ch/*']   # answers the plugin's user agent with 404, browsers with 200
       ignore_urls:
-        - http://nlohmann.github.io/json/*
-        - https://nlohmann.github.io/json/*
         - mailto:*
   - privacy:
       # repology.org refuses requests from GitHub Actions runners, which made