From a5fbf20cbb0620fc331f9c82b706434093e91255 Mon Sep 17 00:00:00 2001
From: ReenigneArcher <42013603+ReenigneArcher@users.noreply.github.com>
Date: Mon, 5 Oct 2026 19:30:06 -0400
Subject: [PATCH] fix: source Highlight.js fixtures from a submodule

---
 .gitmodules                      |  5 +++++
 README.md                        |  3 +++
 package-lock.json                | 11 -----------
 package.json                     |  2 +-
 scripts/stage-examples.mjs       |  4 ++--
 tests-js/jsdoc-template.test.mjs |  4 ++--
 tests/test_project.py            |  9 ++++-----
 third-party/highlight.js         |  1 +
 8 files changed, 18 insertions(+), 21 deletions(-)
 create mode 100644 .gitmodules
 create mode 160000 third-party/highlight.js

diff --git a/.gitmodules b/.gitmodules
new file mode 100644
index 0000000..c7c4861
--- /dev/null
+++ b/.gitmodules
@@ -0,0 +1,5 @@
+[submodule "third-party/highlight.js"]
+	path = third-party/highlight.js
+	url = https://github.com/highlightjs/highlight.js.git
+	branch = main
+	shallow = true
diff --git a/README.md b/README.md
index 3d21c34..7ddd4c3 100644
--- a/README.md
+++ b/README.md
@@ -146,6 +146,9 @@ Doxygen and Cargo must be installed separately. The JSDoc adapter finds a projec
 `node_modules/.bin`, so a global Node.js package is not required. Open `_site/index.html` to move between the generated
 Sphinx, Doxygen, MkDocs, JSDoc, and rustdoc sites.
 
+The language gallery uses upstream fixtures from the pinned `third-party/highlight.js` submodule. `npm run build`
+initializes it automatically; keep its release tag aligned with the `@highlightjs/cdn-assets` dependency.
+
 ## Read the Docs
 
 The root `.readthedocs.yaml` delegates to `readthedocs_build.sh` because Dockle, rather than Read the Docs, owns generator
diff --git a/package-lock.json b/package-lock.json
index 1ba9728..4904d54 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -20,7 +20,6 @@
         "c8": "10.1.3",
         "eslint": "10.12.0",
         "globals": "17.13.0",
-        "highlightjs-fixtures": "github:highlightjs/highlight.js#11.12.0",
         "lucide": "1.52.0"
       },
       "engines": {
@@ -1206,16 +1205,6 @@
         "node": ">=20"
       }
     },
-    "node_modules/highlightjs-fixtures": {
-      "name": "highlight.js",
-      "version": "11.12.0",
-      "resolved": "git+ssh://git@github.com/highlightjs/highlight.js.git#f7f7d3803bd898e37c017ffb881317f0cde04a70",
-      "dev": true,
-      "license": "BSD-3-Clause",
-      "engines": {
-        "node": ">=12.0.0"
-      }
-    },
     "node_modules/hookified": {
       "version": "1.15.1",
       "resolved": "https://registry.npmjs.org/hookified/-/hookified-1.15.1.tgz",
diff --git a/package.json b/package.json
index d3b651d..69cbac9 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,7 @@
     "access": "public"
   },
   "scripts": {
+    "prebuild": "git submodule update --init --depth 1 -- third-party/highlight.js",
     "build": "npm run sync:highlighter && npm run sync:lucide && npm run stage:examples",
     "prepack": "npm run build",
     "pretest": "npm run build",
@@ -67,7 +68,6 @@
     "c8": "10.1.3",
     "eslint": "10.12.0",
     "globals": "17.13.0",
-    "highlightjs-fixtures": "github:highlightjs/highlight.js#11.12.0",
     "lucide": "1.52.0"
   }
 }
diff --git a/scripts/stage-examples.mjs b/scripts/stage-examples.mjs
index 9b0d533..4a739e0 100644
--- a/scripts/stage-examples.mjs
+++ b/scripts/stage-examples.mjs
@@ -25,8 +25,8 @@ const runtimePath = path.join(
 );
 const fixtureRoot = path.join(
   root,
-  'node_modules',
-  'highlightjs-fixtures',
+  'third-party',
+  'highlight.js',
   'test',
   'markup',
 );
diff --git a/tests-js/jsdoc-template.test.mjs b/tests-js/jsdoc-template.test.mjs
index fbd2bdf..e859bb9 100644
--- a/tests-js/jsdoc-template.test.mjs
+++ b/tests-js/jsdoc-template.test.mjs
@@ -49,8 +49,8 @@ test('the packaged highlighter includes every built-in grammar', async () => {
   assert.equal(context.hljs.listLanguages().length, packagedLanguages.length);
   const fixtureLanguages = new Set((await readdir(path.join(
     projectRoot,
-    'node_modules',
-    'highlightjs-fixtures',
+    'third-party',
+    'highlight.js',
     'test',
     'markup',
   ), { withFileTypes: true }))
diff --git a/tests/test_project.py b/tests/test_project.py
index 9858008..90ce1e3 100644
--- a/tests/test_project.py
+++ b/tests/test_project.py
@@ -94,7 +94,9 @@ def test_highlighter_runtime_is_managed_by_npm(self) -> None:
         with (PROJECT_ROOT / "package.json").open(encoding="utf-8") as stream:
             package = json.load(stream)
         version = package["devDependencies"]["@highlightjs/cdn-assets"]
-        fixtures = package["devDependencies"]["highlightjs-fixtures"]
+        fixture_manifest = PROJECT_ROOT / "third-party" / "highlight.js" / "package.json"
+        with fixture_manifest.open(encoding="utf-8") as stream:
+            fixtures = json.load(stream)
         runtime = (
             PROJECT_ROOT
             / "src"
@@ -107,10 +109,7 @@ def test_highlighter_runtime_is_managed_by_npm(self) -> None:
         ).read_text(encoding="utf-8")
 
         self.assertRegex(version, r"^\d+\.\d+\.\d+$")
-        self.assertEqual(
-            fixtures,
-            f"github:highlightjs/highlight.js#{version}",
-        )
+        self.assertEqual(fixtures["version"], version)
         self.assertTrue(
             runtime.startswith(
                 f"/*! Highlight.js {version} | BSD-3-Clause |"
diff --git a/third-party/highlight.js b/third-party/highlight.js
new file mode 160000
index 0000000..f7f7d38
--- /dev/null
+++ b/third-party/highlight.js
@@ -0,0 +1 @@
+Subproject commit f7f7d3803bd898e37c017ffb881317f0cde04a70