From 5f3464111c96f3458ba4bf15fc93ae542b76dd33 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Fri, 11 Sep 2026 11:45:08 +0200
Subject: [PATCH 1/3] feat: prepend anchors with version key

---
 pre_build.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/pre_build.py b/pre_build.py
index 1e931e27..17130dff 100644
--- a/pre_build.py
+++ b/pre_build.py
@@ -4,6 +4,7 @@
 from pathlib import Path
 import jsonc as json
 import logging
+from _version import __version__
 
 # Suppress warnings from json-schema-for-humans about unresolvable URLs
 logging.getLogger().setLevel(logging.ERROR)
@@ -51,7 +52,7 @@ def build_json_examples():
             for json_file in json_files:
                 print(f'Processing {json_file}...')
 
-                crossref = f"examples:{category}:{Path(json_file).stem}"
+                crossref = f"{__version__}:examples:{category}:{Path(json_file).stem}"
                 index_md += f"- [{Path(json_file).stem}](#{crossref})\n"
 
                 json_file_name = Path(json_file).stem
@@ -118,7 +119,7 @@ def build_json_schemas():
             # insert mySt cross-reference at top of markdown files
             with open(output_path_md, 'r', encoding='utf-8') as md_file:
                 md_content = md_file.read()
-            crossref = f"schemas:{Path(schema_file).stem}"
+            crossref = f"{__version__}:schemas:{Path(schema_file).stem}"
             md_content = f"""---
 author: ""
 ---

From 74a4efa72b11c67c257f787c1797d14c072fd151 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Fri, 11 Sep 2026 11:45:20 +0200
Subject: [PATCH 2/3] docs: exclude index.md from children pages

---
 myst.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/myst.yml b/myst.yml
index f4482dfc..866a0b72 100644
--- a/myst.yml
+++ b/myst.yml
@@ -98,7 +98,7 @@ project:
     - file: index.md
     - file: examples/index.md
       children:
-        - pattern: examples/**/*.md
+        - pattern: examples/*/*.md
     - file: schemas/index.md
       children:
         - pattern: schemas/*.md

From a2f627366372ebda818fb48b80eebeea984076c0 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Mon, 14 Sep 2026 12:45:31 +0200
Subject: [PATCH 3/3] docs: normalize anchors to hypens

---
 pre_build.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pre_build.py b/pre_build.py
index 17130dff..da1ec73a 100644
--- a/pre_build.py
+++ b/pre_build.py
@@ -52,7 +52,7 @@ def build_json_examples():
             for json_file in json_files:
                 print(f'Processing {json_file}...')
 
-                crossref = f"{__version__}:examples:{category}:{Path(json_file).stem}"
+                crossref = f"{__version__}-examples-{category}-{Path(json_file).stem}"
                 index_md += f"- [{Path(json_file).stem}](#{crossref})\n"
 
                 json_file_name = Path(json_file).stem
@@ -119,7 +119,7 @@ def build_json_schemas():
             # insert mySt cross-reference at top of markdown files
             with open(output_path_md, 'r', encoding='utf-8') as md_file:
                 md_content = md_file.read()
-            crossref = f"{__version__}:schemas:{Path(schema_file).stem}"
+            crossref = f"{__version__}-schemas-{Path(schema_file).stem}"
             md_content = f"""---
 author: ""
 ---