docs(www): SEO/AEO audit fixes for simple-stack.dev

[bholmesdev]

SEO / AEO audit for simple-stack/www

This PR ships the highest-impact SEO and Answer Engine Optimization (AEO) fixes for the Starlight-powered docs site at https://simple-stack.dev.

Audit findings

Crawlability / discovery

• ❌ astro.config.mjs had no site URL → Starlight could not emit canonical URLs, absolute og:image / og:url, or a sitemap.
• ❌ No robots.txt.
• ❌ No sitemap.xml / sitemap-index.xml.

Structured data (AEO)

• ❌ No JSON-LD on any page → AI engines (ChatGPT, Perplexity, Gemini AI Overviews) had no machine-readable identity for the project.
• ❌ No default Open Graph or Twitter card meta beyond what Starlight emits.

On-page SEO/AEO

• ⚠️ Page description frontmatter was very short, generic, and did not lead with a self-contained answer ("A simple library to query the DOM…", "The simple way to validate forms…").
• ⚠️ Deprecated pages (Stream, Form) had descriptions that didn't mention deprecation, so AI summaries may continue to recommend them.
• ⚠️ Page <title> values contained leading/trailing emoji (💾 Simple store, Simple stream 🌊) which read poorly in SERPs and AI citations.

Changes

• www/astro.config.mjs
  • Set site: "https://simple-stack.dev" and added @astrojs/sitemap integration.
  • Added Starlight description, favicon, and a head config that injects:
    • application/ld+json with an Organization + WebSite graph (sameAs linking to the GitHub org and Discord) for AI attribution.
    • <meta name="robots" content="index, follow, max-image-preview:large">.
    • <meta property="og:site_name" content="Simple Stack">.
    • <meta name="twitter:card" content="summary_large_image">.
• www/package.json: added @astrojs/sitemap@^3.6.0 (already in the workspace lockfile).
• www/public/robots.txt: new file allowing crawling and pointing to /sitemap-index.xml.
• Frontmatter rewrites across index.mdx, store.mdx, query.mdx, scope.mdx, stream.md, form/index.mdx, form/client.md, form/parse.md:
  • Removed emoji from page title (sidebar labels still keep their emoji).
  • Rewrote description to be answer-first, entity-rich, ~150 chars.
  • Prefixed deprecated-page descriptions with Deprecated: so AI summaries reflect their status.

Notes

• Verified astro.config.mjs syntax loads after npm install. A full astro build fails on 404.astro due to a pre-existing zod/Starlight schema incompatibility on main (reproduced on the unmodified branch), unrelated to this PR. All docs pages transformed successfully (vite ✓ built).
• Sidebar labels intentionally still use emoji per the existing visual identity. Only the <title> / OG title strings were de-emojified.
• A future enhancement worth considering: per-page Article JSON-LD with datePublished / dateModified, and a custom social card image referenced via head og:image.

Conversation: https://app.warp.dev/conversation/115c1de7-a28f-4f75-9890-920ec467af16
Run: https://oz.warp.dev/runs/019dd351-2577-7859-ad8b-73e11b92c597

This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
simple-stack-docs	Error		Apr 28, 2026 9:29am

[changeset-bot]

⚠️ No Changeset found

Latest commit: e9f4afc

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR