feat(docs): site health + AI-citation fixes (A1, A2, A8 …) - #897
Open
dhananjay6561 wants to merge 11 commits into
Open
feat(docs): site health + AI-citation fixes (A1, A2, A8 …)#897dhananjay6561 wants to merge 11 commits into
dhananjay6561 wants to merge 11 commits into
Conversation
DocItem computed socialImage but never included it in the Article/ TechArticle JSON-LD, so every doc page emitted an Article without the required 'image' field -> ~146 pages flagged invalid structured data. Add image to articleSchema, falling back to the site-wide default social card (the same 1200x630 og:image from docusaurus.config.js) when a doc sets no front-matter image. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
The swizzled DocItem set <title>{title}</title>, identical to the on-page
<h1> (also the doc title) -> SEMrush 'Duplicate content in h1 and title'
on 124 pages. Append ' | Keploy Docs' so the title differs from the h1.
Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
13 images across 8 doc pages (glossary GIFs + running-keploy screenshots) had no alt attribute -> SEMrush 'Missing ALT' + weaker AI/accessibility extraction. Add descriptive alt to each. utg-vscode-extension from the audit list no longer exists on main, so it is not included. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
Pre-existing whitespace/list-indent/final-newline issues in these two files (unrelated to the alt fix) would fail the prettier CI check once the files are touched. Apply prettier so the PR is clean. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Docusaurus DocItem theme component to address SEO / AI-citation audit findings by improving structured data completeness and avoiding duplicate <title>/<h1> signals across docs pages.
Changes:
- Adds an
imagefield to the per-page Article/TechArticle JSON-LD (with a fallback when front matter has no image). - Appends a suffix to
<title>to differentiate it from the on-page<h1>.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Wrap the long articleImage fallback line and flatten the pre-existing nested-ternary indentation so the swizzled DocItem is clean under the CI-pinned prettier 2.8.8 (--check runs on changed files). Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
The prettify_code workflow pins prettier_version 2.8.8, but creyD/ prettier_action's npx step actually installs and runs prettier 3.9.6. 3.x changed nested-ternary indentation, so the prior 2.8.8-flattened schemaType ternary failed CI. Reformat to 3.9.6 (the version CI runs) so --check passes; all other changed files are already 3.9.6-clean. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
Every /docs page emitted a generic Article. Route API-reference pages (api-testing-*, public-api, cli-commands, sdk-installation — by tag or path) to APIReference, and default all other docs to TechArticle. Both are Article subtypes accepting the same properties as articleSchema, so the schema shape is unchanged — just a precise, AI/Google-friendly type. Built HTML: 35 APIReference, 343 TechArticle, 0 generic Article from docs. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
general-glossary + 3 glossary terms shared one boilerplate description; share-tests copied the generate-api-tests description; k8s-proxy had a wrong (NextJS/Drizzle) description. Give each a unique, accurate one to clear SEMrush 'Duplicate meta descriptions'. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
Pre-existing leading-space paragraphs (unrelated to the description change) would fail the prettier CI check once the file is touched. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
/leadership, /security and /privacy-policy emitted zero page-level schema. Add JSON-LD: leadership -> CollectionPage + ItemList of Person (name, photo, Twitter, worksFor Keploy); security -> WebPage + security ContactPoint (responsible-disclosure email); privacy-policy -> DigitalDocument with dateModified. Verified in built HTML. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
New dependency-free remark plugin extracts each ### question + following answer prose from FAQ docs (keploy-explained/*-faq) and injects FAQPage JSON-LD with Question/acceptedAnswer pairs, so they're eligible for FAQ rich results and AI extraction. Built HTML: FAQPage with 14/11/12 Q&A on the three FAQ pages. Signed-off-by: dhananjay6561 <dhananjayaggarwal6561@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Site Health + AI-citation / GEO fixes for the docs site, from the Aug 2026 SEMrush audit (Site Health 84%, AI Search Health 84%) and the schema-type audit. Covers the docs tickets A1–A10 / AI1–AI6 plus the structured-data specialization from the schema audit, prioritising template-level fixes that clear hundreds of pages at once.
📊 Ticket status
SEOAIimageadded to Article schema — fixes ~146 "invalid structured data"SEO<title>differentiated from on-page<h1>— fixes 124 duplicatesSEOA11YAIalton 13 images / 8 pagesSEOAIArticle→ 343TechArticle+ 35APIReferenceSEOAI/leadership(CollectionPage+ItemList+Person),/security(WebPage+ContactPoint),/privacy-policy(DigitalDocument)AIFAQPageJSON-LD (Question/Answer) on the 3 FAQ docs (14/11/12 Q&A)A11YAIaria-labelsSEO@idSEOAIDefinedTermon glossary term pagesSEOAISEOSEOAISEOAIPERFSEO/docs/1.0.0/*block is intentional✅ Changes so far
Structured data — schema specialization (schema audit)
Article.DocItemnow routes API-reference pages (api-testing-*, public-api, cli-commands, sdk-installation — by tag or path) toAPIReferenceand defaults all other docs toTechArticle. Both areArticlesubtypes accepting the same properties, so the schema shape is unchanged — just a precise, AI/Google-friendly type. Built HTML: 35 APIReference, 343 TechArticle, 0 generic Article from docs.imageon Article schema —DocItemcomputedsocialImagebut never put it in the JSON-LD, so ~146 pages were "invalid structured data" (missingimage). Now included, with the site-wide 1200×630 og:image as the fallback.Structured data — new emitters
/leadership,/security,/privacy-policy) emitted zero page-level schema. Added JSON-LD:CollectionPage+ItemListofPerson(leadership team, with photo + Twitter + worksFor),WebPage+ securityContactPoint(responsible-disclosure email), andDigitalDocumentwithdateModified(privacy policy).src/remark/remarkFaqSchema.js) extracts each### question+ answer prose from the FAQ docs intoQuestion/acceptedAnswerpairs and injectsFAQPageJSON-LD. Built HTML: valid FAQPage with 14 / 11 / 12 Q&A on the three FAQ pages.SEO / metadata
DocItemset<title>{title}</title>(identical to the h1) on 124 pages; now suffixed| Keploy Docs.share-testscopied the generate-api-tests one, andk8s-proxyhad a wrong (NextJS/Drizzle) description; each now has a unique, accurate one.Accessibility / AI
alttext — added descriptivealtto 13 images across 8 pages (glossary GIFs + running-keploy screenshots).🧭 Notes / deviations from the plan
Heading/index.js), and the breadcrumb home link already carryaria-labels; the residual SEMrush "no anchor text" is the zero-width-space hash-link icons, which already have the correct accessible name.AggregateRating/Reviewfor one's own product violates Google's structured-data policy (manual-action risk). Real ratings stay surfaced via the OrganizationsameAslinks (G2/Gartner/Capterra). (Same call as CWV perf(docs): core web vitals — self-host fonts, drop dead assets, defer pixel, add security headers #896.)mainanyway.✅ Verification
npm run buildsucceeds (onBrokenLinks: throw); all changed files pass prettier 3.9.6 (the version CI's action actually runs, despite the 2.8.8 pin).@typedistribution (TechArticle/APIReference), bespoke-page schema present, FAQPage JSON-LD decodes to validFAQPagewith all Q&A.