Captures the SEO idea raised in the comment thread of #355 so we don't lose it. Filing this separately because the implementation is component work, not a content edit.
Context
Google's FAQPage structured data lets search engines surface Q&A pairs directly in rich results. The schema requires each question and answer to be embedded as Question + acceptedAnswer objects in JSON-LD on the page.
Proposed approach
Build a custom <FAQ> MDX component that:
- Renders the Q&A content normally on the page
- Emits matching
FAQPage JSON-LD into a <Head> block
- Keeps the source of truth in the MDX file so authors don't maintain two copies
Would replace the current heading-based structure in docs/toolhive/faq.mdx with the component.
Worth doing?
Honest take: not obviously a win.
Arguments for
- Free SEO upside if Google picks it up
- One-time component build; reusable on the Enterprise FAQ section too
Arguments against
- Google has significantly reduced FAQ rich results in actual SERPs since 2023; mostly limited to government/health sites now
- Adds an authoring abstraction (the component) over plain Markdown, which has a cost every time someone edits the FAQ
- Our FAQ traffic isn't search-dominated; most readers land via in-doc links
If we did it, the cleanest trigger would be when we have a second FAQ section to share the component with (e.g., enterprise FAQ growing).
Acceptance (if we proceed)
<FAQ> component renders questions/answers with same visual style as today- Component emits valid
FAQPage JSON-LD (verified in Google's Rich Results Test)
docs/toolhive/faq.mdx migrated to use it- Build passes
Captures the SEO idea raised in the comment thread of #355 so we don't lose it. Filing this separately because the implementation is component work, not a content edit.
Context
Google's FAQPage structured data lets search engines surface Q&A pairs directly in rich results. The schema requires each question and answer to be embedded as
Question+acceptedAnswerobjects in JSON-LD on the page.Proposed approach
Build a custom
<FAQ>MDX component that:FAQPageJSON-LD into a<Head>blockWould replace the current heading-based structure in
docs/toolhive/faq.mdxwith the component.Worth doing?
Honest take: not obviously a win.
Arguments for
Arguments against
If we did it, the cleanest trigger would be when we have a second FAQ section to share the component with (e.g., enterprise FAQ growing).
Acceptance (if we proceed)
<FAQ>component renders questions/answers with same visual style as todayFAQPageJSON-LD (verified in Google's Rich Results Test)docs/toolhive/faq.mdxmigrated to use it