Add JSON-LD and llms.txt for AI search

.github/workflows/website_deploy.yml

@@ -32,6 +32,19 @@ jobs:
 
       - run: npm ci
       - run: npm run build
+      - name: Check docs llms.txt
+        run: |
+          file=.vitepress/dist/llms.txt
+          if [ ! -s "$file" ]; then
+            echo "::error::$file is missing or empty"
+            exit 1
+          fi
+          count=$(grep -cE '^- \[[^]]+\]\(https://docs\.swmansion\.com/cairo-debugger/[^)]+\)' "$file" || true)
+          if [ "$count" -eq 0 ]; then
+            echo "::error::$file lists no pages"
+            exit 1
+          fi
+          echo "llms.txt lists $count pages"
       - name: Upload GitHub Pages artifact
         uses: actions/upload-pages-artifact@v5
         with:

website/.vitepress/config.mjs

@@ -40,6 +40,8 @@ export default defineConfig({
     lang,
     base,
 
+    transformHead: (context) => [swmStructuredData(context)],
+    buildEnd: writeLlmsTxt,
     head: [
         ["meta", {httpEquiv: "Content-Language", content: lang}],
         ["link", {rel: "icon", href: `${base}favicon.svg`, type: "image/x-icon"}],

website/.vitepress/swm-geo.mjs

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const ORGANIZATION_ID = "https://swmansion.com/#organization";
+const SITE = "https://docs.swmansion.com";
+
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const decode = (value) =>
+  value
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#(?:39|x27);/g, "'")
+    .trim();
+
+const projectFromBase = (base) => base.replace(/\//g, "");
+
+// Same @id as swmansion.com, so engines read one company across both domains.
+export function swmStructuredData({ siteConfig }) {
+  const { base, description, title } = siteConfig.site;
+  const project = projectFromBase(base);
+
+  return [
+    "script",
+    { type: "application/ld+json" },
+    JSON.stringify({
+      "@context": "https://schema.org",
+      "@graph": [
+        {
+          "@type": "Organization",
+          "@id": ORGANIZATION_ID,
+          name: "Software Mansion",
+          url: "https://swmansion.com",
+          sameAs: [
+            "https://github.com/software-mansion",
+            "https://www.linkedin.com/company/software-mansion/",
+            "https://twitter.com/swmansion",
+            "https://www.youtube.com/c/SoftwareMansion",
+          ],
+        },
+        {
+          "@type": "SoftwareSourceCode",
+          name: title,
+          ...(description ? { description } : {}),
+          ...(project
+            ? {
+                codeRepository: `https://github.com/software-mansion/${project}`,
+              }
+            : {}),
+          author: { "@id": ORGANIZATION_ID },
+          maintainer: { "@id": ORGANIZATION_ID },
+        },
+      ],
+    }),
+  ];
+}
+
+function collectHtml(dir, root = dir, found = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectHtml(full, root, found);
+    else if (entry.name.endsWith(".html") && entry.name !== "404.html")
+      found.push(path.relative(root, full));
+  }
+  return found;
+}
+
+export function buildLlmsTxt({ base, description, files, readFile, title }) {
+  const entries = [];
+
+  for (const file of files) {
+    const html = readFile(file);
+    const raw = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html)?.[1] ?? "";
+    const name = decode(raw).replace(
+      new RegExp(`\\s*\\|\\s*${escapeRegExp(title)}$`),
+      "",
+    );
+    if (!name) continue;
+
+    const detail = decode(
+      /<meta[^>]+name="description"[^>]+content="([^"]*)"/i.exec(html)?.[1] ??
+        "",
+    );
+    const route = file.replace(/index\.html$/, "").replace(/\.html$/, "");
+    entries.push(
+      `- [${name}](${SITE}${base}${route})${detail ? `: ${detail}` : ""}`,
+    );
+  }
+
+  const lines = [`# ${title}`];
+  if (description) lines.push("", `> ${description}`);
+  if (entries.length) lines.push("", "## Documentation", "", ...entries.sort());
+  lines.push(
+    "",
+    "## About",
+    "",
+    `- [Software Mansion](https://swmansion.com): maintainer of ${title}`,
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+export async function writeLlmsTxt(siteConfig) {
+  const { outDir, site } = siteConfig;
+  const files = collectHtml(outDir);
+
+  await fs.promises.writeFile(
+    path.join(outDir, "llms.txt"),
+    buildLlmsTxt({
+      base: site.base,
+      description: site.description,
+      files,
+      readFile: (file) => fs.readFileSync(path.join(outDir, file), "utf8"),
+      title: site.title,
+    }),
+    "utf8",
+  );
+}