From 7c9208bfb31b2cd04871d5fe306a0b9b8673e615 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Wed, 8 Jul 2026 20:18:24 +0200
Subject: [PATCH] :memo: make documentation more LLM friendly (#5244)

Implement the scoped agent-readiness subset for json.nlohmann.me:
- Add the mkdocs-llmstxt plugin to generate llms.txt from the nav
  (full_output/llms-full.txt deliberately omitted to avoid dumping
  500+ API reference pages into one giant file).
- Add a permissive robots.txt with a Sitemap reference.
- Add a build hook (hooks/copy_markdown_source.py) that copies each
  page's Markdown source into the built site as a `<path>.md` sibling
  of its HTML output, so agents/tools can fetch raw Markdown directly.

sitemap.xml was already emitted by default and needed no change.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---
 docs/mkdocs/docs/robots.txt               |  4 +++
 docs/mkdocs/hooks/copy_markdown_source.py | 25 +++++++++++++++++++
 docs/mkdocs/mkdocs.yml                    | 30 +++++++++++++++++++++++
 docs/mkdocs/requirements.txt              |  1 +
 4 files changed, 60 insertions(+)
 create mode 100644 docs/mkdocs/docs/robots.txt
 create mode 100644 docs/mkdocs/hooks/copy_markdown_source.py

diff --git a/docs/mkdocs/docs/robots.txt b/docs/mkdocs/docs/robots.txt
new file mode 100644
index 000000000..f52a66807
--- /dev/null
+++ b/docs/mkdocs/docs/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://json.nlohmann.me/sitemap.xml
diff --git a/docs/mkdocs/hooks/copy_markdown_source.py b/docs/mkdocs/hooks/copy_markdown_source.py
new file mode 100644
index 000000000..dfdd9cc7b
--- /dev/null
+++ b/docs/mkdocs/hooks/copy_markdown_source.py
@@ -0,0 +1,25 @@
+"""Copy each documentation page's Markdown source into the built site."""
+
+# Creates a `<path>.md` sibling of each HTML output (for example,
+# `features/comments/` becomes `features/comments.md`) so agents and tools can
+# fetch the raw Markdown directly instead of parsing rendered HTML.
+
+import os
+import shutil
+
+_pages = []
+
+
+def on_files(files, config):
+    global _pages
+    _pages = [f for f in files if f.is_documentation_page()]
+    return files
+
+
+def on_post_build(config):
+    site_dir = config["site_dir"]
+    for file in _pages:
+        url = file.url.rstrip("/")
+        target = os.path.join(site_dir, (url or "index") + ".md")
+        os.makedirs(os.path.dirname(target), exist_ok=True)
+        shutil.copyfile(file.abs_src_path, target)
diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml
index 7f68ea548..721b8e0b2 100644
--- a/docs/mkdocs/mkdocs.yml
+++ b/docs/mkdocs/mkdocs.yml
@@ -367,6 +367,9 @@ markdown_extensions:
       auto_append:
         - ../includes/glossary.md
 
+hooks:
+  - hooks/copy_markdown_source.py
+
 plugins:
   - search:
       separator: '[\s\-\.]'
@@ -389,6 +392,33 @@ plugins:
         - https://nlohmann.github.io/json/*
         - mailto:*
   - privacy
+  - llmstxt:
+      markdown_description: >
+        JSON for Modern C++ is a C++11 header-only library implementing a JSON
+        value type with an STL-like API, JSON Pointer/Patch, CBOR/MessagePack/
+        BSON/UBJSON/BJData binary format support, and a SAX-style parser interface.
+      sections:
+        Home:
+          - index.md
+          - home/*.md
+        Features:
+          - features/*.md
+          - features/binary_formats/*.md
+          - features/element_access/*.md
+          - features/parsing/*.md
+          - features/types/*.md
+        Integration:
+          - integration/*.md
+        API Documentation:
+          - api/*.md
+          - api/basic_json/*.md
+          - api/adl_serializer/*.md
+          - api/byte_container_with_subtype/*.md
+          - api/json_pointer/*.md
+          - api/json_sax/*.md
+          - api/macros/*.md
+        Community:
+          - community/*.md
 
 extra_css:
   - css/custom.css
diff --git a/docs/mkdocs/requirements.txt b/docs/mkdocs/requirements.txt
index 6327a70d6..0ea5cb0fd 100644
--- a/docs/mkdocs/requirements.txt
+++ b/docs/mkdocs/requirements.txt
@@ -7,5 +7,6 @@ mkdocs-material-extensions==1.3.1                   # extensions
 mkdocs-minify-plugin==0.8.0                         # plugin "minify"
 mkdocs-redirects==1.2.3                             # plugin "redirects"
 mkdocs-htmlproofer-plugin==1.5.0                    # plugin "htmlproofer"
+mkdocs-llmstxt==0.5.0                               # plugin "llmstxt"
 
 PyYAML==6.0.3                                       # linter