seo: HowTo schema, glossary DefinedTermSet, docs landing fixes by slayerjain · Pull Request #857 · keploy/docs

slayerjain · 2026-05-04T17:36:52Z

Summary

Audit-driven fixes on keploy.io/docs.

Critical fixes

/docs/ landing rendered zero H1, title Keploy Documentation (20c), description API Test Generator Tool (23c) — both too short. Added an sr-only H1 plus a longer Layout title/description on src/pages/index.js: Keploy Documentation — Install, Capture & Replay API Tests (58c) + a 159-char description covering install, capture, CI replay, SDK references.
src/pages/about.js shipped zero JSON-LD because src/pages/* is not covered by the docs schema plugin. Inlined Article + BreadcrumbList JSON-LD via @docusaurus/Head.
src/pages/concepts/reference/glossary.js shipped zero JSON-LD. Now emits a single DefinedTermSet from the entire glossaryEntries data, with one DefinedTerm per glossary entry. Mirrors the pattern from landing's /what-is-api-testing layout — gives AI engines and search engines a clean, citable definition graph.
Sitemap: noIndex: true on the 1.0.0 / 2.0.0 archives and ignorePatterns for /tags/**, /1.0.0/**, /2.0.0/**. Reduces crawl-budget dilution; preserves the recently-added priority-bucket comments above the sitemap config.

HowTo schema rollout

New src/components/HowTo.js wrapper. Emits HowTo JSON-LD via @docusaurus/Head and (when visible={true}) renders a numbered <ol> of steps. Use visible={false} on pages that already render steps in prose to avoid duplicate UI.
Applied to versioned_docs/version-4.0.0/server/installation.md with visible={false} — the existing "Capturing Testcases" / "Running Testcases" prose stays as-is, only the JSON-LD ships. The schema's step.url values point at explicit {#capturing-testcases} / {#running-testcases} heading anchors.
Applied to all 32 quickstart pages in versioned_docs/version-4.0.0/quickstart/ with visible={false} (existing tutorial prose remains; only schema added).

SDK-installation title alignment

/docs/server/sdk-installation/{go,python,javascript} had H1/title Merge Test Coverage Data while the URL says sdk-installation. Title rewritten to Keploy [Language] SDK — Install & Merge Test Coverage so URL and content topic align without route renames or 301s.
java.md is unchanged here — upstream main has rewritten that file as the Enterprise dynamic-deduplication agent guide, so the SDK-install framing no longer applies. (Resolved during merge.)

Test plan

npx docusaurus build succeeds — verified
Spot-check /docs/ page source: <h1> present + 50–60c title + 150–160c meta description
Spot-check /docs/about/ and /docs/concepts/reference/glossary/: each emits <script type="application/ld+json">
Google Rich Results test: DefinedTerm schema valid on glossary; HowTo valid on /docs/server/installation/ and a sample quickstart
Confirm /docs/sitemap.xml excludes /tags/*, /1.0.0/*, /2.0.0/* after rebuild
Companion PRs in keploy/landing (fix ci pipeline for PR build and check #207) and keploy/blog-website (feat: update broken links and glossary page from user pov #383)

🤖 Generated with Claude Code

Audit findings on keploy.io/docs and follow-up coverage. Critical fixes: - /docs/ landing was rendering zero H1, with title "Keploy Documentation" (20 chars) and description "API Test Generator Tool" (23 chars). Both too short to capture docs intent (install, capture, replay, SDK). Added an sr-only H1 plus a longer Layout title/description on src/pages/index.js ("Keploy Documentation — Install, Capture & Replay API Tests" + a 159-char description covering install, capture, CI replay, SDK references). - src/pages/about.js shipped zero JSON-LD because src/pages/* are not covered by the docs schema plugin. Inlined Article + BreadcrumbList JSON-LD via @docusaurus/Head. - src/pages/concepts/reference/glossary.js shipped zero JSON-LD too. Now emits a single DefinedTermSet from the entire glossaryEntries data, with one DefinedTerm per glossary entry. Mirrors the pattern in landing's /what-is-api-testing layout. - Docusaurus sitemap noIndex on 1.0.0 / 2.0.0 archives + ignorePatterns to drop /tags/** and /1.0.0/** /2.0.0/** from the generated sitemap. Reduces crawl-budget dilution; preserves the recently-added priority bucket comments above the sitemap config. HowTo schema rollout: - New src/components/HowTo.js wrapper. API: <HowTo name="Install Keploy on Linux" totalTime="PT5M" tools={[...]} supplies={[...]} steps={[{name, text, url}, ...]} visible={true|false} /> Emits valid HowTo JSON-LD via @docusaurus/Head and (when visible) renders a numbered <ol>. Use visible={false} on pages that already render the steps in prose to avoid duplicate UI. - Applied to versioned_docs/version-4.0.0/server/installation.md (visible HowTo above the existing prose). - Applied to all 32 quickstart pages in versioned_docs/version-4.0.0/quickstart with visible={false} (existing tutorial prose remains; only schema is added). SDK-installation title alignment: - /docs/server/sdk-installation/go|python|javascript pages had H1/title "Merge Test Coverage Data" while the URL says "sdk-installation". Title rewritten to "Keploy [Language] SDK — Install & Merge Test Coverage" so URL and content topic align without renaming the route or moving files. java.md is unchanged here — upstream main has rewritten that file as the Enterprise dynamic-deduplication agent guide, so the SDK-install framing no longer applies to it. Built + verified: `npx docusaurus build` produces a clean static build. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR applies an SEO-focused audit pass across the Docusaurus docs site by improving page metadata (title/description/H1), adding structured data (JSON-LD) for richer indexing, and reducing crawl-budget waste via sitemap/version noindex configuration.

Changes:

Added a reusable HowTo component that emits schema.org HowTo JSON-LD (and optionally renders a visible step list), and applied it across installation + quickstart pages.
Added inline JSON-LD (Article, DefinedTermSet, BreadcrumbList) to React pages under src/pages/ (landing, about, glossary) to ensure schema is emitted where the docs plugin schema doesn’t apply.
Updated sitemap/docs versioning config to mark old versions as unmaintained/noindex and exclude tags/legacy versions from sitemap generation.

Reviewed changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
versioned_docs/version-4.0.0/server/sdk-installation/python.md	Update frontmatter title/description to align with “SDK installation” topic.
versioned_docs/version-4.0.0/server/sdk-installation/javascript.md	Update frontmatter title/description to align with “SDK installation” topic.
versioned_docs/version-4.0.0/server/sdk-installation/go.md	Update frontmatter title/description to align with “SDK installation” topic.
versioned_docs/version-4.0.0/server/installation.md	Add `HowTo` JSON-LD block describing installation/record/replay steps.
versioned_docs/version-4.0.0/quickstart/sanic-mongo.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/samples-rust.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/samples-node-mongo.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/samples-java.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/samples-go-sse-svelte.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/samples-go-gin-mongo.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/samples-express-mongoose.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/samples-echo.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/samples-bunjs.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/sample-ts.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/sample-rust-crud-mongo.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/rust-wrap-mongo.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/python-microservices.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/python-flask-mongo.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/python-fastapi-twilio.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/python-fastapi-sql.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/python-django-sql.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/node-jwt-sql.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/node-express-mongoose.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/nextjs-postgres.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/k8s-proxy.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/java-spring-postgres.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/java-spring-boot-xml.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/java-spring-boot-openhospital.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/java-spring-boot-mongo.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/go-mux-sql.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/go-mux-mysql.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/go-gin-redis.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/go-fasthttp-postgres.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/flask-redis.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/express-postgresql-prisma.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
versioned_docs/version-4.0.0/quickstart/csharp-dotnet-postgres.md	Add hidden `HowTo` JSON-LD schema for the quickstart.
src/pages/index.js	Improve docs landing title/description and add an SR-only H1 + JSON-LD.
src/pages/concepts/reference/glossary.js	Emit `DefinedTermSet` + `BreadcrumbList` JSON-LD for glossary entries.
src/pages/about.js	Emit `Article` + `BreadcrumbList` JSON-LD for the About page.
src/components/HowTo.js	Introduce a `HowTo` wrapper component to emit HowTo JSON-LD (and optional UI).
docusaurus.config.js	Mark legacy versions noindex and exclude tags/legacy versions from sitemap.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- versioned_docs/version-4.0.0/server/installation.md: add explicit {#capturing-testcases} / {#running-testcases} anchors on the H2s and update HowTo step.url to those anchors. The previous `#-capturing-testcases` slug relied on Docusaurus's auto-slugger behavior with leading emojis and was fragile. - versioned_docs/version-4.0.0/quickstart/k8s-proxy.md: HowTo `tools` list now includes Kind, kubectl, Helm — the prerequisites the page itself calls out below the schema. - versioned_docs/version-4.0.0/quickstart/samples-express-mongoose.md: HowTo `name` is now title-cased ("Sample Course-Selling API (Express) — Record and Replay Tests with Keploy") instead of all lowercase. - versioned_docs/version-4.0.0/quickstart/samples-node-mongo.md: fix typo "Intoduction" → "Introduction". - src/pages/about.js: drop unused `useBaseUrl` import. JSON-LD URLs now carry trailing slashes to match Docusaurus `trailingSlash: true` config — both the Article `url`/`@id` and the BreadcrumbList `item`s. - src/pages/concepts/reference/glossary.js: same trailing-slash fix for DefinedTermSet `@id`/`url`, per-term DefinedTerm `url`s, and the BreadcrumbList items. Centralized via a `withTrailingSlash` helper so future glossary entries inherit the canonical form. - src/pages/index.js: Article schema's `headline` and `description` now derive from `docsHomeTitle` / `docsHomeDescription` (the same values used for the rendered <title>, meta description, and sr-only H1) instead of the old short `siteConfig.title` / `siteConfig.tagline`. Schema and on-page metadata now agree.

- src/components/HowTo.js: when `visible={true}`, the rendered <ol> no longer derives <li id> from `s.url` alone (multiple steps can share the same anchor and that produced duplicate ids in the DOM). The id now suffixes the step position — `${slug}-step-${i+1}`. - versioned_docs/version-4.0.0/server/sdk-installation/python.md: meta description rephrased — was a sentence fragment ending "Combined reports seamlessly.", now a complete clause that reads cleanly in SERP snippets. - versioned_docs/version-4.0.0/server/sdk-installation/javascript.md: same fix for the "Combined integration + unit-test reports." fragment.

Copilot

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- src/components/HowTo.js: stop deriving the visible <li> `id` from `s.url`. In docs usage step.url often points at an existing heading anchor on the page (e.g. `#capturing-testcases`), so the list-item id would clash with the h2 anchor whenever `visible` is enabled. The list is just the readable view; `step.url` in the JSON-LD already carries the schema linkage. - static/data/glossaryEntries.js: fix the "Stubs" entry which had `ink:` instead of `link:`. - src/pages/concepts/reference/glossary.js: defensively filter glossary entries missing a valid `link` before mapping into DefinedTerm.url, so a future similar gap can't ship a malformed `https://keploy.ioundefined` URL into the JSON-LD.

slayerjain · 2026-05-04T18:34:44Z

@copilot-pull-request-reviewer review

Copilot

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

The first install-Linux HowTo step ("Download and install the Keploy binary") was pointing at #capturing-testcases — that anchor exists on the page but it's the wrong section for the install command. There's no installation-specific anchor to point to (the install runs inline above the H2s), so drop the url field for that step rather than emit a misleading deep link. Go SDK meta description was a noun phrase tail of "Graceful shutdown setup, -cover flag, combined reports." Rephrase as a complete sentence so AI engines and snippet renderers can quote it cleanly.

Copilot

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/pages/about.js:47

useDocusaurusContext() is only used to destructure siteConfig, but siteConfig is never referenced. Consider removing the unused useDocusaurusContext import and the unused context/siteConfig variables to avoid ESLint no-unused-vars warnings and keep the page module minimal.

import Head from "@docusaurus/Head";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";

// Custom React pages under src/pages/ are not covered by the docs schema
// plugin — add Article + BreadcrumbList JSON-LD inline so the page is
// machine-readable for search engines and AI crawlers.
//
// Site config sets `trailingSlash: true`, so canonical URLs in the JSON-LD
// must carry the trailing slash to match the actual emitted href and avoid
// duplicate URL variants in structured data.
const aboutStructuredData = [
  {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: "About the Keploy Documentation",
    description:
      "Information about Keploy's documentation, contribution guidelines, and licensing.",
    url: "https://keploy.io/docs/about/",
    publisher: {
      "@type": "Organization",
      name: "Keploy",
      logo: {
        "@type": "ImageObject",
        url: "https://keploy.io/docs/img/favicon.png",
      },
    },
    mainEntityOfPage: {
      "@type": "WebPage",
      "@id": "https://keploy.io/docs/about/",
    },
  },
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    itemListElement: [
      {"@type": "ListItem", position: 1, name: "Home", item: "https://keploy.io/"},
      {"@type": "ListItem", position: 2, name: "Docs", item: "https://keploy.io/docs/"},
      {"@type": "ListItem", position: 3, name: "About", item: "https://keploy.io/docs/about/"},
    ],
  },
];

function About() {
  const context = useDocusaurusContext();
  const {siteConfig = {}} = context;

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…teps baseUrl is /docs/, so Docusaurus emits sitemap routes as /docs/tags/... and /docs/1.0.0/.../docs/2.0.0/... . The previous bare patterns (/tags/**, /1.0.0/**, /2.0.0/**) couldn't match those, so tag indexes and the legacy doc versions were quietly slipping into the generated sitemap despite the noIndex headers elsewhere. Add the prefixed patterns; keep the bare ones as defence-in-depth in case baseUrl is ever flattened. HowTo.js was emitting steps with empty `text` and auto-generated "Step N" names whenever authors omitted those fields, producing low-quality HowTo structured data the rich-results test flags. Filter to entries that carry both `name` and `text`; drop the schema entirely if none qualify, and render the visible <ol> from the same filtered list so the markup and JSON-LD stay in sync.

Copilot

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings May 4, 2026 17:36

Copilot started reviewing on behalf of slayerjain May 4, 2026 17:37 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

nehagup requested a review from Copilot May 4, 2026 17:53

Copilot started reviewing on behalf of nehagup May 4, 2026 17:54 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

nehagup requested a review from Copilot May 4, 2026 18:07

Copilot started reviewing on behalf of nehagup May 4, 2026 18:09 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

Comment thread src/pages/concepts/reference/glossary.js Outdated

Comment thread src/components/HowTo.js Outdated

Copilot started work on behalf of slayerjain May 4, 2026 18:34 View session

Copilot finished work on behalf of slayerjain May 4, 2026 18:37

Merge branch 'main' into seo/audit-fixes

6a9e664

nehagup requested a review from Copilot May 5, 2026 12:08

Copilot started reviewing on behalf of nehagup May 5, 2026 12:11 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread versioned_docs/version-4.0.0/server/installation.md

Comment thread versioned_docs/version-4.0.0/server/sdk-installation/go.md Outdated

nehagup requested a review from Copilot May 5, 2026 13:33

Copilot started reviewing on behalf of nehagup May 5, 2026 13:34 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread docusaurus.config.js

Comment thread src/components/HowTo.js

nehagup requested a review from Copilot May 5, 2026 19:23

Copilot started reviewing on behalf of nehagup May 5, 2026 19:24 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

Uh oh!

Conversation

slayerjain commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

slayerjain commented May 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

slayerjain commented May 4, 2026 •

edited

Loading