feat(docs): add FAQPage and HowTo JSON-LD schemas for SEO/AEO

[rubenmarcus]

Summary

• Add FAQPage JSON-LD schema with 6 Q&A pairs (what is ralph-starter, pricing, Figma support, supported agents, integrations, accessibility)
• Add HowTo JSON-LD schema for "How to convert Figma designs to code with AI" (4 steps, 5min total time)
• Add "See Also" cross-links to GitHub source docs page
• Targets Google rich results (FAQ accordion, HowTo steps)

Test plan

• pnpm build in docs/ — builds without errors
• Validate JSON-LD at https://search.google.com/test/rich-results
• Check rendered HTML has 6 <script type="application/ld+json"> tags (was 4, now 6)
• GitHub source docs shows "See Also" section at bottom

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

Issue Linking Reminder

This PR doesn't appear to have a linked issue. Consider linking to:

• This repo: Closes #123
• ralph-ideas: Closes multivmlabs/ralph-ideas#123

Using Closes, Fixes, or Resolves will auto-close the issue when this PR is merged.

---

If this PR doesn't need an issue, you can ignore this message.

[greptile-apps]

Greptile Summary

This PR adds FAQPage and HowTo JSON-LD structured data schemas to the Docusaurus documentation site for SEO/AEO purposes, alongside keyword and description updates across existing schemas to highlight Figma and visual-validation capabilities. It also adds a "See Also" cross-link section to github.md.

Key findings:

• ⚠️ SEO compliance risk: The FAQPage and HowTo schemas are injected globally via headTags on every page of the site, which violates Google's structured data guidelines — these schemas are only valid on pages where the corresponding content is visible to users.
• Schema conformance issue: The HowTo schema uses SoftwareApplication for the tool property, which should be HowToTool per schema.org specifications.
• Consistency gap: The docusaurus-plugin-llms description was not updated to include Figma/visual-validation, leaving it inconsistent with other updated descriptions in this PR.
• The keyword, description, and structured data updates to existing schemas are accurate and well-formed.
• The "See Also" section added to github.md is clean and links to the correct related CLI pages.

Confidence Score: 3/5

• Safe to merge for metadata and documentation updates, but the global FAQPage/HowTo injection introduces a real SEO policy violation that should be resolved before going live.
• The keyword, description, and Markdown additions are low-risk and well-executed. However, the global injection of FAQPage and HowTo schemas across all pages violates Google's structured data guidelines in a way that could result in a domain-level manual action against rich results — a meaningful compliance risk that warrants fixing before deployment. Additionally, the HowTo tool type is not schema.org compliant, and the llms-plugin description consistency gap should be addressed.
• docs/docusaurus.config.ts — the global headTags placement of FAQPage and HowTo schemas needs to be scoped to a dedicated page where the content is actually rendered, the HowTo tool type needs correction, and the llms-plugin description needs updating to include Figma/visual-validation.

Comments Outside Diff (2)

1. docs/docusaurus.config.ts, line 216-322 (link)

   FAQPage and HowTo schemas are injected globally on all pages

   Both the FAQPage (lines 216–276) and HowTo (lines 277–321) schemas are placed inside headTags, which Docusaurus injects into every page of the site. According to Google's structured data guidelines:

   • FAQPage must only appear on pages where the FAQ questions and answers are actually visible to users. Adding it globally violates Google's FAQ rich results policy and can result in a manual action.
   • HowTo markup similarly must only appear on pages where the full step-by-step content is displayed.

   Currently, these schemas will appear on documentation pages like /docs/sources/github.md where the FAQ and HowTo content is not visible to users.

   Recommended fix: Move these schemas to a dedicated FAQ/HowTo page (e.g., docs/faq.md) and inject them only there using Docusaurus per-page frontmatter with custom head tags, rather than globally in docusaurus.config.ts.

2. docs/docusaurus.config.ts, line 328-334 (link)

   Plugin description not updated to match other changes

   The docusaurus-plugin-llms description omits Figma and visual-validation, while all other descriptions in this PR were updated to include these terms. This creates an inconsistency in the metadata crawlers see.

_{Last reviewed commit: 59bc40b}

[github-actions]

🔗 Docs Preview

Preview URL: https://feat-seo-aeo-improvements.ralph-starter-docs.pages.dev

This preview was deployed from the latest commit on this PR.