From 20feb6af75f2451375b1ee4033f925be4b075a50 Mon Sep 17 00:00:00 2001
From: Mohamed Shams El-Deen <mohamedshamseldeen95@gmail.com>
Date: Wed, 22 Jul 2026 03:53:32 +0300
Subject: [PATCH 1/2] feat(html): add sitemap generator

Enable the sitemap generator plugin in doc-kit and configure the page URLs to produce extension-based paths without double slashes. This closes #203.
---
 scripts/html/doc-kit.config.mjs | 6 +++++-
 scripts/html/index.mjs          | 2 ++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/scripts/html/doc-kit.config.mjs b/scripts/html/doc-kit.config.mjs
index 7606bb74..b448e946 100644
--- a/scripts/html/doc-kit.config.mjs
+++ b/scripts/html/doc-kit.config.mjs
@@ -10,7 +10,7 @@ const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 const VERSION = process.env.VERSION;
 const MAJOR_VERSION = VERSION ? `v${major(VERSION)}.x` : undefined;
-const URL_PATH = VERSION ? `/docs/api/${MAJOR_VERSION}` : '/';
+const URL_PATH = VERSION ? `/docs/api/${MAJOR_VERSION}` : '';
 
 const ORIGIN = process.env.VERCEL_URL
   ? `https://${process.env.VERCEL_URL}`
@@ -105,6 +105,10 @@ export default {
       },
     },
   },
+  sitemap: {
+    indexURL: '{baseURL}/',
+    pageURL: '{baseURL}{path}.html',
+  },
 };
 
 if (!VERSION) {
diff --git a/scripts/html/index.mjs b/scripts/html/index.mjs
index d2ff70c1..ab0ec250 100644
--- a/scripts/html/index.mjs
+++ b/scripts/html/index.mjs
@@ -16,6 +16,8 @@ const runDocKit = version =>
       'web',
       '-t',
       'orama-db',
+      '-t',
+      'sitemap',
       '--config-file',
       './scripts/html/doc-kit.config.mjs',
     ],

From fef4ce70424bba4cc31300603bad2ed5dca84139 Mon Sep 17 00:00:00 2001
From: Mohamed Shams El-Deen <mohamedshamseldeen95@gmail.com>
Date: Wed, 22 Jul 2026 14:52:39 +0300
Subject: [PATCH 2/2] feat(html): generate sitemap-index.xml

---
 package.json                   |  2 +-
 scripts/html/sitemap-index.mjs | 25 +++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)
 create mode 100644 scripts/html/sitemap-index.mjs

diff --git a/package.json b/package.json
index 6b0e4313..5a393acf 100644
--- a/package.json
+++ b/package.json
@@ -9,7 +9,7 @@
     "build:md:api": "node scripts/markdown/api/index.mjs && node scripts/markdown/api/configuration.mjs",
     "build:md:readmes": "node scripts/markdown/readmes.mjs",
     "build:md:governance": "node scripts/markdown/governance.mjs",
-    "build:html": "node scripts/html/index.mjs",
+    "build:html": "node scripts/html/index.mjs && node scripts/html/sitemap-index.mjs",
     "build:rss-feed": "node scripts/rss-feed/index.mjs",
     "build": "npm-run-all build:*",
     "lint": "npm-run-all \"lint:!(fix)\"",
diff --git a/scripts/html/sitemap-index.mjs b/scripts/html/sitemap-index.mjs
new file mode 100644
index 00000000..36367b03
--- /dev/null
+++ b/scripts/html/sitemap-index.mjs
@@ -0,0 +1,25 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { major } from 'semver';
+
+const versions = JSON.parse(await readFile('./versions.json', 'utf8'));
+
+const ORIGIN = process.env.VERCEL_URL
+  ? `https://${process.env.VERCEL_URL}`
+  : 'http://localhost:3000';
+
+const sitemaps = [
+  `${ORIGIN}/sitemap.xml`,
+  ...versions.map(
+    version => `${ORIGIN}/docs/api/v${major(version)}.x/sitemap.xml`
+  ),
+];
+
+const sitemapIndex = `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${sitemaps
+  .map(url => `  <sitemap>\n    <loc>${url}</loc>\n  </sitemap>`)
+  .join('\n')}
+</sitemapindex>
+`;
+
+await writeFile('./out/sitemap-index.xml', sitemapIndex, 'utf8');