Skip to content

docs: add schema.org structured-data matrix #903

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nehagup merged 2 commits into from
Sep 7, 2026
Merged

docs: add schema.org structured-data matrix #903

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
43cb135
docs: add schema.org structured-data matrix
dhananjay6561 Sep 7, 2026
c968913
docs: format schema matrix with prettier
dhananjay6561 Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions SCHEMA_MATRIX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# Structured Data (Schema.org) Matrix

A map of every JSON-LD `schema.org` type emitted across the docs site, the
source that emits it, and the pages/components it applies to. Introduced in
[PR #897](https://github.com/keploy/docs/pull/897) (site health + AI-citation
fixes). Use this as the single reference when adding, moving, or debugging
structured data.

> **Why this exists:** JSON-LD nodes that share an `@id` are merged by
> consumers (Google, LLM answer engines). Canonical entities are declared once
> in `src/schema/siteEntities.js` and referenced by `@id` everywhere else, so
> the graph stays consistent. See the header comment in that file.

## 1. Site-wide graph (every route)

Injected into the `<head>` of **every** page via `headTags` in
`docusaurus.config.js` (`innerHTML: JSON.stringify(siteGraph)`).

| Schema type | `@id` | Source | Applies to |
| --------------------- | --------------------------------- | ---------------------------------------------------------- | ---------- |
| `Organization` | `https://keploy.io/#organization` | `src/schema/siteEntities.js` → `siteGraph` | All routes |
| `WebSite` | `https://keploy.io/docs/#website` | `src/schema/siteEntities.js` → `siteGraph` | All routes |
| `SoftwareApplication` | `https://keploy.io/#keploy` | `src/schema/siteEntities.js` → `siteGraph` | All routes |
| `ImageObject` | `https://keploy.io/#logo` | nested in `Organization.logo` | All routes |
| `SearchAction` | — | nested in `WebSite.potentialAction` (sitelinks search box) | All routes |

These three nodes are referenced by `@id` (`organizationRef`, `websiteRef`)
from the per-page schemas below, so the per-page nodes never re-declare the
publisher/author organization.

## 2. Per-doc schema (Markdown pages via `DocItem`)

Emitted by `src/theme/DocItem/index.js` for pages rendered through the docs
theme. Type is chosen per page from front matter, path, and content.

| Schema type | When it applies | Key logic in `DocItem` |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `TechArticle` | Default for any normal doc page | `schemaType` fallback |
| `APIReference` | `/running-keploy/public-api` and `/running-keploy/cli-commands`, or `apiReference: true` / `type: api` front matter | `isApi` |
| `BlogPosting` | `type: blog` / `blog: true` front matter, or `blog` tag | `isBlog` |
| `[<type>, LearningResource]` | Quickstart tutorials — `/quickstart/<name>/`; adds `learningResourceType: "Tutorial"` | `isQuickstart` |
| Custom via front matter | `schemaType:` / `schema_type:` front matter overrides all detection | `schemaTypeFromFrontMatter` |
| `DefinedTerm` | Glossary term pages — `/concepts/reference/glossary/<term>/`; joins the glossary `DefinedTermSet` by `@id` | `isGlossaryTerm` |
| `CollectionPage` | Section index pages (source is `index.md`/`README.md`, not the docs root) | `isCategoryHub` |
| _(suppressed)_ | Docs root, versioned roots (`/docs/4.0.0/`), category index pages — emit only breadcrumbs | `suppressArticleSchema` |

Every `Article`-family node references `organizationRef` (publisher/author
fallback) and `websiteRef` (`isPartOf`), and carries a fallback social-card
`image` (`static/img/keploy-docs-card.png`).

## 3. Breadcrumbs (docs pages)

| Schema type | Source | Applies to |
| ----------------------------- | ---------------------------------------------- | --------------------------------------- |
| `BreadcrumbList` + `ListItem` | `src/theme/DocBreadcrumbs/index.js` | Every docs page with a breadcrumb trail |
| `BreadcrumbList` + `ListItem` | `breadcrumbList()` helper in `siteEntities.js` | Bespoke React pages (see §5) |

## 4. Content-injected schema (Markdown authoring)

| Schema type | Source | Applies to |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `FAQPage` → `Question` / `Answer` | `src/remark/remarkFaqSchema.js` (remark plugin, wired in `docusaurus.config.js`) | `*-faq.md` pages: `keploy-explained/api-testing-faq`, `integration-testing-faq`, `unit-testing-faq` |
| `HowTo` → `HowToStep`, `HowToSupply`, `HowToTool`, `MonetaryAmount` | `src/components/HowTo.js` (used as `<HowTo>` in MDX) | ~44 quickstart / installation / server docs |

The `remarkFaqSchema` plugin auto-detects FAQ docs by the `-faq.md` filename,
turns each `##`/`###` heading into a `Question`, and only emits when it finds
≥2 Q&A pairs (skips the `## Related` divider).

## 5. Bespoke React pages (`src/pages/*`)

Each hand-built page emits its own JSON-LD, using `organizationRef` /
`websiteRef` / `breadcrumbList()` from `siteEntities.js` for consistency.

| Page (route) | Source | Schema types emitted |
| ---------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------- |
| Home (`/docs/`) | `src/pages/index.js` | `CollectionPage`, `ItemList` + `ListItem`, `BreadcrumbList` |
| About (`/about`) | `src/pages/about.js` | `AboutPage`, `BreadcrumbList` |
| Leadership (`/leadership`) | `src/pages/leadership.js` | `CollectionPage`, `ItemList` + `ListItem`, `Person` |
| Application Development (`/application-development`) | `src/pages/application-development.js` | `WebPage`, `ItemList` + `ListItem`, `BreadcrumbList` |
| Security (`/security`) | `src/pages/security.js` | `WebPage`, `Organization`, `ContactPoint` |
| Privacy Policy (`/privacy-policy`) | `src/pages/privacy-policy.js` | `DigitalDocument` |
| Glossary hub (`/concepts/reference/glossary/`) | `src/pages/concepts/reference/glossary.js` | `DefinedTermSet` + `DefinedTerm`, `BreadcrumbList` |
| Community | `src/components/Community.js` | `ItemList` + `ListItem` |

The glossary hub's `DefinedTermSet` (`@id` = `TERMSET_ID`) is the set that each
individual glossary term page's `DefinedTerm` (§2) joins via `inDefinedTermSet`.

## Quick reference: type → source

| Schema type | Emitted by |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `Organization` | `siteEntities.js` (site graph); `security.js` |
| `WebSite` | `siteEntities.js` (site graph) |
| `SoftwareApplication` | `siteEntities.js` (site graph) |
| `ImageObject` | `siteEntities.js` (nested in Organization) |
| `SearchAction` | `siteEntities.js` (nested in WebSite) |
| `TechArticle` / `APIReference` / `BlogPosting` | `DocItem/index.js` |
| `LearningResource` | `DocItem/index.js` (quickstarts) |
| `DefinedTerm` | `DocItem/index.js` (term pages); `glossary.js` (hub) |
| `DefinedTermSet` | `glossary.js` |
| `CollectionPage` | `DocItem/index.js` (section hubs); `index.js`; `leadership.js` |
| `BreadcrumbList` / `ListItem` | `DocBreadcrumbs/index.js`; `siteEntities.js` helper |
| `FAQPage` / `Question` / `Answer` | `remarkFaqSchema.js` |
| `HowTo` / `HowToStep` / `HowToSupply` / `HowToTool` / `MonetaryAmount` | `HowTo.js` |
| `AboutPage` | `about.js` |
| `WebPage` | `security.js`; `application-development.js` |
| `ContactPoint` | `security.js` |
| `DigitalDocument` | `privacy-policy.js` |
| `Person` | `leadership.js` |
| `ItemList` / `ListItem` | `index.js`; `leadership.js`; `application-development.js`; `Community.js` |

---

_Generated as a reference for the structured-data work in PR #897. When you add
a new schema emitter or change a type, update this table._
Loading