Review and extend the documentation, and check it in CI (#5638)

* 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>

* Keep the customer links that could not be fixed

A dead link on the customers page is still the evidence of where the
use of the library was documented. Keep the original URLs of the entries
without a working replacement (Marne, Cisco Webex Desk Camera, Philips
Hue, CyberArk) and exclude exactly these URLs from the link check.

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

* Correct the duplicate-key recipe's claim about SAX positions

The SAX interface's key() receives no position either; only parse_error()
does. Also note that the recipe does not report the path to the repeated
key (see discussion #5085).

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

* Say the library is available as a single header and mention json_fwd.hpp

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

* Correct documentation errors found while hunting for bugs

- patch/patch_inplace: list the JSON pointer errors parse_error.106-109
  and out_of_range.402/404, and quote the actual parse_error.105 message.
- unflatten: list parse_error.106/107/108 and out_of_range.404.
- to_bson: list out_of_range.415 (binary subtype above 255) and note
  that 412 and 415 are new in 3.13.0.
- to_string: state that string_t must be convertible to std::string, also
  in the StringType requirements table.
- JSON Lines: a `while (input >> j)` loop also throws after the last value
  for concatenated JSON values; show a loop that works for both.
- BON8: a string gets 0xFF only if nothing follows it in the message; a
  string at the end of an array or object is ended by 0xFE.
- custom_string_type.hpp: add operator+=(char), which the "Always
  required" list asks for (json_pointer::to_string, flatten, unflatten,
  and diff did not compile), and an ADL int_to_string for diff and items.

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

* Cache the release headers with functools.lru_cache

Codacy (Pylint) flagged the mutable default argument that header() used
as its cache. functools.lru_cache keeps the same memoization without it.
The script's output is unchanged.

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

---------

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

docs/mkdocs/docs/features/element_access/checked_access.md

@@ -6,7 +6,7 @@ The [`at`](../../api/basic_json/at.md) member function performs checked access;
 desired value if it exists and throws a [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range)
 otherwise.
 
-??? example "Read access"
+??? example "Example: read access"
 
     Consider the following JSON value:
     
@@ -31,7 +31,7 @@ otherwise.
 
 The return value is a reference, so it can be used to modify the original value.
 
-??? example "Write access"
+??? example "Example: write access"
 
     ```cpp
     j.at("name") = "John Smith";
@@ -50,7 +50,7 @@ The return value is a reference, so it can be used to modify the original value.
 When accessing an invalid index (i.e., an index greater than or equal to the array size) or the passed object key is
 non-existing, an exception is thrown.
 
-??? example "Accessing via invalid index or missing key"
+??? example "Example: access via invalid index or missing key"
 
     ```cpp
     j.at("hobbies").at(3) = "cooking";

docs/mkdocs/docs/features/element_access/default_value.md

@@ -41,9 +41,9 @@ you want to access and a default value in case there is no value stored with tha
 
     The value function is a template, and the return type of the function is determined by the type of the provided
     default value unless otherwise specified. This can have unexpected effects. In the example below, we store a 64-bit
-    unsigned integer. We get exactly that value when using [`operator[]`](../../api/basic_json/operator[].md). However,
-    when we call `value` and provide `#!c 0` as default value, then `#!c -1` is returned. This occurs, because `#!c 0`
-    has type `#!c int` which overflows when handling the value `#!c 18446744073709551615`.
+    unsigned integer. We get exactly that value when using [`operator[]`](../../api/basic_json/operator%5B%5D.md).
+    However, when we call `value` and provide `#!c 0` as default value, then `#!c -1` is returned. This occurs,
+    because `#!c 0` has type `#!c int` which overflows when handling the value `#!c 18446744073709551615`.
 
     To address this issue, either provide a correctly typed default value or use the template parameter to specify the
     desired return type. Note that this issue occurs even when a value is stored at the provided key, and the default

docs/mkdocs/docs/features/element_access/index.md

@@ -5,5 +5,19 @@ There are many ways elements in a JSON value can be accessed:
 - unchecked access via [`operator[]`](unchecked_access.md)
 - checked access via [`at`](checked_access.md)
 - access with default value via [`value`](default_value.md)
-- iterators
-- JSON pointers
+- [iterators](../iterators.md)
+- [JSON pointers](../json_pointer.md)
+
+Testing whether a key or index exists before accessing it is also possible, with
+[`contains`](../../api/basic_json/contains.md) or [`find`](../../api/basic_json/find.md) (which returns an iterator to
+the value, or `end()` if it is not found).
+
+```mermaid
+flowchart TD
+    A["accessing a value"] --> B{"must it exist?"}
+    B -->|"yes, missing is an error"| C["at() -- throws"]
+    B -->|"yes, but checking is my job"| D["operator[] -- unchecked"]
+    B -->|"no, a fallback is fine"| E["value() -- default value"]
+    A --> F{"just testing first?"}
+    F -->|"yes"| G["contains() / find()"]
+```

docs/mkdocs/docs/features/element_access/unchecked_access.md

@@ -5,7 +5,7 @@
 Elements in a JSON object and a JSON array can be accessed via [`operator[]`](../../api/basic_json/operator%5B%5D.md)
 similar to a `#!cpp std::map` and a `#!cpp std::vector`, respectively.
 
-??? example "Read access"
+??? example "Example: read access"
 
     Consider the following JSON value:
     
@@ -31,7 +31,7 @@ similar to a `#!cpp std::map` and a `#!cpp std::vector`, respectively.
 The return value is a reference, so it can modify the original value. In case the passed object key is non-existing, a
 `#!json null` value is inserted which can immediately be overwritten.
 
-??? example "Write access"
+??? example "Example: write access"
 
     ```cpp
     j["name"] = "John Smith";
@@ -52,7 +52,7 @@ The return value is a reference, so it can modify the original value. In case th
 When accessing an invalid index (i.e., an index greater than or equal to the array size), the JSON array is resized such
 that the passed index is the new maximal index. Intermediate values are filled with `#!json null`.
 
-??? example "Filling up arrays with `#!json null` values"
+??? example "Example: filling up arrays with `#!json null` values"
 
     ```cpp
     j["hobbies"][0] = "running";
@@ -94,8 +94,8 @@ that the passed index is the new maximal index. Intermediate values are filled w
     - It is **undefined behavior** to access a const object with a non-existing key.
     - It is **undefined behavior** to access a const array with an invalid index.
     - In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor
-      symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](../macros.md#json_assertx). See the documentation
-      on [runtime assertions](../assertions.md) for more information.
+      symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](../../api/macros/json_assert.md). See the
+      documentation on [runtime assertions](../assertions.md) for more information.
 
 !!! failure "Exceptions"
 
@@ -105,8 +105,9 @@ that the passed index is the new maximal index. Intermediate values are filled w
 ## Performance: reserving array capacity
 
 There is no public `reserve(count)` member on `basic_json` for pre-allocating array capacity. If you are building
-a large array incrementally (e.g., via repeated `push_back()`) and know its final size ahead of time, you can
-reserve capacity via `get_ref()` to access the underlying `array_t` directly:
+a large array incrementally (e.g., via repeated [`push_back()`](../../api/basic_json/push_back.md)) and know its final
+size ahead of time, you can reserve capacity via [`get_ref()`](../../api/basic_json/get_ref.md) to access the
+underlying `array_t` directly:
 
 ```cpp
 json j = json::array();