Merge branch 'ci/path-filters' into ci/tiers

Keep the tiered job layout and apply the harden-runner 2.22.2 bump from #5962. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Merge branch 'develop' into ci/path-filters
2026-11-13 15:35:23 +00:00 · 2026-10-30 15:36:22 +01:00 · 2026-10-30 15:35:39 +01:00 · 2026-10-30 15:20:12 +01:00 · 2026-10-30 15:19:42 +01:00 · 2026-10-30 15:19:08 +01:00
481 changed files with 18144 additions and 4163 deletions
@@ -154,6 +154,15 @@ and each page's title (H1) and declaration by
 [`docs/docset/generate_docset.py`](https://github.com/nlohmann/json/blob/develop/docs/docset/generate_docset.py);
 `make build` reports API pages that cannot be classified.

+A pull request that changes only the documentation, Markdown files, GitHub metadata, or license files skips the
+compiler workflows (Ubuntu, macOS, Windows); the documentation and license checks still run. See
+[`tools/check_path_filters`](https://github.com/nlohmann/json/tree/develop/tools/check_path_filters) for the list of
+skipped files and what to do when a compiler job starts reading one of them.
+
+Most compiler jobs run only once a maintainer adds the label "🚀 ready to merge" to a pull request; until then, a
+smaller set of jobs runs on every push. See
+[How CI runs](https://json.nlohmann.me/community/quality_assurance/#how-ci-runs) for the sets and when they run.
+
 ### Amalgamate the source code

 The single-header files
@@ -28,7 +28,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -22,7 +22,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -46,7 +46,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -20,7 +20,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -13,7 +13,7 @@ jobs:
    runs-on: ubuntu-22.04
    steps:
    - name: Harden Runner
-      uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+      uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
      with:
        egress-policy: audit

@@ -27,7 +27,7 @@ jobs:

    steps:
    - name: Harden Runner
-      uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+      uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
      with:
        egress-policy: audit

@@ -38,14 +38,14 @@ jobs:

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
-      uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+      uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
      with:
        languages: c-cpp

    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
    # If this step fails, then you should remove it and run the build manually (see below)
    - name: Autobuild
-      uses: github/codeql-action/autobuild@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+      uses: github/codeql-action/autobuild@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1

    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+      uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
@@ -20,7 +20,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -21,7 +21,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -31,7 +31,7 @@ jobs:
      security-events: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -48,6 +48,6 @@ jobs:
          output: 'flawfinder_results.sarif'

      - name: Upload analysis results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
        with:
          sarif_file: ${{github.workspace}}/flawfinder_results.sarif
@@ -54,7 +54,7 @@ jobs:
    timeout-minutes: 60
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -23,7 +23,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -7,6 +7,25 @@ on:
      - master
      - release/*
  pull_request:
+    # Skip pull requests that change only files no job here reads. The list is checked by
+    # tools/check_path_filters/check_path_filters.py (repository_checks.yml); change both together.
+    paths:
+      - '**'
+      - '!docs/**'
+      - '!**.md'
+      - '!.github/*'
+      - '!.github/ISSUE_TEMPLATE/**'
+      - '!.github/external_ci/**'
+      - '!.github/workflows/**'
+      - '!.reuse/**'
+      - '!LICENSES/**'
+      - '!CITATION.cff'
+      - '!REUSE.toml'
+      # read by tools/check_build_options in the ci_meson_install job (ubuntu.yml)
+      - 'docs/mkdocs/docs/integration/package_managers.md'
+      # built by the swiftpm job (macos.yml)
+      - 'docs/mkdocs/docs/integration/swift/**'
+      - '.github/workflows/macos.yml'
  workflow_dispatch:

 concurrency:
@@ -37,7 +37,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -0,0 +1,83 @@
+name: Repository checks
+
+# Checks that concern files the compiler workflows (ubuntu.yml, macos.yml,
+# windows.yml) skip with their path filter: the documentation, the license
+# information, and the CI configuration itself. This workflow has no path filter.
+on:
+  push:
+    branches:
+      - develop
+      - master
+      - release/*
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check_ci_configuration:
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Check the path filters of the compiler workflows
+        run: python3 tools/check_path_filters/check_path_filters.py
+      - name: Check the job sets of the compiler workflows and their documentation
+        run: |
+          python3 -m venv venv
+          venv/bin/pip install --quiet -r tools/ci_jobs/requirements.txt
+          venv/bin/python tools/ci_jobs/ci_jobs.py
+
+  ci_reuse_compliance:
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_reuse_compliance
+
+  ci_test_documentation:
+    runs-on: ubuntu-26.04
+    strategy:
+      matrix:
+        target: [ci_test_examples, ci_test_build_documentation, ci_test_documentation_mermaid]
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          # the git-revision-date-localized plugin needs the history; a shallow clone makes the strict build fail
+          fetch-depth: ${{ matrix.target == 'ci_test_build_documentation' && '0' || '1' }}
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        if: matrix.target == 'ci_test_documentation_mermaid'
+        with:
+          node-version: 24
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ${{ matrix.target }}
@@ -40,7 +40,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -80,6 +80,6 @@ jobs:

      # Upload the results to GitHub's code scanning dashboard.
      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
        with:
          sarif_file: results.sarif
@@ -36,7 +36,7 @@ jobs:
    runs-on: ubuntu-26.04
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -65,7 +65,7 @@ jobs:

      # Upload SARIF file generated in previous step
      - name: Upload SARIF file
-        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
        with:
          sarif_file: semgrep.sarif
        if: always()
@@ -16,7 +16,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -7,17 +7,62 @@ on:
      - master
      - release/*
  pull_request:
+    # labeled: the "🚀 ready to merge" label starts the full set (see below)
+    types: [opened, synchronize, reopened, labeled]
+    # Skip pull requests that change only files no job here reads. The list is checked by
+    # tools/check_path_filters/check_path_filters.py (repository_checks.yml); change both together.
+    paths:
+      - '**'
+      - '!docs/**'
+      - '!**.md'
+      - '!.github/*'
+      - '!.github/ISSUE_TEMPLATE/**'
+      - '!.github/external_ci/**'
+      - '!.github/workflows/**'
+      - '!.reuse/**'
+      - '!LICENSES/**'
+      - '!CITATION.cff'
+      - '!REUSE.toml'
+      # read by tools/check_build_options in the ci_meson_install job (ubuntu.yml)
+      - 'docs/mkdocs/docs/integration/package_managers.md'
+      # built by the swiftpm job (macos.yml)
+      - 'docs/mkdocs/docs/integration/swift/**'
+      - '.github/workflows/ubuntu.yml'
+  schedule:
+    # the nightly set (see below), on develop
+    - cron: '0 2 * * *'
  workflow_dispatch:

 permissions:
  contents: read

+# A run triggered by any other label gets a group of its own, so it does not
+# cancel the run of the last push; its jobs are skipped.
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref || github.run_id }}
+  group: ${{ github.workflow }}-${{ github.event_name == 'schedule' && 'nightly' || github.ref || github.run_id }}${{ github.event.action == 'labeled' && github.event.label.name != '🚀 ready to merge' && format('-{0}', github.run_id) || '' }}
  cancel-in-progress: true

+# The jobs are split into three sets (see "How CI runs" in
+# docs/mkdocs/docs/community/quality_assurance.md):
+#
+# - PR set: every pull request push and every push; chosen because these jobs
+#   caught 92 % of the failing commits in Sep/Oct 2026.
+# - full set: after the PR set passed, on pushes and on pull requests with the
+#   "🚀 ready to merge" label; every remaining compiler, version and standard.
+# - nightly set: slow tools and rare compilers, nightly on develop, on pushes
+#   to master and release/*, and when started by hand.
+#
+# A matrix whose entries belong to different sets is split into one job per
+# set; the jobs share their steps through YAML anchors. tools/ci_jobs checks
+# that every job belongs to exactly one set.
+
 jobs:
+  ###########################################################################
+  # PR set
+  ###########################################################################
+
  ci_test_gcc:
+    if: &pr_set ${{ github.event_name != 'schedule' && (github.event.action != 'labeled' || github.event.label.name == '🚀 ready to merge') }}
    runs-on: ubuntu-latest
    container: gcc:latest
    steps:
@@ -32,6 +77,7 @@ jobs:
        run: cmake --build build --target ci_test_gcc

  ci_meson_install:
+    if: *pr_set
    runs-on: ubuntu-26.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -76,43 +122,15 @@ jobs:
          cmake -S tests/cmake_import/project -B build-import-split -DCMAKE_PREFIX_PATH=${{ github.workspace }}/install-split
          cmake --build build-import-split

-  ci_infer:
-    runs-on: ubuntu-26.04
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
-        with:
-          egress-policy: audit
-
-      - name: Install Infer
-        run: |
-          wget -q -O - "https://github.com/facebook/infer/releases/download/v1.3.0/infer-linux-x86_64-v1.3.0.tar.xz" | sudo tar -C /opt -xJ
-          sudo ln -s /opt/infer-linux-x86_64-v1.3.0/bin/infer /usr/local/bin/infer
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build
-        run: cmake --build build --target ci_infer
-      - name: Archive Infer report
-        if: always()
-        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
-        with:
-          name: infer-report
-          path: ${{ github.workspace }}/build/build_infer/infer-out/report.txt
-          if-no-files-found: ignore
-
  ci_static_analysis_ubuntu:
+    if: *pr_set
    runs-on: ubuntu-26.04
    strategy:
      matrix:
-        target: [ci_test_single_header, ci_cppcheck, ci_cpplint, ci_reproducible_tests, ci_non_git_tests, ci_offline_testdata, ci_reuse_compliance, ci_test_valgrind]
-    steps:
+        target: [ci_cpplint]
+    steps: &static_analysis_ubuntu_steps
      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
        with:
          egress-policy: audit

@@ -130,12 +148,13 @@ jobs:
        run: cmake --build build --target ${{ matrix.target }}

  ci_static_analysis_clang:
+    if: *pr_set
    runs-on: ubuntu-latest
    container: silkeh/clang:22
    strategy:
      matrix:
-        target: [ci_test_clang, ci_clang_tidy, ci_test_clang_sanitizer, ci_clang_analyze, ci_single_binaries]
-    steps:
+        target: [ci_test_clang, ci_clang_tidy, ci_test_clang_sanitizer, ci_single_binaries]
+    steps: &static_analysis_clang_steps
      - name: Install git, clang-tools, iwyu (ci_single_binaries), and unzip
        run: apt-get update ; apt-get install -y git clang-tools iwyu unzip
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -149,12 +168,13 @@ jobs:
        run: cmake --build build --target ${{ matrix.target }}

  ci_cmake_options:
+    if: *pr_set
    runs-on: ubuntu-latest
    container: ubuntu:24.04
    strategy:
      matrix:
-        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls, ci_test_disableenumserialization, ci_test_disabletuplereferenceconversion, ci_test_skiplibraryversioncheck, ci_test_simdutf, ci_test_strict_nul_handling, ci_test_delete_deprecated_functions, ci_test_no_thread_local]
-    steps:
+        target: [ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noglobaludls]
+    steps: &cmake_options_steps
      - name: Install build-essential
        run: apt-get update ; apt-get install -y build-essential unzip wget git
      # the CMake 3.5.0 release binary that ci_cmake_flags downloads links
@@ -174,50 +194,17 @@ jobs:
      - name: Build
        run: cmake --build build --target ${{ matrix.target }}

-  ci_test_coverage:
-    runs-on: ubuntu-26.04
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
-        with:
-          egress-policy: audit
-
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - name: Install dependencies and de_DE locale
-        run: |
-          sudo apt-get clean
-          sudo apt-get update
-          sudo apt-get install -y build-essential cmake lcov ninja-build make locales gcc-multilib g++-multilib
-          sudo locale-gen de_DE
-          sudo update-locale
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build
-        run: cmake --build build --target ci_test_coverage
-      - name: Archive coverage report
-        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
-        with:
-          name: code-coverage-report
-          path: ${{ github.workspace }}/build/html
-      - name: Publish report to Coveralls
-        uses: coverallsapp/github-action@8d6379e14d29928660c4ba802d8e85393440b329 # v2.3.8
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          path-to-lcov: ${{ github.workspace }}/build/json.info.filtered.noexcept
-          fail-on-error: false
-
  ci_test_compilers_gcc_old:
+    if: *pr_set
    runs-on: ubuntu-latest
    strategy:
      matrix:
-        compiler: ['4.8', '4.9', '5', '6']
+        compiler: ['4.8']
    # official gcc:4.8/4.9/5/6 images fail to check out code (too old for
    # actions/checkout); install the old compilers on top of official ubuntu:20.04
    # instead, mirroring what the (now retired) custom json-ci image did.
    container: ubuntu:20.04
-    steps:
+    steps: &compilers_gcc_old_steps
      - name: Install g++-${{ matrix.compiler }}
        run: |
          export DEBIAN_FRONTEND=noninteractive
@@ -250,7 +237,137 @@ jobs:
      - name: Build
        run: cmake --build build --target ci_test_compiler_g++-${{ matrix.compiler }}

-  ci_test_compilers_gcc:
+  ci_test_compilers_clang:
+    if: *pr_set
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        compiler: ['3.4']
+    container: silkeh/clang:${{ matrix.compiler }}
+    steps: &compilers_clang_steps
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
+      - name: Disable filesystem support (std::filesystem is unusable) for clang 7 / 8 / 9 / 10
+        run: echo "JSON_FORCED_GLOBAL_COMPILE_OPTIONS=-DJSON_HAS_FILESYSTEM=0;-DJSON_HAS_EXPERIMENTAL_FILESYSTEM=0" >> "$GITHUB_ENV"
+        if: ${{ matrix.compiler == '7' || matrix.compiler == '8' || matrix.compiler == '9' || matrix.compiler == '10' }}
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_test_compiler_default
+
+  ci_test_standards_gcc:
+    if: *pr_set
+    runs-on: ubuntu-latest
+    container: gcc:latest
+    strategy:
+      matrix:
+        standard: [26]
+    steps: &standards_gcc_steps
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_test_gcc_cxx${{ matrix.standard }}
+
+  ci_test_standards_clang:
+    if: *pr_set
+    runs-on: ubuntu-latest
+    container: silkeh/clang:latest
+    strategy:
+      matrix:
+        standard: [26]
+        stdlib: [libcxx]
+    steps: &standards_clang_steps
+      - name: Install git and unzip
+        run: apt-get update ; apt-get install -y git unzip
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build with libc++
+        run: cmake --build build --target ci_test_clang_libcxx_cxx${{ matrix.standard }}
+        if: ${{ matrix.stdlib == 'libcxx' }}
+      - name: Build with libstdc++
+        run: cmake --build build --target ci_test_clang_cxx${{ matrix.standard }}
+        if: ${{ matrix.stdlib == 'libstdcxx' }}
+
+  ci_emscripten:
+    if: *pr_set
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - name: Install emscripten
+        uses: mymindstorm/setup-emsdk@4528d102f7230f0e7b276855c01ea1159be0e984 # v16
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
+      - name: Run CMake
+        run: cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$EMSDK/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -GNinja
+      - name: Build
+        run: cmake --build build
+
+  ###########################################################################
+  # full set: starts after the PR set passed
+  ###########################################################################
+
+  ci_static_analysis_ubuntu_full:
+    needs: &pr_set_jobs [ci_test_gcc, ci_meson_install, ci_static_analysis_ubuntu, ci_static_analysis_clang, ci_cmake_options, ci_test_compilers_gcc_old, ci_test_compilers_clang, ci_test_standards_gcc, ci_test_standards_clang, ci_emscripten]
+    if: &full_set ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, '🚀 ready to merge') }}
+    runs-on: ubuntu-26.04
+    strategy:
+      matrix:
+        target: [ci_test_single_header, ci_cppcheck, ci_reproducible_tests, ci_non_git_tests, ci_offline_testdata]
+    steps: *static_analysis_ubuntu_steps
+
+  ci_static_analysis_clang_full:
+    needs: *pr_set_jobs
+    if: *full_set
+    runs-on: ubuntu-latest
+    container: silkeh/clang:22
+    strategy:
+      matrix:
+        target: [ci_clang_analyze]
+    steps: *static_analysis_clang_steps
+
+  ci_cmake_options_full:
+    needs: *pr_set_jobs
+    if: *full_set
+    runs-on: ubuntu-latest
+    container: ubuntu:24.04
+    strategy:
+      matrix:
+        target: [ci_cmake_flags, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_disableenumserialization, ci_test_disabletuplereferenceconversion, ci_test_skiplibraryversioncheck, ci_test_simdutf, ci_test_strict_nul_handling, ci_test_delete_deprecated_functions, ci_test_no_thread_local]
+    steps: *cmake_options_steps
+
+  ci_test_compilers_gcc_old_full:
+    needs: *pr_set_jobs
+    if: *full_set
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        compiler: ['4.9', '5', '6']
+    container: ubuntu:20.04
+    steps: *compilers_gcc_old_steps
+
+  ci_test_compilers_gcc_full:
+    needs: *pr_set_jobs
+    if: *full_set
    runs-on: ubuntu-latest
    strategy:
      matrix:
@@ -268,91 +385,44 @@ jobs:
      - name: Build
        run: cmake --build build --target ci_test_compiler_default

-  ci_test_compilers_clang:
+  ci_test_compilers_clang_full:
+    needs: *pr_set_jobs
+    if: *full_set
    runs-on: ubuntu-latest
    strategy:
      matrix:
-        compiler: ['3.4', '3.5', '3.6', '3.7', '3.8', '3.9', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15-bullseye', '16', '17', '18', '19', '20', '21', '22', 'latest']
+        compiler: ['3.5', '3.6', '3.7', '3.8', '3.9', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15-bullseye', '16', '17', '18', '19', '20', '21', '22', 'latest']
    container: silkeh/clang:${{ matrix.compiler }}
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
-      - name: Disable filesystem support (std::filesystem is unusable) for clang 7 / 8 / 9 / 10
-        run: echo "JSON_FORCED_GLOBAL_COMPILE_OPTIONS=-DJSON_HAS_FILESYSTEM=0;-DJSON_HAS_EXPERIMENTAL_FILESYSTEM=0" >> "$GITHUB_ENV"
-        if: ${{ matrix.compiler == '7' || matrix.compiler == '8' || matrix.compiler == '9' || matrix.compiler == '10' }}
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build
-        run: cmake --build build --target ci_test_compiler_default
+    steps: *compilers_clang_steps

-  ci_test_standards_gcc:
+  ci_test_standards_gcc_full:
+    needs: *pr_set_jobs
+    if: *full_set
    runs-on: ubuntu-latest
    container: gcc:latest
    strategy:
      matrix:
-        standard: [11, 14, 17, 20, 23, 26]
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build
-        run: cmake --build build --target ci_test_gcc_cxx${{ matrix.standard }}
+        standard: [11, 14, 17, 20, 23]
+    steps: *standards_gcc_steps

-  ci_test_standards_clang:
+  ci_test_standards_clang_full:
+    needs: *pr_set_jobs
+    if: *full_set
    runs-on: ubuntu-latest
    container: silkeh/clang:latest
    strategy:
      matrix:
        standard: [11, 14, 17, 20, 23, 26]
        stdlib: [libcxx, libstdcxx]
-    steps:
-      - name: Install git and unzip
-        run: apt-get update ; apt-get install -y git unzip
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build with libc++
-        run: cmake --build build --target ci_test_clang_libcxx_cxx${{ matrix.standard }}
-        if: ${{ matrix.stdlib == 'libcxx' }}
-      - name: Build with libstdc++
-        run: cmake --build build --target ci_test_clang_cxx${{ matrix.standard }}
-        if: ${{ matrix.stdlib == 'libstdcxx' }}
-
-  ci_cuda_example:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        # 11.8.0: newest pre-C++20 CUDA release, exercises the C++17 fallback
-        # path (tests/cuda_example/CMakeLists.txt picks the standard per nvcc
-        # version); 12.1.1: permanent regression guard for #3907 (nvcc 12.0/12.1
-        # choke on enable_borrowed_range at C++20, fixed in 12.2); 12.6.3: recent
-        # CUDA/C++20 coverage.
-        cuda: ['11.8.0', '12.1.1', '12.6.3']
-    container: nvidia/cuda:${{ matrix.cuda }}-devel-ubuntu22.04
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build
-        run: cmake --build build --target ci_cuda_example
+        exclude:
+          # in the PR set
+          - standard: 26
+            stdlib: libcxx
+    steps: *standards_clang_steps

  ci_module_cpp20:
+    needs: *pr_set_jobs
+    if: *full_set
    strategy:
      matrix:
        container: ['gcc:latest', 'silkeh/clang:latest']
@@ -382,7 +452,109 @@ jobs:
      - name: Build
        run: cmake --build build --target ci_module_cpp20

+  ###########################################################################
+  # nightly set
+  ###########################################################################
+
+  ci_infer:
+    if: &nightly_set ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref != 'refs/heads/develop') }}
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - name: Install Infer
+        run: |
+          wget -q -O - "https://github.com/facebook/infer/releases/download/v1.3.0/infer-linux-x86_64-v1.3.0.tar.xz" | sudo tar -C /opt -xJ
+          sudo ln -s /opt/infer-linux-x86_64-v1.3.0/bin/infer /usr/local/bin/infer
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_infer
+      - name: Archive Infer report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: infer-report
+          path: ${{ github.workspace }}/build/build_infer/infer-out/report.txt
+          if-no-files-found: ignore
+
+  ci_static_analysis_ubuntu_nightly:
+    if: *nightly_set
+    runs-on: ubuntu-26.04
+    strategy:
+      matrix:
+        target: [ci_test_valgrind]
+    steps: *static_analysis_ubuntu_steps
+
+  ci_test_coverage:
+    if: *nightly_set
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install dependencies and de_DE locale
+        run: |
+          sudo apt-get clean
+          sudo apt-get update
+          sudo apt-get install -y build-essential cmake lcov ninja-build make locales gcc-multilib g++-multilib
+          sudo locale-gen de_DE
+          sudo update-locale
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_test_coverage
+      - name: Archive coverage report
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: code-coverage-report
+          path: ${{ github.workspace }}/build/html
+      - name: Publish report to Coveralls
+        uses: coverallsapp/github-action@8d6379e14d29928660c4ba802d8e85393440b329 # v2.3.8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path-to-lcov: ${{ github.workspace }}/build/json.info.filtered.noexcept
+          fail-on-error: false
+
+  ci_cuda_example:
+    if: *nightly_set
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 11.8.0: newest pre-C++20 CUDA release, exercises the C++17 fallback
+        # path (tests/cuda_example/CMakeLists.txt picks the standard per nvcc
+        # version); 12.1.1: permanent regression guard for #3907 (nvcc 12.0/12.1
+        # choke on enable_borrowed_range at C++20, fixed in 12.2); 12.6.3: recent
+        # CUDA/C++20 coverage.
+        cuda: ['11.8.0', '12.1.1', '12.6.3']
+    container: nvidia/cuda:${{ matrix.cuda }}-devel-ubuntu22.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_cuda_example
+
  ci_icpc:
+    if: *nightly_set
    runs-on: ubuntu-latest
    # Intel discontinued the classic icc/icpc compiler in oneAPI 2024.0; this is
    # Intel's own last officially published image that still includes it.
@@ -402,6 +574,7 @@ jobs:
        run: cmake --build build --target ci_icpc

  ci_icpx:
+    if: *nightly_set
    runs-on: ubuntu-latest
    container: intel/oneapi-hpckit:latest
    steps:
@@ -416,6 +589,7 @@ jobs:
        run: cmake --build build --target ci_icpx

  ci_nvhpc:
+    if: *nightly_set
    runs-on: ubuntu-latest
    container: nvcr.io/nvidia/nvhpc:25.5-devel-cuda12.9-ubuntu22.04
    steps:
@@ -429,54 +603,10 @@ jobs:
      - name: Build
        run: cmake --build build --target ci_nvhpc

-  ci_emscripten:
-    runs-on: ubuntu-26.04
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
-        with:
-          egress-policy: audit
-
-      - name: Install emscripten
-        uses: mymindstorm/setup-emsdk@4528d102f7230f0e7b276855c01ea1159be0e984 # v16
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-      - name: Get latest CMake and ninja
-        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
-      - name: Run CMake
-        run: cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$EMSDK/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -GNinja
-      - name: Build
-        run: cmake --build build
-
-  ci_test_documentation:
-    runs-on: ubuntu-26.04
-    strategy:
-      matrix:
-        target: [ci_test_examples, ci_test_build_documentation, ci_test_documentation_mermaid]
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
-        with:
-          egress-policy: audit
-
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-          # the git-revision-date-localized plugin needs the history; a shallow clone makes the strict build fail
-          fetch-depth: ${{ matrix.target == 'ci_test_build_documentation' && '0' || '1' }}
-      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
-        if: matrix.target == 'ci_test_documentation_mermaid'
-        with:
-          node-version: 24
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build
-        run: cmake --build build --target ${{ matrix.target }}
-
  # Native Linux ARM64 runner with the latest GCC. The ubuntu-24.04-arm label is
  # only available for public repositories.
  ci_test_arm64:
+    if: *nightly_set
    runs-on: ubuntu-24.04-arm
    container: gcc:latest
    steps:
@@ -491,3 +621,33 @@ jobs:
        run: cmake -S . -B build -DJSON_CI=On
      - name: Build
        run: cmake --build build --target ci_test_compiler_default
+
+  # A failure of a scheduled run opens an issue, or comments on the open one.
+  nightly_report:
+    needs: [ci_infer, ci_static_analysis_ubuntu_nightly, ci_test_coverage, ci_cuda_example, ci_icpc, ci_icpx, ci_nvhpc, ci_test_arm64]
+    if: ${{ always() && github.event_name == 'schedule' && contains(needs.*.result, 'failure') }}
+    runs-on: ubuntu-26.04
+    permissions:
+      issues: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - name: Open or update the nightly failure issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          WORKFLOW: ${{ github.workflow }}
+          SHA: ${{ github.sha }}
+        run: |
+          title="Nightly CI failure (${WORKFLOW})"
+          body="The nightly run of ${WORKFLOW} on ${SHA:0:10} failed: ${RUN_URL}"
+          number=$(gh issue list --state open --search "in:title \"${title}\"" --json number,title --jq "map(select(.title == \"${title}\")) | .[0].number // empty")
+          if [ -n "$number" ]; then
+            gh issue comment "$number" --body "$body"
+          else
+            gh issue create --title "$title" --body "$body"
+          fi
@@ -7,6 +7,25 @@ on:
      - master
      - release/*
  pull_request:
+    # Skip pull requests that change only files no job here reads. The list is checked by
+    # tools/check_path_filters/check_path_filters.py (repository_checks.yml); change both together.
+    paths:
+      - '**'
+      - '!docs/**'
+      - '!**.md'
+      - '!.github/*'
+      - '!.github/ISSUE_TEMPLATE/**'
+      - '!.github/external_ci/**'
+      - '!.github/workflows/**'
+      - '!.reuse/**'
+      - '!LICENSES/**'
+      - '!CITATION.cff'
+      - '!REUSE.toml'
+      # read by tools/check_build_options in the ci_meson_install job (ubuntu.yml)
+      - 'docs/mkdocs/docs/integration/package_managers.md'
+      # built by the swiftpm job (macos.yml)
+      - 'docs/mkdocs/docs/integration/swift/**'
+      - '.github/workflows/windows.yml'
  workflow_dispatch:

 permissions:
@@ -28,7 +47,7 @@ jobs:
        with:
          persist-credentials: false
      - name: Set up MinGW
-        uses: egor-tensin/setup-mingw@41b837e47d7f85214629d255b9c4bc3fcbe9fd63 # v3.0
+        uses: egor-tensin/setup-mingw@d54f5ef0ce585bd3fbb1f8a71b5b254f59dbf931 # v3.0
        with:
          platform: ${{ matrix.architecture }}
          version: 12.2.0 # https://github.com/egor-tensin/setup-mingw/issues/14
@@ -153,7 +172,7 @@ jobs:
      - name: Install Clang
        run: curl -fsSL -o LLVM${{ matrix.version }}.exe https://github.com/llvm/llvm-project/releases/download/llvmorg-${{ matrix.version }}/LLVM-${{ matrix.version }}-win64.exe ; 7z x LLVM${{ matrix.version }}.exe -y -o"C:/Program Files/LLVM"
      - name: Set up MinGW
-        uses: egor-tensin/setup-mingw@41b837e47d7f85214629d255b9c4bc3fcbe9fd63 # v3.0
+        uses: egor-tensin/setup-mingw@d54f5ef0ce585bd3fbb1f8a71b5b254f59dbf931 # v3.0
        with:
          platform: x64
          version: 12.2.0 # https://github.com/egor-tensin/setup-mingw/issues/14
@@ -1408,9 +1408,9 @@ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR I
 - The class contains a port of the shortest double-to-decimal conversion of [Żmij](https://github.com/vitaut/zmij) by Victor Zverovich, including the conversion of the digits to text by Xiang JunBo and the SIMD instruction sequence of Dougall Johnson, which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above). Copyright &copy; 2025 [Victor Zverovich](https://github.com/vitaut)
 - The class contains a copy of [Hedley](https://nemequ.github.io/hedley/) from Evan Nemerson which is licensed as [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/).
 - The class contains parts of [Google Abseil](https://github.com/abseil/abseil-cpp) which is licensed under the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).
- The class contains an adapted version of the Eisel-Lemire algorithm, its table of powers of five, and its digit comparison for long numbers from [fast_float](https://github.com/fastfloat/fast_float) by Daniel Lemire and contributors, which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here), the Apache 2.0 License, and the Boost Software License. Copyright &copy; 2021 The fast_float authors
+- The class contains an adapted version of the Eisel-Lemire algorithm, its table of powers of five, its digit comparison for long numbers, and its parsing of eight digits at a time from [fast_float](https://github.com/fastfloat/fast_float) by Daniel Lemire and contributors, which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here), the Apache 2.0 License, and the Boost Software License. Copyright &copy; 2021 The fast_float authors
 - The view's parser (`<nlohmann/json_view.hpp>`) contains techniques and code adapted from [yyjson](https://github.com/ibireme/yyjson) by YaoYuan, which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above): table-driven decoding of `\u` escapes and fixed-offset unrolled checks.
- The view's parser (`<nlohmann/json_view.hpp>`) validates non-ASCII strings with the vector UTF-8 check of [simdjson](https://github.com/simdjson/simdjson) by Daniel Lemire, Geoff Langdale, John Keiser, and contributors (its "lookup4" algorithm and tables, after J. Keiser and D. Lemire, "Validating UTF-8 In Less Than One Instruction Per Byte", 2021), which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here) and the Apache 2.0 License. Copyright &copy; 2018-2025 The simdjson authors
+- The class's lexer and the view's parser (`<nlohmann/json_view.hpp>`) validate non-ASCII strings with the vector UTF-8 check of [simdjson](https://github.com/simdjson/simdjson) by Daniel Lemire, Geoff Langdale, John Keiser, and contributors (its "lookup4" algorithm and tables, after J. Keiser and D. Lemire, "Validating UTF-8 In Less Than One Instruction Per Byte", 2021), which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here) and the Apache 2.0 License. Copyright &copy; 2018-2025 The simdjson authors

 <img align="right" src="https://git.fsfe.org/reuse/reuse-ci/raw/branch/master/reuse-horizontal.png" alt="REUSE Software">

@@ -30,7 +30,7 @@ class (either explicitly or via the conversion operators).

 ## Return value

-1. (none) -- the converted value is written to the output parameter `val`.
+1. (none) — the converted value is written to the output parameter `val`.
 2. the JSON value `j` converted to `TargetType`

 ## Examples
@@ -67,7 +67,9 @@ class (either explicitly or via the conversion operators).

 ## See also

- [to_json](to_json.md)
+- [`to_json`](to_json.md) - convert a C++ value to JSON
+- [Arbitrary Type Conversions](../../features/arbitrary_types.md) - write your own `from_json` and `to_json` functions
+- [Converting values](../../features/conversions.md) - overview of `get`, `get_to` and implicit conversions

 ## Version history

@@ -33,10 +33,10 @@ struct adl_serializer {
 ## See also

 - [Arbitrary type conversions](../../features/arbitrary_types.md) - how to make your types convertible
- [**get**](../basic_json/get.md) / [**get_to**](../basic_json/get_to.md) - convert a JSON value to a C++ type
- [**basic_json**](../basic_json/basic_json.md) - construct a JSON value from a C++ value
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE**](../macros/nlohmann_define_type_intrusive.md) - generate the conversion functions for a type
- [Specializing enum conversion](../../features/enum_conversion.md)
+- [`get`](../basic_json/get.md) - / [`get_to`](../basic_json/get_to.md) - convert a JSON value to a C++ type
+- [`basic_json`](../basic_json/basic_json.md) - construct a JSON value from a C++ value
+- [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](../macros/nlohmann_define_type_intrusive.md) - generate the conversion functions for a type
+- [Specializing enum conversion](../../features/enum_conversion.md) - serializing enums as JSON strings

 ## Version history

@@ -36,7 +36,9 @@ This function is usually called by the constructors of the [basic_json](../basic

 ## See also

- [from_json](from_json.md)
+- [`from_json`](from_json.md) - convert JSON to a C++ value
+- [Arbitrary Type Conversions](../../features/arbitrary_types.md) - write your own `from_json` and `to_json` functions
+- [Converting values](../../features/conversions.md) - overview of `get`, `get_to` and implicit conversions

 ## Version history

@@ -148,15 +148,20 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by

 ## See also

- [parse](parse.md) - deserialize from a compatible input
- [sax_parse](sax_parse.md) - parse input using the SAX interface
- [operator>>](../operator_gtgt.md) - deserialize from stream
+- [`parse`](parse.md) - deserialize from a compatible input
+- [`sax_parse`](sax_parse.md) - parse input using the SAX interface
+- [`operator>>`](../operator_gtgt.md) - deserialize from stream
 - [`JSON_STRICT_NUL_HANDLING`](../macros/json_strict_nul_handling.md) - opt in to rejecting a NUL byte in the input
  instead of treating it as end of input
 - [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md) - read a `std::istream` one character
  at a time
 - [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) - read a `FILE*` with the locking stdio
  functions
+- [Parsing](../../features/parsing/index.md) - overview of the parsing functions
+- [Comments](../../features/comments.md) - ignore `//` and `/* */` comments while parsing
+- [Trailing Commas](../../features/trailing_commas.md) - accept trailing commas in arrays and objects
+- [Parsing and Exceptions](../../features/parsing/parse_exceptions.md) - handling parse errors and locating them in the input
+- [Parsing Untrusted Input](../../features/parsing/untrusted_input.md) - limits and checks for input you do not control

 ## Version history

@@ -29,9 +29,9 @@ Linear in the size of `init`.
 This function is only needed to express two edge cases that cannot be realized with the initializer list constructor
 ([`basic_json(initializer_list_t, bool, value_t)`](basic_json.md)). These cases are:

-1. creating an array whose elements are all pairs whose first element is a string -- in this case, the initializer list
+1. creating an array whose elements are all pairs whose first element is a string — in this case, the initializer list
   constructor would create an object, taking the first elements as keys
-2. creating an empty array -- passing the empty initializer list to the initializer list constructor yields an empty
+2. creating an empty array — passing the empty initializer list to the initializer list constructor yields an empty
   object

 ## Examples
@@ -69,10 +69,12 @@ Arrays are stored as pointers in a `basic_json` type. That is, for any access to

 ## See also

- [object_t](object_t.md) the type used to store JSON objects
- [binary_t](binary_t.md) the type used to store binary values
- [is_array](is_array.md) checks whether the JSON value is an array
- [max_size](max_size.md) returns the maximum possible number of elements
+- [`object_t`](object_t.md) - the type used to store JSON objects
+- [`binary_t`](binary_t.md) - the type used to store binary values
+- [`is_array`](is_array.md) - checks whether the JSON value is an array
+- [`max_size`](max_size.md) - returns the maximum possible number of elements
+- [Types](../../features/types/index.md) - how arrays are stored
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `ArrayType` template parameter

 ## Version history

@@ -46,7 +46,8 @@ The function is equivalent to `static_cast<json_base_class_t&>(j)` (or `static_c

 ## See also

- [json_base_class_t](json_base_class_t.md) - type of the custom base class
+- [`json_base_class_t`](json_base_class_t.md) - type of the custom base class
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `CustomBaseClass` template parameter

 ## Version history

@@ -90,7 +90,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Constant.
 2. Logarithmic in the size of the container.
 3. Logarithmic in the size of the container.
-4. Logarithmic in the size of the container.
+4. Linear in the number of reference tokens of `ptr`; for each of them, logarithmic in the size of the object, or
+   constant for an array.

 ## Notes

@@ -230,10 +231,12 @@ Strong exception safety: if an exception occurs, the original value stays intact

 ## See also

- documentation on [checked access](../../features/element_access/checked_access.md)
- [`operator[]`](operator%5B%5D.md) for unchecked access by reference
- [`value`](value.md) for access with default value
- [basic_json_view::at](../basic_json_view/at.md) - the same access on a zero-copy view
+- [Checked access](../../features/element_access/checked_access.md) - element access with range checking
+- [`operator[]`](operator%5B%5D.md) - unchecked access by reference
+- [`value`](value.md) - access with default value
+- [`basic_json_view::at`](../basic_json_view/at.md) - the same access on a zero-copy view
+- [Element Access](../../features/element_access/index.md) - overview of all ways to access elements
+- [JSON Pointer](../../features/json_pointer.md) - access nested values with a pointer

 ## Version history

@@ -57,8 +57,9 @@ Constant.

 ## See also

- [front](front.md) to access the first element
- [basic_json_view::back](../basic_json_view/back.md) - the same access on a zero-copy view
+- [`front`](front.md) - to access the first element
+- [`basic_json_view::back`](../basic_json_view/back.md) - the same access on a zero-copy view
+- [Element Access](../../features/element_access/index.md) - overview of all ways to access elements

 ## Version history

@@ -52,7 +52,7 @@ basic_json(basic_json&& other) noexcept;
    The postcondition of this constructor can be restored by calling [`clear()`](clear.md).

 2. Create a `#!json null` JSON value. It either takes a null pointer as parameter (explicitly creating `#!json null`)
-   or no parameter (implicitly creating `#!json null`). The passed null pointer itself is not read -- it is only used to
+   or no parameter (implicitly creating `#!json null`). The passed null pointer itself is not read — it is only used to
   choose the right constructor.

 3. This is a "catch all" constructor for all compatible JSON types; that is, types for which a `to_json()` method
@@ -113,19 +113,22 @@ basic_json(basic_json&& other) noexcept;

    ```mermaid
    flowchart TD
-        A(["initializer_list init"]) --> B{"empty, or every element is a 2-element<br/>array whose first element is a string?"}
-        B -->|"yes"| C{"type_deduction"}
-        B -->|"no"| D{"type_deduction"}
+        A(["initializer_list init"]) --> B{{"empty, or every element is a 2-element<br/>array whose first element is a string?"}}
+        B -->|"yes"| C{{"type_deduction"}}
+        B -->|"no"| D{{"type_deduction"}}
        C -->|"true"| OBJ["create object"]
-        C -->|"false"| E{"manual_type"}
+        C -->|"false"| E{{"manual_type"}}
        E -->|"object"| OBJ
        E -->|"array"| ARR["create array"]
        D -->|"true"| ARR
-        D -->|"false"| F{"manual_type"}
+        D -->|"false"| F{{"manual_type"}}
        F -->|"array"| ARR
        F -->|"object"| ERR["throw type_error.301"]
    ```

+    <p class="nj-caption" markdown>Decision flow for an initializer list: hexagons are checks, edge labels are their
+    outcomes, and rectangles are the resulting value or exception.</p>
+
    The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:
    
    1. The empty initializer list is written as `#!cpp {}` which is exactly an empty JSON object.
@@ -473,12 +476,13 @@ basic_json(basic_json&& other) noexcept;

 ## See also

- [array](array.md) create a JSON array value, forcing array creation from an initializer list even when it looks like
+- [`array`](array.md) - create a JSON array value, forcing array creation from an initializer list even when it looks like
  an object
- [object](object.md) create a JSON object value, forcing object creation from an initializer list
- [binary](binary.md) create a JSON binary array value
- [operator=](operator=.md) copy assignment operator
+- [`object`](object.md) - create a JSON object value, forcing object creation from an initializer list
+- [`binary`](binary.md) - create a JSON binary array value
+- [`operator=`](operator=.md) - copy assignment operator
 - [Creating JSON values](../../features/creating_values.md) - the article on creating JSON values
+- [Converting values](../../features/conversions.md) - which C++ types can be converted

 ## Version history

@@ -7,7 +7,12 @@ const_iterator begin() const noexcept;

 Returns an iterator to the first element.

-![Illustration from cppreference.com](../../images/range-begin-end.svg)
+<div class="nj-fig-wrap" markdown>
+--8<-- "images/range-begin-end.svg"
+</div>
+
+<p class="nj-caption" markdown>`begin()` points to the first element and `end()` to the position after the last element;
+the dashed cell is the past-the-last position, which must not be dereferenced.</p>

 ## Return value

@@ -39,12 +44,12 @@ Constant.

 ## See also

- [end](end.md) returns an iterator to one past the last element
- [cbegin](cbegin.md) returns a const iterator to the first element
- [rbegin](rbegin.md) returns a reverse iterator to the last element
- [items](items.md) returns an iteration proxy to access keys and values during range-based for loops
+- [`end`](end.md) - returns an iterator to one past the last element
+- [`cbegin`](cbegin.md) - returns a const iterator to the first element
+- [`rbegin`](rbegin.md) - returns a reverse iterator to the last element
+- [`items`](items.md) - returns an iteration proxy to access keys and values during range-based for loops
 - [Iterators](../../features/iterators.md) - the article on iterators
- [basic_json_view::begin](../basic_json_view/begin.md) - the same iteration on a zero-copy view (in document order,
+- [`basic_json_view::begin`](../basic_json_view/begin.md) - the same iteration on a zero-copy view (in document order,
  not sorted by key)

 ## Version history
@@ -63,10 +63,11 @@ initialization of a binary array type, for backwards compatibility and so it doe

 ## See also

- [binary_t](binary_t.md) type for binary values
- [get_binary](get_binary.md) get a reference to the stored binary value
- [is_binary](is_binary.md) return whether the value is binary
- [byte_container_with_subtype](../byte_container_with_subtype/index.md) container for binary values with subtype
+- [Binary formats](../../features/binary_formats/index.md) - formats that can store binary values
+- [`binary_t`](binary_t.md) - type for binary values
+- [`get_binary`](get_binary.md) - get a reference to the stored binary value
+- [`is_binary`](is_binary.md) - return whether the value is binary
+- [`byte_container_with_subtype`](../byte_container_with_subtype/index.md) - container for binary values with subtype
 - [Binary Values](../../features/binary_values.md) - the article on binary values

 ## Version history
@@ -41,7 +41,7 @@ represent a byte array in modern C++.
    [`byte_container_with_subtype`](../byte_container_with_subtype/index.md) derives directly from it. Its
    `value_type` must additionally be exactly one byte wide (e.g., `std::uint8_t`/`char`/`std::byte`): the binary
    serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via
-    `reinterpret_cast`, which is only correct for byte-sized elements -- a container like
+    `reinterpret_cast`, which is only correct for byte-sized elements — a container like
    `#!cpp std::vector<std::intptr_t>` will not work as `BinaryType`. The elements must be stored contiguously, and
    the binary readers additionally require `resize()` and `operator[]`. See
    [Template Parameter Requirements](../../features/types/template_parameters.md#binarytype) for the full list.
@@ -118,7 +118,9 @@ type `#!cpp binary_t*` must be dereferenced.

 ## See also

- [byte_container_with_subtype](../byte_container_with_subtype/index.md)
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [Binary formats](../../features/binary_formats/index.md) - formats that can store binary values
+- [`byte_container_with_subtype`](../byte_container_with_subtype/index.md) - container type used by binary values

 ## Version history

@@ -47,7 +47,9 @@ Boolean values are stored directly inside a `basic_json` type.

 ## See also

- [is_boolean](is_boolean.md) checks whether the JSON value is a boolean
+- [`is_boolean`](is_boolean.md) - checks whether the JSON value is a boolean
+- [Types](../../features/types/index.md) - how booleans are stored
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `BooleanType` template parameter

 ## Version history

@@ -6,7 +6,12 @@ const_iterator cbegin() const noexcept;

 Returns an iterator to the first element.

-![Illustration from cppreference.com](../../images/range-begin-end.svg)
+<div class="nj-fig-wrap" markdown>
+--8<-- "images/range-begin-end.svg"
+</div>
+
+<p class="nj-caption" markdown>`cbegin()` points to the first element, like `begin()`, and `end()` to the position after
+the last element; the dashed cell is the past-the-last position, which must not be dereferenced.</p>

 ## Return value

@@ -38,11 +43,11 @@ Constant.

 ## See also

- [begin](begin.md) returns an iterator to the first element
- [cend](cend.md) returns a const iterator to one past the last element
- [crbegin](crbegin.md) returns a const reverse iterator to the last element
+- [`begin`](begin.md) - returns an iterator to the first element
+- [`cend`](cend.md) - returns a const iterator to one past the last element
+- [`crbegin`](crbegin.md) - returns a const reverse iterator to the last element
 - [Iterators](../../features/iterators.md) - the article on iterators
- [basic_json_view::cbegin](../basic_json_view/cbegin.md) - the same iteration on a zero-copy view
+- [`basic_json_view::cbegin`](../basic_json_view/cbegin.md) - the same iteration on a zero-copy view

 ## Version history

@@ -42,8 +42,9 @@ store

 ## See also

- [from_cbor](from_cbor.md) deserializes a JSON value from CBOR
- [input_format_t](input_format_t.md) the enumeration of supported input formats
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [`from_cbor`](from_cbor.md) - deserializes a JSON value from CBOR
+- [`input_format_t`](input_format_t.md) - the enumeration of supported input formats
 - [CBOR](../../features/binary_formats/cbor.md) - the article on the CBOR format

 ## Version history
@@ -6,7 +6,12 @@ const_iterator cend() const noexcept;

 Returns an iterator to one past the last element.

-![Illustration from cppreference.com](../../images/range-begin-end.svg)
+<div class="nj-fig-wrap" markdown>
+--8<-- "images/range-begin-end.svg"
+</div>
+
+<p class="nj-caption" markdown>`cend()` points to the position after the last element, like `end()`, and `begin()` to
+the first element; the dashed cell is the past-the-last position, which must not be dereferenced.</p>

 ## Return value

@@ -38,11 +43,11 @@ Constant.

 ## See also

- [end](end.md) returns an iterator to one past the last element
- [cbegin](cbegin.md) returns a const iterator to the first element
- [crend](crend.md) returns a const reverse iterator to one before the first element
+- [`end`](end.md) - returns an iterator to one past the last element
+- [`cbegin`](cbegin.md) - returns a const iterator to the first element
+- [`crend`](crend.md) - returns a const reverse iterator to one before the first element
 - [Iterators](../../features/iterators.md) - the article on iterators
- [basic_json_view::cend](../basic_json_view/cend.md) - the same iteration on a zero-copy view
+- [`basic_json_view::cend`](../basic_json_view/cend.md) - the same iteration on a zero-copy view

 ## Version history

@@ -54,8 +54,9 @@ All iterators, pointers, and references related to this container are invalidate

 ## See also

- [erase](erase.md) removes elements from a JSON value
- [empty](empty.md) checks whether the JSON value has no elements
+- [`erase`](erase.md) - removes elements from a JSON value
+- [`empty`](empty.md) - checks whether the JSON value has no elements
+- [Modifying values](../../features/modifying_values.md) - the article on modifying values

 ## Version history

@@ -141,9 +141,10 @@ Strong exception safety: if an exception occurs, the original value stays intact

 ## See also

- [find](find.md) find a value in an object
- [count](count.md) returns the number of occurrences of a key
- [basic_json_view::contains](../basic_json_view/contains.md) - the same check on a zero-copy view
+- [`find`](find.md) - find a value in an object
+- [`count`](count.md) - returns the number of occurrences of a key
+- [`basic_json_view::contains`](../basic_json_view/contains.md) - the same check on a zero-copy view
+- [Element Access](../../features/element_access/index.md#does-this-key-exist) - how to test whether a key exists

 ## Version history

@@ -85,9 +85,10 @@ Logarithmic in the size of the JSON object.

 ## See also

- [find](find.md) find a value in an object
- [contains](contains.md) checks whether a key exists
- [basic_json_view::count](../basic_json_view/count.md) - the same check on a zero-copy view
+- [`find`](find.md) - find a value in an object
+- [`contains`](contains.md) - checks whether a key exists
+- [`basic_json_view::count`](../basic_json_view/count.md) - the same check on a zero-copy view
+- [Element Access](../../features/element_access/index.md#does-this-key-exist) - how to test whether a key exists

 ## Version history

@@ -6,7 +6,13 @@ const_reverse_iterator crbegin() const noexcept;

 Returns an iterator to the reverse-beginning; that is, the last element.

-![Illustration from cppreference.com](../../images/range-rbegin-rend.svg)
+<div class="nj-fig-wrap" markdown>
+--8<-- "images/range-rbegin-rend.svg"
+</div>
+
+<p class="nj-caption" markdown>`crbegin()` points to the last element, like `rbegin()`, and `rend()` to the position
+before the first element. The upper row is the reversed sequence and the lower row the forward sequence; dashed arrows
+link each reverse iterator to the forward iterator it stores, and dashed cells are past-the-last positions.</p>

 ## Return value

@@ -38,9 +44,9 @@ Constant.

 ## See also

- [crend](crend.md) returns a const reverse iterator to one before the first element
- [rbegin](rbegin.md) returns a reverse iterator to the last element
- [cbegin](cbegin.md) returns a const iterator to the first element
+- [`crend`](crend.md) - returns a const reverse iterator to one before the first element
+- [`rbegin`](rbegin.md) - returns a reverse iterator to the last element
+- [`cbegin`](cbegin.md) - returns a const iterator to the first element
 - [Iterators](../../features/iterators.md) - the article on iterators

 ## Version history
@@ -7,7 +7,13 @@ const_reverse_iterator crend() const noexcept;
 Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder,
 attempting to access it results in undefined behavior.

-![Illustration from cppreference.com](../../images/range-rbegin-rend.svg)
+<div class="nj-fig-wrap" markdown>
+--8<-- "images/range-rbegin-rend.svg"
+</div>
+
+<p class="nj-caption" markdown>`crend()` points to the position before the first element, like `rend()`, and `rbegin()`
+to the last element. The upper row is the reversed sequence and the lower row the forward sequence; dashed arrows link
+each reverse iterator to the forward iterator it stores, and dashed cells are past-the-last positions.</p>

 ## Return value

@@ -39,9 +45,9 @@ Constant.

 ## See also

- [crbegin](crbegin.md) returns a const reverse iterator to the last element
- [rend](rend.md) returns a reverse iterator to one before the first element
- [cend](cend.md) returns a const iterator to one past the last element
+- [`crbegin`](crbegin.md) - returns a const reverse iterator to the last element
+- [`rend`](rend.md) - returns a reverse iterator to one before the first element
+- [`cend`](cend.md) - returns a const iterator to one past the last element
 - [Iterators](../../features/iterators.md) - the article on iterators

 ## Version history
@@ -32,8 +32,10 @@ The actual comparator used depends on [`object_t`](object_t.md) and can be obtai

 ## See also

- [object_comparator_t](object_comparator_t.md) the comparator actually used by `object_t`
- [object_t](object_t.md) the type used to store JSON objects
+- [`object_comparator_t`](object_comparator_t.md) - the comparator actually used by `object_t`
+- [`object_t`](object_t.md) - the type used to store JSON objects
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `ObjectType` template parameter
+- [Object order](../../features/object_order.md) - preserve the insertion order of keys

 ## Version history

@@ -19,9 +19,10 @@ The equality holds up to [`operator==`](operator_eq.md), so it has the following
 - A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and
  to [discarded](is_discarded.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is
  serialized as `#!json null`, so a patch that was dumped and parsed again would set `#!json null`.
- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`,
-  `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `#!json []`. The patched value is then
-  the `source` and keeps its number type.
+- Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is
+  negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and
+  `diff(0.0, -0.0)` (positive and negative zero) all return `#!json []`. The patched value is then the `source` and
+  keeps its number type and sign.

 ## Parameters

@@ -92,11 +93,12 @@ operations times the length of their paths, so a small change deep inside a valu

 ## See also

- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
- [patch](patch.md) applies a JSON Patch
- [patch_inplace](patch_inplace.md) applies a JSON Patch in place
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
- [merge_diff](merge_diff.md) creates a diff as a JSON Merge Patch
+- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902) - specification of JSON Patch
+- [`patch`](patch.md) - applies a JSON Patch
+- [`patch_inplace`](patch_inplace.md) - applies a JSON Patch in place
+- [`merge_patch`](merge_patch.md) - applies a JSON Merge Patch
+- [`merge_diff`](merge_diff.md) - creates a diff as a JSON Merge Patch
+- [JSON Patch and Diff](../../features/json_patch.md) - the article on JSON Patch

 ## Version history

@@ -89,9 +89,9 @@ Binary values are serialized as an object containing two keys:

 ## See also

- [to_string](to_string.md) returns a string representation of a JSON value
- [operator<<](../operator_ltlt.md) serialize to stream
- [`basic_json_view::dump`](../basic_json_view/dump.md) the corresponding function of `basic_json_view`, serializing
+- [`to_string`](to_string.md) - returns a string representation of a JSON value
+- [`operator<<`](../operator_ltlt.md) - serialize to stream
+- [`basic_json_view::dump`](../basic_json_view/dump.md) - the corresponding function of `basic_json_view`, serializing
  directly from a flat index without building a `basic_json` value
 - [Serialization](../../features/serialization.md) - the serialization article

@@ -63,8 +63,8 @@ Logarithmic in the size of the container, O(log(`size()`)).

 ## See also

- [emplace_back](emplace_back.md) add a value to an array
- [insert](insert.md) add values to an array/object
+- [`emplace_back`](emplace_back.md) - add a value to an array
+- [`insert`](insert.md) - add values to an array/object
 - [Modifying values](../../features/modifying_values.md) - the article on modifying values

 ## Version history
@@ -61,8 +61,8 @@ Amortized constant.

 ## See also

- [operator+=](operator+=.md) add a value to an array/object
- [push_back](push_back.md) add a value to an array/object
+- [`operator+=`](operator+=.md) - add a value to an array/object
+- [`push_back`](push_back.md) - add a value to an array/object
 - [Modifying values](../../features/modifying_values.md) - the article on modifying values

 ## Version history
@@ -41,7 +41,7 @@ bool empty() const noexcept

 ## Notes

-This function does not return whether a string stored as JSON value is empty -- it returns whether the JSON container
+This function does not return whether a string stored as JSON value is empty — it returns whether the JSON container
 itself is empty which is `#!cpp false` in the case of a string.

 ## Examples
@@ -62,9 +62,9 @@ itself is empty which is `#!cpp false` in the case of a string.

 ## See also

- [size](size.md) returns the number of elements
- [clear](clear.md) clears the content and resets the value to the default value
- [basic_json_view::empty](../basic_json_view/empty.md) - the same check on a zero-copy view
+- [`size`](size.md) - returns the number of elements
+- [`clear`](clear.md) - clears the content and resets the value to the default value
+- [`basic_json_view::empty`](../basic_json_view/empty.md) - the same check on a zero-copy view

 ## Version history

@@ -7,7 +7,12 @@ const_iterator end() const noexcept;

 Returns an iterator to one past the last element.

-![Illustration from cppreference.com](../../images/range-begin-end.svg)
+<div class="nj-fig-wrap" markdown>
+--8<-- "images/range-begin-end.svg"
+</div>
+
+<p class="nj-caption" markdown>`end()` points to the position after the last element and `begin()` to the first element;
+the dashed cell is the past-the-last position, which must not be dereferenced.</p>

 ## Return value

@@ -39,11 +44,11 @@ Constant.

 ## See also

- [begin](begin.md) returns an iterator to the first element
- [cend](cend.md) returns a const iterator to one past the last element
- [rend](rend.md) returns a reverse iterator to one before the first element
+- [`begin`](begin.md) - returns an iterator to the first element
+- [`cend`](cend.md) - returns a const iterator to one past the last element
+- [`rend`](rend.md) - returns a reverse iterator to one before the first element
 - [Iterators](../../features/iterators.md) - the article on iterators
- [basic_json_view::end](../basic_json_view/end.md) - the same iteration on a zero-copy view
+- [`basic_json_view::end`](../basic_json_view/end.md) - the same iteration on a zero-copy view

 ## Version history

@@ -60,8 +60,9 @@ Constant.

 ## See also

- [start_pos](start_pos.md) to access the start position
- [JSON_DIAGNOSTIC_POSITIONS](../macros/json_diagnostic_positions.md) for an overview of the diagnostic positions
+- [`start_pos`](start_pos.md) - to access the start position
+- [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) - overview of the supported conversions
+- [Parsing and Exceptions](../../features/parsing/parse_exceptions.md) - handling parse errors and locating them in the input

 ## Version history

@@ -204,8 +204,8 @@ Strong exception safety: if an exception occurs, the original value stays intact

 ## See also

- [clear](clear.md) clears the contents
- [insert](insert.md) add values to an array/object
+- [`clear`](clear.md) - clears the contents
+- [`insert`](insert.md) - add values to an array/object
 - [Modifying values](../../features/modifying_values.md) - the article on modifying values

 ## Version history
@@ -61,7 +61,7 @@ keep

 ## See also

- [dump](dump.md) serializes a JSON value, with an `error_handler_t` parameter to configure invalid UTF-8 handling
+- [`dump`](dump.md) - serializes a JSON value, with an `error_handler_t` parameter to configure invalid UTF-8 handling
 - [Handling invalid UTF-8](../../features/serialization.md#handling-invalid-utf-8) - the article on handling invalid UTF-8

 ## Version history
@@ -40,6 +40,9 @@ classDiagram
    style json_exception fill:#CCCCFF
 ```

+<p class="nj-caption" markdown>Class hierarchy of the library's exceptions; arrows point from a derived class to its
+base class, and the highlighted box is `basic_json::exception`.</p>
+
 Subclasses:

 - [`parse_error`](parse_error.md) for exceptions indicating a parse error
@@ -80,7 +83,11 @@ constructor.

 ## See also

-[List of exceptions](../../home/exceptions.md)
+- [List of exceptions](../../home/exceptions.md) - overview of all exceptions thrown by the library
+- [Working Without Exceptions](../../features/no_exceptions.md) - using the library without exceptions
+- [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) - extended exception messages with the path of the failing value
+- [Parsing and Exceptions](../../features/parsing/parse_exceptions.md) - parsing alternatives that do not throw
+- [Debugging](../../home/debugging.md) - debugging aids

 ## Version history

@@ -91,10 +91,11 @@ Logarithmic in the size of the JSON object.

 ## See also

- [count](count.md) returns the number of occurrences of a key
- [contains](contains.md) checks whether a key exists
- [basic_json_view::find](../basic_json_view/find.md) - the same lookup on a zero-copy view (a duplicate key resolves
+- [`count`](count.md) - returns the number of occurrences of a key
+- [`contains`](contains.md) - checks whether a key exists
+- [`basic_json_view::find`](../basic_json_view/find.md) - the same lookup on a zero-copy view (a duplicate key resolves
  to the first member, whereas `parse()` keeps the last)
+- [Element Access](../../features/element_access/index.md#does-this-key-exist) - how to test whether a key exists

 ## Version history

@@ -58,7 +58,8 @@ Empty objects and arrays are flattened to `#!json null` and will not be reconstr

 ## See also

- [unflatten](unflatten.md) the reverse function
+- [`unflatten`](unflatten.md) - the reverse function
+- [JSON Pointer](../../features/json_pointer.md#flatten-unflatten) - the article on JSON Pointer and flattening

 ## Version history

@@ -86,8 +86,8 @@ std::string format_as(const BasicJsonType& j)

 ## See also

- [dump](dump.md)
- [std::formatter<basic_json>](std_formatter.md) - the `std::format` (C++20) equivalent
+- [`dump`](dump.md) - serialize a JSON value to a string
+- [`std::formatter<basic_json>`](std_formatter.md) - the `std::format` (C++20) equivalent
 - [Serialization](../../features/serialization.md) - the serialization article

 ## Version history
@@ -110,12 +110,16 @@ Linear in the size of the input.

 ## See also

- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
- [from_bon8](from_bon8.md) create a JSON value from an input in BON8 format
+- [BJData](../../features/binary_formats/bjdata.md) - the format, its byte layout and how values are mapped
+- [Binary formats](../../features/binary_formats/index.md) - overview and comparison of the supported binary formats
+- [Parsing untrusted input](../../features/parsing/untrusted_input.md) - limits and safe handling of hostile data
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [`to_bjdata`](to_bjdata.md) - create a BJData serialization of a JSON value
+- [`from_cbor`](from_cbor.md) - create a JSON value from an input in CBOR format
+- [`from_msgpack`](from_msgpack.md) - create a JSON value from an input in MessagePack format
+- [`from_bson`](from_bson.md) - create a JSON value from an input in BSON format
+- [`from_ubjson`](from_ubjson.md) - create a JSON value from an input in UBJSON format
+- [`from_bon8`](from_bon8.md) - create a JSON value from an input in BON8 format

 ## Version history

@@ -101,12 +101,15 @@ Linear in the size of the input.

 ## See also

- [to_bon8](to_bon8.md) create a BON8 serialization of a JSON value
- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
+- [BON8](../../features/binary_formats/bon8.md) - the format, its byte layout and how values are mapped
+- [Binary formats](../../features/binary_formats/index.md) - overview and comparison of the supported binary formats
+- [Parsing untrusted input](../../features/parsing/untrusted_input.md) - limits and safe handling of hostile data
+- [`to_bon8`](to_bon8.md) - create a BON8 serialization of a JSON value
+- [`from_cbor`](from_cbor.md) - create a JSON value from an input in CBOR format
+- [`from_msgpack`](from_msgpack.md) - create a JSON value from an input in MessagePack format
+- [`from_bson`](from_bson.md) - create a JSON value from an input in BSON format
+- [`from_ubjson`](from_ubjson.md) - create a JSON value from an input in UBJSON format
+- [`from_bjdata`](from_bjdata.md) - create a JSON value from an input in BJData format

 ## Version history

@@ -109,13 +109,17 @@ Linear in the size of the input.

 ## See also

- [BSON specification](http://bsonspec.org/spec.html)
- [to_bson](to_bson.md) for the analogous serialization
- [from_cbor](from_cbor.md) for the related CBOR format
- [from_msgpack](from_msgpack.md) for the related MessagePack format
- [from_ubjson](from_ubjson.md) for the related UBJSON format
- [from_bjdata](from_bjdata.md) for the related BJData format
- [from_bon8](from_bon8.md) for the related BON8 format
+- [BSON](../../features/binary_formats/bson.md) - the format, its byte layout and how values are mapped
+- [Binary formats](../../features/binary_formats/index.md) - overview and comparison of the supported binary formats
+- [Parsing untrusted input](../../features/parsing/untrusted_input.md) - limits and safe handling of hostile data
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [BSON specification](http://bsonspec.org/spec.html) - specification of the BSON format
+- [`to_bson`](to_bson.md) - the analogous serialization
+- [`from_cbor`](from_cbor.md) - the related CBOR format
+- [`from_msgpack`](from_msgpack.md) - the related MessagePack format
+- [`from_ubjson`](from_ubjson.md) - the related UBJSON format
+- [`from_bjdata`](from_bjdata.md) - the related BJData format
+- [`from_bon8`](from_bon8.md) - the related BON8 format

 ## Version history

@@ -122,12 +122,16 @@ Linear in the size of the input.

 ## See also

- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
- [from_bon8](from_bon8.md) create a JSON value from an input in BON8 format
+- [CBOR](../../features/binary_formats/cbor.md) - the format, its byte layout and how values are mapped
+- [Binary formats](../../features/binary_formats/index.md) - overview and comparison of the supported binary formats
+- [Parsing untrusted input](../../features/parsing/untrusted_input.md) - limits and safe handling of hostile data
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [`to_cbor`](to_cbor.md) - create a CBOR serialization of a JSON value
+- [`from_msgpack`](from_msgpack.md) - create a JSON value from an input in MessagePack format
+- [`from_bson`](from_bson.md) - create a JSON value from an input in BSON format
+- [`from_ubjson`](from_ubjson.md) - create a JSON value from an input in UBJSON format
+- [`from_bjdata`](from_bjdata.md) - create a JSON value from an input in BJData format
+- [`from_bon8`](from_bon8.md) - create a JSON value from an input in BON8 format

 ## Version history

@@ -107,12 +107,16 @@ Linear in the size of the input.

 ## See also

- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
- [from_bon8](from_bon8.md) create a JSON value from an input in BON8 format
+- [MessagePack](../../features/binary_formats/messagepack.md) - the format, its byte layout and how values are mapped
+- [Binary formats](../../features/binary_formats/index.md) - overview and comparison of the supported binary formats
+- [Parsing untrusted input](../../features/parsing/untrusted_input.md) - limits and safe handling of hostile data
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [`to_msgpack`](to_msgpack.md) - create a MessagePack serialization of a JSON value
+- [`from_cbor`](from_cbor.md) - create a JSON value from an input in CBOR format
+- [`from_bson`](from_bson.md) - create a JSON value from an input in BSON format
+- [`from_ubjson`](from_ubjson.md) - create a JSON value from an input in UBJSON format
+- [`from_bjdata`](from_bjdata.md) - create a JSON value from an input in BJData format
+- [`from_bon8`](from_bon8.md) - create a JSON value from an input in BON8 format

 ## Version history

@@ -114,12 +114,16 @@ Linear in the size of the input.

 ## See also

- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
- [from_bon8](from_bon8.md) create a JSON value from an input in BON8 format
+- [UBJSON](../../features/binary_formats/ubjson.md) - the format, its byte layout and how values are mapped
+- [Binary formats](../../features/binary_formats/index.md) - overview and comparison of the supported binary formats
+- [Parsing untrusted input](../../features/parsing/untrusted_input.md) - limits and safe handling of hostile data
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [`to_ubjson`](to_ubjson.md) - create a UBJSON serialization of a JSON value
+- [`from_cbor`](from_cbor.md) - create a JSON value from an input in CBOR format
+- [`from_msgpack`](from_msgpack.md) - create a JSON value from an input in MessagePack format
+- [`from_bson`](from_bson.md) - create a JSON value from an input in BSON format
+- [`from_bjdata`](from_bjdata.md) - create a JSON value from an input in BJData format
+- [`from_bon8`](from_bon8.md) - create a JSON value from an input in BON8 format

 ## Version history

@@ -50,9 +50,10 @@ Constant.

 ## See also

- [back](back.md) to access the last element
- [basic_json_view::front](../basic_json_view/front.md) - the same access on a zero-copy view (document order, not
+- [`back`](back.md) - to access the last element
+- [`basic_json_view::front`](../basic_json_view/front.md) - the same access on a zero-copy view (document order, not
  sorted; duplicate keys are visited)
+- [Element Access](../../features/element_access/index.md) - overview of all ways to access elements

 ## Version history

@@ -178,13 +178,14 @@ overload (3).

 ## See also

- [get_to](get_to.md) convert and write into a passed value
- [get_ptr](get_ptr.md) get a pointer to the stored value
- [get_ref](get_ref.md) get a reference to the stored value
- [operator ValueType](operator_ValueType.md) get a value via implicit conversion
+- [`get_to`](get_to.md) - convert and write into a passed value
+- [`get_ptr`](get_ptr.md) - get a pointer to the stored value
+- [`get_ref`](get_ref.md) - get a reference to the stored value
+- [`operator ValueType`](operator_ValueType.md) - get a value via implicit conversion
 - [Converting values](../../features/conversions.md) - the type conversions article
- [basic_json_view::get](../basic_json_view/get.md) - the same conversion on a zero-copy view (many types are
+- [`basic_json_view::get`](../basic_json_view/get.md) - the same conversion on a zero-copy view (many types are
  converted without ever building a `basic_json` value)
+- [Arbitrary Type Conversions](../../features/arbitrary_types.md) - make your own types usable with `get`

 ## Version history

@@ -36,7 +36,7 @@ Constant.

 ## See also

- [basic_json](index.md#template-parameters) the class template, with `AllocatorType` as one of its template parameters
+- [`basic_json`](index.md#template-parameters) - the class template, with `AllocatorType` as one of its template parameters
 - [Template Parameter Requirements](../../features/types/template_parameters.md#allocatortype) - the requirements for `AllocatorType`

 ## Version history
@@ -42,8 +42,11 @@ Constant.

 ## See also

- [get](get.md) get a value (explicit conversion)
- [get_ref](get_ref.md) get a reference to the stored value
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [`binary`](binary.md) - create a binary value
+- [`is_binary`](is_binary.md) - check whether a value is binary
+- [`get`](get.md) - get a value (explicit conversion)
+- [`get_ref`](get_ref.md) - get a reference to the stored value

 ## Version history

@@ -86,7 +86,8 @@ Constant.

 ## See also

- [get_ref()](get_ref.md) get a reference value
+- [`get_ref()`](get_ref.md) - get a reference value
+- [Converting values](../../features/conversions.md) - getting values out, with or without copying

 ## Version history

@@ -60,9 +60,10 @@ Constant.

 ## See also

- [get_ptr()](get_ptr.md) get a pointer value
- [basic_json_view::get_string](../basic_json_view/get_string.md) - the closest counterpart on a zero-copy view: a
+- [`get_ptr()`](get_ptr.md) - get a pointer value
+- [`basic_json_view::get_string`](../basic_json_view/get_string.md) - the closest counterpart on a zero-copy view: a
  string without a copy, but as a view rather than a reference to a value that must already exist
+- [Converting values](../../features/conversions.md) - getting values out, with or without copying

 ## Version history

@@ -68,11 +68,12 @@ Depends on the `json_serializer<ValueType>::from_json()` implementation.

 ## See also

- [get](get.md) get a value (explicit conversion)
- [get_ref](get_ref.md) get a reference to the stored value
- [get_ptr](get_ptr.md) get a pointer to the stored value
+- [`get`](get.md) - get a value (explicit conversion)
+- [`get_ref`](get_ref.md) - get a reference to the stored value
+- [`get_ptr`](get_ptr.md) - get a pointer to the stored value
 - [Converting values](../../features/conversions.md) - the type conversions article
- [basic_json_view::get_to](../basic_json_view/get_to.md) - the same conversion on a zero-copy view
+- [`basic_json_view::get_to`](../basic_json_view/get_to.md) - the same conversion on a zero-copy view
+- [Arbitrary Type Conversions](../../features/arbitrary_types.md) - make your own types usable with `get_to`

 ## Version history

@@ -189,7 +189,7 @@ The class satisfies the following concept requirements:
 Functions to inspect the type of a JSON value.

 - [**type**](type.md) - return the type of the JSON value
- [**operator value_t**](operator_value_t.md) - return the type of the JSON value
+- [`operator value_t`](operator_value_t.md) - return the type of the JSON value
 - [**type_name**](type_name.md) - return the type as string
 - [**is_primitive**](is_primitive.md) - return whether the type is primitive
 - [**is_structured**](is_structured.md) - return whether the type is structured
@@ -218,7 +218,7 @@ Direct access to the stored value of a JSON value.
 - [**get_to**](get_to.md) - get a value and write it to a destination
 - [**get_ptr**](get_ptr.md) - get a pointer value
 - [**get_ref**](get_ref.md) - get a reference value
- [**operator ValueType**](operator_ValueType.md) - get a value
+- [`operator ValueType`](operator_ValueType.md) - get a value
 - [**get_binary**](get_binary.md) - get a binary value
 - [**as_base_class**](as_base_class.md) - access the custom base class

@@ -359,10 +359,15 @@ Access to the JSON value

 ## See also

- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
- [basic_json_document](../basic_json_document/index.md) / [basic_json_view](../basic_json_view/index.md) - parse a JSON
+- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259) -
+  specification of the JSON data interchange format
+- [`basic_json_document`](../basic_json_document/index.md) - / [`basic_json_view`](../basic_json_view/index.md) - parse a JSON
  text into a flat index and read it through a view
 - [Zero-copy JSON views](../../features/json_view.md) - when to use a document and a view instead of a `basic_json`
+- [Types](../../features/types/index.md) - how JSON values are stored and which types exist
+- [Converting values](../../features/conversions.md) - get values out of a JSON value and put values in
+- [Creating JSON values](../../features/creating_values.md) - all the ways to build a JSON value
+- [Arbitrary Type Conversions](../../features/arbitrary_types.md) - convert your own types to and from JSON

 ## Version history

@@ -53,8 +53,9 @@ bon8

 ## See also

- [sax_parse](sax_parse.md) generic SAX parse interface, taking an `input_format_t` to select the input format
- [cbor_tag_handler_t](cbor_tag_handler_t.md) configures how CBOR tags are treated while parsing
+- [`sax_parse`](sax_parse.md) - generic SAX parse interface, taking an `input_format_t` to select the input format
+- [`cbor_tag_handler_t`](cbor_tag_handler_t.md) - configures how CBOR tags are treated while parsing
+- [Binary Formats](../../features/binary_formats/index.md) - CBOR, MessagePack, BSON, and other formats

 ## Version history

@@ -185,10 +185,11 @@ Strong exception safety: if an exception occurs, the original value stays intact

 ## See also

- [emplace](emplace.md) add a value to an object
- [emplace_back](emplace_back.md) add a value to an array
- [push_back](push_back.md) add a value to an array/object
- [update](update.md) merges objects
+- [`emplace`](emplace.md) - add a value to an object
+- [`emplace_back`](emplace_back.md) - add a value to an array
+- [`push_back`](push_back.md) - add a value to an array/object
+- [`update`](update.md) - merges objects
+- [Modifying values](../../features/modifying_values.md) - the article on modifying values

 ## Version history

@@ -40,6 +40,9 @@ classDiagram
    style json_invalid_iterator fill:#CCCCFF
 ```

+<p class="nj-caption" markdown>Class hierarchy of the library's exceptions; arrows point from a derived class to its
+base class, and the highlighted box is `basic_json::invalid_iterator`.</p>
+
 ## Member functions

 - **what** - returns explanatory string
@@ -66,12 +69,14 @@ classDiagram

 ## See also

- [`exception`](exception.md) for the base class of all exceptions thrown by the library
- [List of iterator errors](../../home/exceptions.md#iterator-errors)
- [`parse_error`](parse_error.md) for exceptions indicating a parse error
- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
- [`other_error`](other_error.md) for exceptions indicating other library errors
+- [`exception`](exception.md) - the base class of all exceptions thrown by the library
+- [List of iterator errors](../../home/exceptions.md#iterator-errors) - overview of iterator errors (`invalid_iterator`)
+- [`parse_error`](parse_error.md) - exceptions indicating a parse error
+- [`type_error`](type_error.md) - exceptions indicating executing a member function with a wrong type
+- [`out_of_range`](out_of_range.md) - exceptions indicating access out of the defined range
+- [`other_error`](other_error.md) - exceptions indicating other library errors
+- [Exceptions](../../home/exceptions.md) - all exceptions and their error codes
+- [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) - extended exception messages with the path of the failing value

 ## Version history

@@ -36,11 +36,12 @@ Constant.

 ## See also

- [is_object](is_object.md) checks whether the JSON value is an object
- [is_structured](is_structured.md) checks whether the JSON value is structured (array or object)
- [type](type.md) returns the type of the JSON value
- [array_t](array_t.md) the type used to store JSON arrays
- [basic_json_view::is_array](../basic_json_view/is_array.md) - the same check on a zero-copy view
+- [`is_object`](is_object.md) - checks whether the JSON value is an object
+- [`is_structured`](is_structured.md) - checks whether the JSON value is structured (array or object)
+- [`type`](type.md) - returns the type of the JSON value
+- [`array_t`](array_t.md) - the type used to store JSON arrays
+- [`basic_json_view::is_array`](../basic_json_view/is_array.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored

 ## Version history

@@ -36,10 +36,11 @@ Constant.

 ## See also

- [is_primitive](is_primitive.md) checks whether the JSON value is primitive
- [binary_t](binary_t.md) the type used to store binary values
- [get_binary](get_binary.md) returns a reference to the stored binary value
- [basic_json_view::is_binary](../basic_json_view/is_binary.md) - the same check on a zero-copy view
+- [Binary values](../../features/binary_values.md) - how binary values and subtypes are handled
+- [`is_primitive`](is_primitive.md) - checks whether the JSON value is primitive
+- [`binary_t`](binary_t.md) - the type used to store binary values
+- [`get_binary`](get_binary.md) - returns a reference to the stored binary value
+- [`basic_json_view::is_binary`](../basic_json_view/is_binary.md) - the same check on a zero-copy view

 ## Version history

@@ -36,9 +36,10 @@ Constant.

 ## See also

- [boolean_t](boolean_t.md) the type used to store JSON booleans
- [is_primitive](is_primitive.md) checks whether the JSON value is primitive
- [basic_json_view::is_boolean](../basic_json_view/is_boolean.md) - the same check on a zero-copy view
+- [`boolean_t`](boolean_t.md) - the type used to store JSON booleans
+- [`is_primitive`](is_primitive.md) - checks whether the JSON value is primitive
+- [`basic_json_view::is_boolean`](../basic_json_view/is_boolean.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored

 ## Version history

@@ -87,8 +87,9 @@ with `allow_exceptions` set to `#!cpp false`: a parse error then yields a discar

 ## See also

- [basic_json_view::is_discarded](../basic_json_view/is_discarded.md) - the corresponding check on a zero-copy view,
+- [`basic_json_view::is_discarded`](../basic_json_view/is_discarded.md) - the corresponding check on a zero-copy view,
  which is `#!cpp true` if the view refers to no value
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored

 ## Version history

@@ -36,11 +36,12 @@ Constant.

 ## See also

- [is_array](is_array.md) checks whether the JSON value is an array
- [is_object](is_object.md) checks whether the JSON value is an object
- [type](type.md) returns the type of the JSON value
- [value_t](value_t.md) the enumeration of JSON types
- [basic_json_view::is_null](../basic_json_view/is_null.md) - the same check on a zero-copy view
+- [`is_array`](is_array.md) - checks whether the JSON value is an array
+- [`is_object`](is_object.md) - checks whether the JSON value is an object
+- [`type`](type.md) - returns the type of the JSON value
+- [`value_t`](value_t.md) - the enumeration of JSON types
+- [`basic_json_view::is_null`](../basic_json_view/is_null.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored

 ## Version history

@@ -46,10 +46,12 @@ constexpr bool is_number() const noexcept

 ## See also

- [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
- [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
- [is_number_float()](is_number_float.md) check if the value is a floating-point number
- [basic_json_view::is_number](../basic_json_view/is_number.md) - the same check on a zero-copy view
+- [`is_number_integer()`](is_number_integer.md) - check if the value is an integer or unsigned integer number
+- [`is_number_unsigned()`](is_number_unsigned.md) - check if the value is an unsigned integer number
+- [`is_number_float()`](is_number_float.md) - check if the value is a floating-point number
+- [`basic_json_view::is_number`](../basic_json_view/is_number.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored
+- [Number Handling](../../features/types/number_handling.md) - how numbers are stored and converted

 ## Version history

@@ -37,10 +37,12 @@ Constant.

 ## See also

- [is_number()](is_number.md) check if the value is a number
- [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
- [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
- [basic_json_view::is_number_float](../basic_json_view/is_number_float.md) - the same check on a zero-copy view
+- [`is_number()`](is_number.md) - check if the value is a number
+- [`is_number_integer()`](is_number_integer.md) - check if the value is an integer or unsigned integer number
+- [`is_number_unsigned()`](is_number_unsigned.md) - check if the value is an unsigned integer number
+- [`basic_json_view::is_number_float`](../basic_json_view/is_number_float.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored
+- [Number Handling](../../features/types/number_handling.md) - how numbers are stored and converted

 ## Version history

@@ -37,10 +37,12 @@ Constant.

 ## See also

- [is_number()](is_number.md) check if the value is a number
- [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
- [is_number_float()](is_number_float.md) check if the value is a floating-point number
- [basic_json_view::is_number_integer](../basic_json_view/is_number_integer.md) - the same check on a zero-copy view
+- [`is_number()`](is_number.md) - check if the value is a number
+- [`is_number_unsigned()`](is_number_unsigned.md) - check if the value is an unsigned integer number
+- [`is_number_float()`](is_number_float.md) - check if the value is a floating-point number
+- [`basic_json_view::is_number_integer`](../basic_json_view/is_number_integer.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored
+- [Number Handling](../../features/types/number_handling.md) - how numbers are stored and converted

 ## Version history

@@ -40,10 +40,12 @@ Constant.

 ## See also

- [is_number()](is_number.md) check if the value is a number
- [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
- [is_number_float()](is_number_float.md) check if the value is a floating-point number
- [basic_json_view::is_number_unsigned](../basic_json_view/is_number_unsigned.md) - the same check on a zero-copy view
+- [`is_number()`](is_number.md) - check if the value is a number
+- [`is_number_integer()`](is_number_integer.md) - check if the value is an integer or unsigned integer number
+- [`is_number_float()`](is_number_float.md) - check if the value is a floating-point number
+- [`basic_json_view::is_number_unsigned`](../basic_json_view/is_number_unsigned.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored
+- [Number Handling](../../features/types/number_handling.md) - how numbers are stored and converted

 ## Version history

@@ -36,11 +36,12 @@ Constant.

 ## See also

- [is_array](is_array.md) checks whether the JSON value is an array
- [is_structured](is_structured.md) checks whether the JSON value is structured (array or object)
- [type](type.md) returns the type of the JSON value
- [object_t](object_t.md) the type used to store JSON objects
- [basic_json_view::is_object](../basic_json_view/is_object.md) - the same check on a zero-copy view
+- [`is_array`](is_array.md) - checks whether the JSON value is an array
+- [`is_structured`](is_structured.md) - checks whether the JSON value is structured (array or object)
+- [`type`](type.md) - returns the type of the JSON value
+- [`object_t`](object_t.md) - the type used to store JSON objects
+- [`basic_json_view::is_object`](../basic_json_view/is_object.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored

 ## Version history

@@ -56,13 +56,14 @@ This library extends primitive types to binary types, because binary types are r

 ## See also

- [is_structured()](is_structured.md) returns whether the JSON value is structured
- [is_null()](is_null.md) returns whether the JSON value is `null`
- [is_string()](is_string.md) returns whether the JSON value is a string
- [is_boolean()](is_boolean.md) returns whether the JSON value is a boolean
- [is_number()](is_number.md) returns whether the JSON value is a number
- [is_binary()](is_binary.md) returns whether the JSON value is a binary array
- [basic_json_view::is_primitive](../basic_json_view/is_primitive.md) - the same check on a zero-copy view
+- [`is_structured()`](is_structured.md) - returns whether the JSON value is structured
+- [`is_null()`](is_null.md) - returns whether the JSON value is `null`
+- [`is_string()`](is_string.md) - returns whether the JSON value is a string
+- [`is_boolean()`](is_boolean.md) - returns whether the JSON value is a boolean
+- [`is_number()`](is_number.md) - returns whether the JSON value is a number
+- [`is_binary()`](is_binary.md) - returns whether the JSON value is a binary array
+- [`basic_json_view::is_primitive`](../basic_json_view/is_primitive.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored

 ## Version history

@@ -36,10 +36,11 @@ Constant.

 ## See also

- [is_primitive](is_primitive.md) checks whether the JSON value is primitive
- [type](type.md) returns the type of the JSON value
- [string_t](string_t.md) the type used to store JSON strings
- [basic_json_view::is_string](../basic_json_view/is_string.md) - the same check on a zero-copy view
+- [`is_primitive`](is_primitive.md) - checks whether the JSON value is primitive
+- [`type`](type.md) - returns the type of the JSON value
+- [`string_t`](string_t.md) - the type used to store JSON strings
+- [`basic_json_view::is_string`](../basic_json_view/is_string.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored

 ## Version history

@@ -54,10 +54,11 @@ Note that though strings are containers in C++, they are treated as primitive va

 ## See also

- [is_primitive()](is_primitive.md) returns whether JSON value is primitive
- [is_array()](is_array.md) returns whether the value is an array
- [is_object()](is_object.md) returns whether the value is an object
- [basic_json_view::is_structured](../basic_json_view/is_structured.md) - the same check on a zero-copy view
+- [`is_primitive()`](is_primitive.md) - returns whether JSON value is primitive
+- [`is_array()`](is_array.md) - returns whether the value is an array
+- [`is_object()`](is_object.md) - returns whether the value is an object
+- [`basic_json_view::is_structured`](../basic_json_view/is_structured.md) - the same check on a zero-copy view
+- [Types](../../features/types/index.md) - the JSON value types and how they are stored

 ## Version history

@@ -54,7 +54,7 @@ using element_type = decltype(*j_object.items().begin());
 ```

 The per-element type (`iteration_proxy_value`) lives in the library's internal `detail` namespace and is
-intentionally unspecified as a stable, named type -- `decltype` is the supported way to obtain it, but its exact
+intentionally unspecified as a stable, named type — `decltype` is the supported way to obtain it, but its exact
 name/definition may change between versions.

 ## Return value
@@ -97,10 +97,11 @@ When iterating over an array, `key()` will return the index of the element as st

 ## See also

- [begin](begin.md) returns an iterator to the first element
- [end](end.md) returns an iterator to one past the last element
- [basic_json_view::items](../basic_json_view/items.md) - the same range on a zero-copy view (`#!cpp const auto`,
+- [`begin`](begin.md) - returns an iterator to the first element
+- [`end`](end.md) - returns an iterator to one past the last element
+- [`basic_json_view::items`](../basic_json_view/items.md) - the same range on a zero-copy view (`#!cpp const auto`,
  not `#!cpp const auto&`: items are produced on the fly; document order, not sorted; duplicate keys are visited)
+- [Iterators](../../features/iterators.md#access-object-keys-during-iteration) - the article on iterating over keys and values

 ## Version history

@@ -57,7 +57,7 @@ same name. Hidden members remain accessible via [`as_base_class`](as_base_class.

 ## See also

- [as_base_class](as_base_class.md) - access the custom base class
+- [`as_base_class`](as_base_class.md) - access the custom base class
 - [Template Parameter Requirements](../../features/types/template_parameters.md#custombaseclass) - the requirements for `CustomBaseClass`

 ## Version history
@@ -44,10 +44,11 @@ deserializes. See [Template Parameter Requirements](../../features/types/templat

 ## See also

- [adl_serializer](../adl_serializer/index.md) the default `json_serializer`
- [get](get.md) explicit type conversion using the `json_serializer`'s `from_json()` method
- [get_to](get_to.md) explicit type conversion into a variable using the `json_serializer`'s `from_json()` method
+- [`adl_serializer`](../adl_serializer/index.md) - the default `json_serializer`
+- [`get`](get.md) - explicit type conversion using the `json_serializer`'s `from_json()` method
+- [`get_to`](get_to.md) - explicit type conversion into a variable using the `json_serializer`'s `from_json()` method
 - [Arbitrary Type Conversions](../../features/arbitrary_types.md) - the article on converting between JSON values and arbitrary types
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `JSONSerializer` template parameter

 ## Version history

@@ -33,7 +33,7 @@ constant complexity.

 ## Notes

-This function does not return the maximal length of a string stored as JSON value -- it returns the maximal number of
+This function does not return the maximal length of a string stored as JSON value — it returns the maximal number of
 string elements the JSON value can store which is `1`.

 ## Examples
@@ -56,9 +56,9 @@ string elements the JSON value can store which is `1`.

 ## See also

- [size](size.md) returns the number of elements
- [array_t](array_t.md) the type used to store JSON arrays
- [object_t](object_t.md) the type used to store JSON objects
+- [`size`](size.md) - returns the number of elements
+- [`array_t`](array_t.md) - the type used to store JSON arrays
+- [`object_t`](object_t.md) - the type used to store JSON objects

 ## Version history

@@ -70,9 +70,10 @@ object operation (looking up a key, or adding one to the patch): logarithmic for

 ## See also

- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396)
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
- [diff](diff.md) creates a diff as a JSON Patch
+- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396) - specification of JSON Merge Patch
+- [`merge_patch`](merge_patch.md) - applies a JSON Merge Patch
+- [`diff`](diff.md) - creates a diff as a JSON Patch
+- [JSON Merge Patch](../../features/merge_patch.md) - the article on JSON Merge Patch

 ## Version history

@@ -85,9 +85,10 @@ cost also includes one copy of `apply_patch` (see the notes below).

 ## See also

- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396)
- [patch](patch.md) apply a JSON patch
- [merge_diff](merge_diff.md) creates a diff as a JSON Merge Patch
+- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396) - specification of JSON Merge Patch
+- [`patch`](patch.md) - apply a JSON patch
+- [`merge_diff`](merge_diff.md) - creates a diff as a JSON Merge Patch
+- [JSON Merge Patch](../../features/merge_patch.md) - the article on JSON Merge Patch

 ## Version history

@@ -48,8 +48,11 @@ Constant.

 ## See also

- [**NLOHMANN_JSON_VERSION_MAJOR**/**NLOHMANN_JSON_VERSION_MINOR**/**NLOHMANN_JSON_VERSION_PATCH**](../macros/nlohmann_json_version_major.md)
-  \- library version information
+- [`NLOHMANN_JSON_VERSION_MAJOR`](../macros/nlohmann_json_version_major.md) /
+  [`NLOHMANN_JSON_VERSION_MINOR`](../macros/nlohmann_json_version_major.md) /
+  [`NLOHMANN_JSON_VERSION_PATCH`](../macros/nlohmann_json_version_major.md) - library version information
+- [Integration](../../integration/index.md) - integrate the library
+- [Supported Macros](../../features/macros.md) - guide to all supported macros

 ## Version history

@@ -84,10 +84,11 @@ Floating-point number values are stored directly inside a `basic_json` type.

 ## See also

- [number_integer_t](number_integer_t.md) the type used to store JSON integer numbers
- [number_unsigned_t](number_unsigned_t.md) the type used to store JSON unsigned integer numbers
- [is_number_float](is_number_float.md) checks whether the JSON value is a floating-point number
+- [`number_integer_t`](number_integer_t.md) - the type used to store JSON integer numbers
+- [`number_unsigned_t`](number_unsigned_t.md) - the type used to store JSON unsigned integer numbers
+- [`is_number_float`](is_number_float.md) - checks whether the JSON value is a floating-point number
 - [Number Handling](../../features/types/number_handling.md) - the article on number handling
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the number template parameters

 ## Version history

@@ -80,10 +80,11 @@ Integer number values are stored directly inside a `basic_json` type.

 ## See also

- [number_unsigned_t](number_unsigned_t.md) the type used to store JSON unsigned integer numbers
- [number_float_t](number_float_t.md) the type used to store JSON floating-point numbers
- [is_number_integer](is_number_integer.md) checks whether the JSON value is a signed integer number
+- [`number_unsigned_t`](number_unsigned_t.md) - the type used to store JSON unsigned integer numbers
+- [`number_float_t`](number_float_t.md) - the type used to store JSON floating-point numbers
+- [`is_number_integer`](is_number_integer.md) - checks whether the JSON value is a signed integer number
 - [Number Handling](../../features/types/number_handling.md) - the article on number handling
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the number template parameters

 ## Version history

@@ -82,10 +82,11 @@ Integer number values are stored directly inside a `basic_json` type.

 ## See also

- [number_integer_t](number_integer_t.md) the type used to store JSON integer numbers
- [number_float_t](number_float_t.md) the type used to store JSON floating-point numbers
- [is_number_unsigned](is_number_unsigned.md) checks whether the JSON value is an unsigned integer number
+- [`number_integer_t`](number_integer_t.md) - the type used to store JSON integer numbers
+- [`number_float_t`](number_float_t.md) - the type used to store JSON floating-point numbers
+- [`is_number_unsigned`](is_number_unsigned.md) - checks whether the JSON value is an unsigned integer number
 - [Number Handling](../../features/types/number_handling.md) - the article on number handling
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the number template parameters

 ## Version history

@@ -27,8 +27,10 @@ and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.

 ## See also

- [object_t](object_t.md) the type used to store JSON objects
- [default_object_comparator_t](default_object_comparator_t.md) the fallback comparator used when `object_t` has no `key_compare` member type
+- [`object_t`](object_t.md) - the type used to store JSON objects
+- [`default_object_comparator_t`](default_object_comparator_t.md) - the fallback comparator used when `object_t` has no `key_compare` member type
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `ObjectType` template parameter
+- [Object order](../../features/object_order.md) - preserve the insertion order of keys

 ## Version history

@@ -20,7 +20,7 @@ To store objects in C++, a type is defined by the template parameters described
 `ObjectType`
 :   the container to store objects. Its template parameters must have the same order and meaning as those of
    `std::map`; in particular, the third parameter is a comparator. `#!cpp std::unordered_map`, whose third parameter
-    is a hash function, therefore needs an adapter -- see
+    is a hash function, therefore needs an adapter — see
    [Template Parameter Requirements](../../features/types/template_parameters.md#objecttype) for the full list of
    requirements, an adapter example, and the containers that are known to work.

@@ -125,10 +125,12 @@ the object is silently converted as an array of key-value pairs, which is incorr

 ## See also

- [array_t](array_t.md) the type used to store JSON arrays
- [string_t](string_t.md) the type used to store JSON strings
- [object_comparator_t](object_comparator_t.md) the comparator used to order object keys
+- [`array_t`](array_t.md) - the type used to store JSON arrays
+- [`string_t`](string_t.md) - the type used to store JSON strings
+- [`object_comparator_t`](object_comparator_t.md) - the comparator used to order object keys
 - [Object Order](../../features/object_order.md) - the article on object key ordering
+- [Types](../../features/types/index.md) - how objects are stored
+- [Template Parameter Requirements](../../features/types/template_parameters.md) - requirements on the `ObjectType` template parameter

 ## Version history

@@ -123,8 +123,9 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se

 ## See also

- [emplace_back](emplace_back.md) add a value to an array
- [push_back](push_back.md) add a value to an array/object
+- [`emplace_back`](emplace_back.md) - add a value to an array
+- [`push_back`](push_back.md) - add a value to an array/object
+- [Modifying values](../../features/modifying_values.md) - the article on modifying values

 ## Version history

@@ -45,8 +45,9 @@ Linear.

 ## See also

- [basic_json](basic_json.md) create a JSON value
- [swap](swap.md) exchanges the contents of two JSON values
+- [`basic_json`](basic_json.md) - create a JSON value
+- [`swap`](swap.md) - exchanges the contents of two JSON values
+- [Creating JSON values](../../features/creating_values.md) - ways to create and assign JSON values

 ## Version history