feat(docs): site health + AI-citation fixes (A1, A2, A8 …)

.github/workflows/build_and_check.yml

@@ -25,3 +25,6 @@ jobs:
 
       - name: Build Documentation
         run: npm run build
+
+      - name: Verify structured-data graph
+        run: npm run verify-schema

docs/components/RowOfImages.js

@@ -1,14 +1,27 @@
 import React from "react";
 
-export default function RowOfImages({imagePath1, imagePath2}) {
+export default function RowOfImages({
+  imagePath1,
+  imagePath2,
+  alt1 = "",
+  alt2 = "",
+}) {
   return (
     <div className={"docs-centered-image-wrapper"}>
       <div className="row">
         <div className="col col--6">
-          <img className="docs-centered-image-size-100" src={imagePath1} />
+          <img
+            className="docs-centered-image-size-100"
+            src={imagePath1}
+            alt={alt1}
+          />
         </div>
         <div className="col col--6">
-          <img className="docs-centered-image-size-100" src={imagePath2} />
+          <img
+            className="docs-centered-image-size-100"
+            src={imagePath2}
+            alt={alt2}
+          />
         </div>
       </div>
     </div>

docusaurus.config.js

@@ -2,6 +2,8 @@
 
 import {themes as prismThemes} from "prism-react-renderer";
 const path = require("path");
+const remarkFaqSchema = require("./src/remark/remarkFaqSchema");
+const {siteGraph} = require("./src/schema/siteEntities");
 const fs = require("fs");
 import {visit} from "unist-util-visit";
 const FontPreloadPlugin = require("webpack-font-preload-plugin");
@@ -60,121 +62,17 @@ module.exports = {
         href: "https://keploy.io/",
       },
     },
+    // Site-wide entity graph (Organization, WebSite, SoftwareApplication).
+    // These used to be three sibling <script> blocks, each re-declaring its
+    // own publisher, which left several disconnected Organization nodes on
+    // every page. They now share one graph and are addressable by `@id`, so
+    // per-page schema can point at them instead of copying them.
     {
       tagName: "script",
       attributes: {
         type: "application/ld+json",
       },
-      innerHTML: JSON.stringify({
-        "@context": "https://schema.org",
-        "@type": "SoftwareApplication",
-        name: "Keploy",
-        description:
-          "Keploy is an open-source, AI-powered testing agent and sandboxing platform that automatically generates test cases, dependency mocks, and production-like sandboxes from real user traffic using eBPF. It helps developers achieve 90% test coverage in minutes with zero code changes. Native support is available on Linux; macOS and Windows require a Linux environment such as Lima, WSL, or Docker.",
-        applicationCategory: "DeveloperTool",
-        applicationSubCategory: "Test Automation",
-        operatingSystem: "Linux",
-        license: "https://www.apache.org/licenses/LICENSE-2.0",
-        softwareHelp: "https://keploy.io/docs/",
-        codeRepository: "https://github.com/keploy/keploy",
-        downloadUrl: "https://github.com/keploy/keploy/releases",
-        isAccessibleForFree: true,
-        url: "https://keploy.io",
-        featureList: [
-          "Automatic test case generation from real user traffic",
-          "Production-like sandbox environments from captured traffic",
-          "AI-powered dependency virtualization and mock generation",
-          "Record and replay testing with eBPF kernel capture",
-          "AI noise detection for flaky test elimination",
-          "Legacy application testing without code changes",
-          "Migration regression testing against production baselines",
-          "Continuous validation in CI/CD pipelines",
-          "Multi-language support (Go, Java, TypeScript, Python)",
-        ],
-        keywords: [
-          "test automation",
-          "API testing",
-          "API test generation",
-          "unit testing",
-          "integration testing",
-          "mock generation",
-          "dependency virtualization",
-          "eBPF-based testing",
-          "record and replay",
-          "production sandbox",
-        ],
-        programmingLanguage: [
-          "Go",
-          "Java",
-          "TypeScript",
-          "JavaScript",
-          "Python",
-        ],
-        publisher: {
-          "@type": "Organization",
-          name: "Keploy",
-          url: "https://keploy.io",
-        },
-      }),
-    },
-    {
-      tagName: "script",
-      attributes: {
-        type: "application/ld+json",
-      },
-      innerHTML: JSON.stringify({
-        "@context": "https://schema.org/",
-        "@type": "Organization",
-        name: "Keploy",
-        url: "https://keploy.io/",
-        logo: "https://keploy.io/images/keploy-logo-full.svg",
-        foundingDate: "2021-01-01",
-        knowsAbout: [
-          "API Testing",
-          "Test Automation",
-          "eBPF-based Testing",
-          "Dependency Virtualization",
-          "AI-Powered Testing",
-        ],
-        award: [
-          "API World 2023 Award: Best in API Infrastructure",
-          "CNCF Landscape",
-          "Google for Startups Accelerator",
-          "Google Summer of Code Mentoring Organization",
-        ],
-        sameAs: [
-          "https://github.com/keploy",
-          "https://twitter.com/Keployio",
-          "https://www.linkedin.com/company/keploy",
-          "https://www.youtube.com/@keploy",
-          "https://discord.gg/keploy",
-          "https://community.keploy.io",
-          "https://marketplace.visualstudio.com/items?itemName=Keploy.keployio",
-          "https://chromewebstore.google.com/detail/keploy-api-test-recorder/ohcclfkaidblnjnggclkiecgkpgldihe",
-          "https://www.crunchbase.com/organization/hybridk8s",
-          "https://www.gartner.com/reviews/product/keploy-618993540",
-          "https://www.g2.com/products/keploy/reviews",
-          "https://www.capterra.in/software/1070466/Keploy",
-          "https://aws.amazon.com/marketplace/reviews/reviews-list/prodview-xgwmdk4ivjjv4",
-        ],
-      }),
-    },
-    {
-      tagName: "script",
-      attributes: {
-        type: "application/ld+json",
-      },
-      innerHTML: JSON.stringify({
-        "@context": "https://schema.org/",
-        "@type": "WebSite",
-        name: "Keploy Documentation",
-        url: "https://keploy.io/docs/",
-        potentialAction: {
-          "@type": "SearchAction",
-          target: "https://keploy.io/docs/search?q={search_term_string}",
-          "query-input": "required name=search_term_string",
-        },
-      }),
+      innerHTML: JSON.stringify(siteGraph),
     },
     // Meta Pixel Code
     {
@@ -199,7 +97,10 @@ fbq('track', 'PageView');`,
     // End Meta Pixel Code
   ],
   title: "Keploy Documentation",
-  titleDelimiter: "🐰",
+  // Plain "|" delimiter for React-page <title>s (about, security, …). The old
+  // "🐰" put an emoji in SERP titles; this keeps them clean and aligns with the
+  // "|" suffix the docs theme (DocItem) uses.
+  titleDelimiter: "|",
   tagline: "API Test Generator Tool",
   url: "https://keploy.io",
   baseUrl: "/docs/",
@@ -263,8 +164,13 @@ fbq('track', 'PageView');`,
       },
       {name: "twitter:card", content: "summary_large_image"},
       {
+        // 1200x630 card committed to this repo (static/img/), so it can't 404
+        // from a change in the landing app. The old
+        // https://keploy.io/images/keploy-hero.png returned the landing app's
+        // 404 page, breaking every social/OG preview and the Article schema
+        // image fallback that reused it.
         property: "og:image",
-        content: "https://keploy.io/images/keploy-hero.png",
+        content: "https://keploy.io/docs/img/keploy-docs-card.png",
       },
       {property: "og:image:width", content: "1200"},
       {property: "og:image:height", content: "630"},
@@ -484,6 +390,9 @@ fbq('track', 'PageView');`,
                 },
               {},
             ],
+            // Emit FAQPage JSON-LD (Question/Answer) for FAQ docs so they are
+            // eligible for FAQ rich results and AI extraction.
+            remarkFaqSchema,
           ],
         },
         // Will be passed to @docusaurus/plugin-content-blog

package.json

@@ -7,6 +7,7 @@
     "start": "docusaurus start",
     "clean": "rimraf build",
     "build": "docusaurus build",
+    "verify-schema": "node scripts/verify-schema-graph.js build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",

scripts/verify-schema-graph.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * Verifies the JSON-LD graph in the built site.
+ *
+ * The @id-based consolidation only pays off if every bare {"@id": "..."}
+ * reference resolves to a node actually defined on the same page -- an
+ * unresolved reference is worse than the inline duplicate it replaced,
+ * because consumers get a dangling pointer instead of an entity. This walks
+ * the built HTML and fails on unparseable JSON-LD, dangling references, or a
+ * regression to the generic `Article` type. noindex pages (archived versions)
+ * are skipped. Note it verifies JSON validity and @id resolution, not that
+ * every emitted `url` actually resolves.
+ *
+ * Usage: node scripts/verify-schema-graph.js [buildDir]
+ */
+const fs = require("fs");
+const path = require("path");
+
+const buildDir = process.argv[2] || "build";
+
+// Pages Docusaurus renders with a `noindex` robots meta (archived versions
+// carrying `noIndex: true`, etc.) are skipped: they keep their own legacy
+// schema copies and are never served to crawlers. Detected from the built HTML
+// rather than a hard-coded version list, so it can't drift when a version is
+// archived.
+const NOINDEX_RE = /<meta[^>]+name="robots"[^>]+content="[^"]*noindex/i;
+
+function findHtml(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      findHtml(full, out);
+    } else if (entry.name === "index.html") {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// The build inlines JSON-LD into <script type="application/ld+json">. The
+// <Head>/Helmet emitters HTML-escape entities while the raw-text body <script>
+// (remark FAQ plugin) does not, so unescape defensively before parsing --
+// unescaping already-clean JSON is a no-op here.
+const SCRIPT_RE =
+  /<script[^>]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/g;
+
+// A page is its own WebPage: the idiomatic `mainEntityOfPage:
+// {"@type":"WebPage","@id":<pageUrl>}` points at the document itself, which has
+// no separate full node. Seed `defined` with the page's own URL so that
+// self-reference resolves, while a typed ref to any *other* undefined @id is
+// still caught as dangling. Use og:url, not the canonical <link>: a few docs
+// set a cross-site canonical (e.g. to the blog), but og:url is always the
+// page's own trailing-slash URL, which is what the schema @id derives from.
+const OG_URL_RE = /<meta[^>]+property="og:url"[^>]+content="([^"]+)"/i;
+
+function unescapeHtml(s) {
+  return s
+    .replace(/&quot;/g, '"')
+    .replace(/&#x27;/g, "'")
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+// Collect every node that declares an @id, and every bare {"@id"} reference.
+function walk(node, defined, referenced) {
+  if (Array.isArray(node)) {
+    node.forEach((n) => walk(n, defined, referenced));
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  const keys = Object.keys(node).filter((k) => k !== "@context");
+  if (node["@id"]) {
+    // A node is a *reference* when it carries nothing beyond @id -- including
+    // the idiomatic typed form {"@type":"Person","@id":"…"}, which has two keys
+    // but still only points at an entity defined elsewhere. Only a node with a
+    // real property (name, url, …) *defines* the entity. Treating typed refs as
+    // definitions would let a typed pointer at an undefined @id pass silently,
+    // which is exactly the dangling case this guard exists to catch.
+    const propsBeyondId = keys.filter((k) => k !== "@id" && k !== "@type");
+    if (propsBeyondId.length === 0) {
+      referenced.add(node["@id"]);
+    } else {
+      defined.add(node["@id"]);
+    }
+  }
+  for (const key of keys) {
+    walk(node[key], defined, referenced);
+  }
+}
+
+const files = findHtml(buildDir);
+
+let parseErrors = 0;
+let dangling = 0;
+let blocks = 0;
+let scanned = 0;
+const typeCounts = new Map();
+
+for (const file of files) {
+  const html = fs.readFileSync(file, "utf8");
+  // Skip noindex pages (archived versions etc.) -- see NOINDEX_RE above.
+  if (NOINDEX_RE.test(html)) {
+    continue;
+  }
+  scanned += 1;
+  const defined = new Set();
+  const referenced = new Set();
+  const ownUrl = html.match(OG_URL_RE);
+  if (ownUrl) {
+    defined.add(ownUrl[1]);
+  }
+  let match;
+  SCRIPT_RE.lastIndex = 0;
+  while ((match = SCRIPT_RE.exec(html))) {
+    blocks += 1;
+    let parsed;
+    try {
+      parsed = JSON.parse(unescapeHtml(match[1]));
+    } catch (err) {
+      parseErrors += 1;
+      console.error(`INVALID JSON-LD  ${file}\n  ${err.message}`);
+      continue;
+    }
+    const graph = parsed["@graph"] || parsed;
+    walk(graph, defined, referenced);
+    for (const n of Array.isArray(graph) ? graph : [graph]) {
+      const t = n && n["@type"];
+      if (typeof t === "string") {
+        typeCounts.set(t, (typeCounts.get(t) || 0) + 1);
+      }
+    }
+  }
+  for (const ref of referenced) {
+    if (!defined.has(ref)) {
+      dangling += 1;
+      console.error(`DANGLING @id     ${file}\n  ${ref}`);
+    }
+  }
+}
+
+// The specialization work replaced every generic `Article` with a subtype
+// (TechArticle / APIReference / BlogPosting). Pin that: a stray generic
+// `Article` reappearing is a regression the shape checks above wouldn't catch.
+const genericArticles = typeCounts.get("Article") || 0;
+
+console.log(`\nPages scanned:     ${scanned}`);
+console.log(`JSON-LD blocks:    ${blocks}`);
+console.log(`Invalid JSON:      ${parseErrors}`);
+console.log(`Dangling @id refs: ${dangling}`);
+console.log(`Generic Article:   ${genericArticles}`);
+console.log("\nTop-level @type distribution:");
+for (const [type, count] of [...typeCounts].sort((a, b) => b[1] - a[1])) {
+  console.log(`  ${String(count).padStart(5)}  ${type}`);
+}
+if (genericArticles) {
+  console.error(
+    `\nFAIL: ${genericArticles} generic "Article" node(s) -- use TechArticle/APIReference/BlogPosting.`
+  );
+}
+
+process.exit(parseErrors || dangling || genericArticles ? 1 : 0);