docs(www): SEO + AEO audit fixes (sitemap, robots, JSON-LD, noindex deprecated)

www/astro.config.mjs

@@ -1,10 +1,56 @@
+import sitemap from "@astrojs/sitemap";
 import starlight from "@astrojs/starlight";
 import { defineConfig } from "astro/config";
 
+const SITE_URL = "https://simple-stack.dev";
+
+// Site-wide JSON-LD describing the project as an Organization.
+// Helps AI engines (ChatGPT, Perplexity, Google AI Overviews) attribute
+// citations and disambiguate the brand.
+const organizationJsonLd = {
+	"@context": "https://schema.org",
+	"@type": "Organization",
+	name: "Simple Stack",
+	url: SITE_URL,
+	logo: `${SITE_URL}/favicon.svg`,
+	description:
+		"Simple Stack is a suite of small, focused tools for Astro and modern web frameworks, including Simple Store, Simple Scope, and Simple Query.",
+	sameAs: [
+		"https://github.com/bholmesdev/simple-stack",
+		"https://wtw.dev/chat",
+	],
+};
+
 export default defineConfig({
+	site: SITE_URL,
+	trailingSlash: "ignore",
 	integrations: [
 		starlight({
 			title: "Simple Stack 🌱",
+			description:
+				"Simple Stack is a suite of small, focused tools for Astro: Simple Store for reactive state, Simple Scope for build-time scoped IDs, and Simple Query for DOM scripting.",
+			favicon: "/favicon.svg",
+			head: [
+				// Canonical Twitter / OG defaults applied to every page.
+				{
+					tag: "meta",
+					attrs: { name: "twitter:card", content: "summary_large_image" },
+				},
+				{
+					tag: "meta",
+					attrs: { property: "og:site_name", content: "Simple Stack" },
+				},
+				{
+					tag: "meta",
+					attrs: { name: "robots", content: "index, follow, max-image-preview:large" },
+				},
+				// Organization structured data for AEO / rich results.
+				{
+					tag: "script",
+					attrs: { type: "application/ld+json" },
+					content: JSON.stringify(organizationJsonLd),
+				},
+			],
 			social: [
 				{
 					icon: "github",
@@ -44,5 +90,13 @@ export default defineConfig({
 				"./src/styles/custom.css",
 			],
 		}),
+		sitemap({
+			// Keep the sitemap aligned with indexable pages only. The deprecated
+			// stream and form docs set <meta name="robots" content="noindex">,
+			// so they should not be advertised to search engines.
+			filter: (page) =>
+				!page.startsWith(`${SITE_URL}/stream`) &&
+				!page.startsWith(`${SITE_URL}/form`),
+		}),
 	],
 });

www/package.json

@@ -17,6 +17,7 @@
 	},
 	"dependencies": {
 		"@astrojs/check": "^0.9.6",
+		"@astrojs/sitemap": "^3.6.0",
 		"@astrojs/starlight": "^0.37.1",
 		"@fontsource/atkinson-hyperlegible": "^5.0.18",
 		"astro": "^5.16.6",

www/public/robots.txt

@@ -0,0 +1,7 @@
+# https://simple-stack.dev/robots.txt
+# Allow all standard search engine and AI crawlers.
+User-agent: *
+Allow: /
+
+# Sitemap is generated by @astrojs/sitemap at build time.
+Sitemap: https://simple-stack.dev/sitemap-index.xml

www/src/content/docs/form/client.md

@@ -1,8 +1,14 @@
 ---
-title:  Add client validation
+title: Add client validation
 description: Add client validation to your forms
 sidebar:
   order: 3
+head:
+  # Deprecated package: keep the docs accessible but exclude from search engines.
+  - tag: meta
+    attrs:
+      name: robots
+      content: noindex, follow
 ---
 
 :::caution

www/src/content/docs/form/index.mdx

@@ -1,9 +1,15 @@
 ---
 title: Simple form
-description: The simple way to validate forms in your fullstack app. 
+description: The simple way to validate forms in your fullstack app.
 sidebar:
   label: Get started
   order: 1
+head:
+  # Deprecated package: keep the docs accessible but exclude from search engines.
+  - tag: meta
+    attrs:
+      name: robots
+      content: noindex, follow
 ---
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';

www/src/content/docs/form/parse.md

@@ -1,8 +1,14 @@
 ---
-title: Parse form requests 
+title: Parse form requests
 description: Validate forms server-side
 sidebar:
   order: 2
+head:
+  # Deprecated package: keep the docs accessible but exclude from search engines.
+  - tag: meta
+    attrs:
+      name: robots
+      content: noindex, follow
 ---
 
 :::caution

www/src/content/docs/index.mdx

@@ -1,15 +1,71 @@
 ---
 title: Simple stack 🌱
-description: A suite of tools built for Astro to simplify your workflow.
+description: "Simple Stack is a collection of small, focused tools for Astro: Simple Store for reactive state, Simple Scope for build-time scoped IDs, and Simple Query for DOM scripting."
 tableOfContents: false
 head:
-  - tag: title
-    content: Simple stack 🌱
+  - tag: meta
+    attrs:
+      property: "og:title"
+      content: "Simple Stack — small, focused tools for Astro"
+  - tag: meta
+    attrs:
+      property: "og:description"
+      content: "Simple Store, Simple Scope, and Simple Query: tiny libraries that solve a single use case in Astro and modern web apps."
+  - tag: script
+    attrs:
+      type: "application/ld+json"
+    content: |
+      {
+        "@context": "https://schema.org",
+        "@type": "FAQPage",
+        "mainEntity": [
+          {
+            "@type": "Question",
+            "name": "What is Simple Stack?",
+            "acceptedAnswer": {
+              "@type": "Answer",
+              "text": "Simple Stack is a collection of small, focused libraries for Astro and modern web frameworks. It includes Simple Store for reactive state, Simple Scope for build-time scoped IDs, and Simple Query for DOM scripting in Astro components."
+            }
+          },
+          {
+            "@type": "Question",
+            "name": "What does Simple Store do?",
+            "acceptedAnswer": {
+              "@type": "Answer",
+              "text": "Simple Store is a reactive store that combines the simplicity of signals with selector-style sub-stores you'd find in Zustand or Redux. It supports React, Next.js, and any framework with a Vite-based toolchain."
+            }
+          },
+          {
+            "@type": "Question",
+            "name": "What does Simple Scope do?",
+            "acceptedAnswer": {
+              "@type": "Answer",
+              "text": "Simple Scope is a Vite plugin that generates a stable, scoped ID for the current file at build time, with zero client-side JavaScript. It is useful for form label IDs and querying scoped DOM elements."
+            }
+          },
+          {
+            "@type": "Question",
+            "name": "What does Simple Query do?",
+            "acceptedAnswer": {
+              "@type": "Answer",
+              "text": "Simple Query is an Astro integration that adds a small, jQuery-like API for selecting elements inside an Astro component using data-target attributes, with built-in support for the Signals proposal via signal-polyfill."
+            }
+          },
+          {
+            "@type": "Question",
+            "name": "Which Simple Stack packages are still maintained?",
+            "acceptedAnswer": {
+              "@type": "Answer",
+              "text": "Simple Store, Simple Scope, and Simple Query are actively maintained. Simple Stream and Simple Form are deprecated; Astro's Server Islands and Form Actions cover those use cases natively."
+            }
+          }
+        ]
+      }
 ---
 
-A collection of tools I've built to **make web development simpler.**
+**Simple Stack is a collection of small, focused libraries for [Astro](https://astro.build) and modern web frameworks.** Each package solves one job well: [Simple Store](/store) for reactive state, [Simple Scope](/scope) for build-time scoped IDs, and [Simple Query](/query) for DOM scripting in Astro components.
 
-To be honest, there isn't a "story" connecting these packages together (I'm no TanStack). But they follow a common theme: solve a simple use case without too many features.
+There isn't a "story" connecting these packages together (I'm no TanStack). But they follow a common theme: solve a simple use case without too many features.
 
 import { CardGrid, Card, LinkCard } from '@astrojs/starlight/components';
 

www/src/content/docs/stream.md

@@ -1,6 +1,12 @@
 ---
 title: Simple stream 🌊
 description: Suspend Astro components with fallback content. Like React Server Components, but Just HTML ™️
+head:
+  # Deprecated package: keep the docs accessible but exclude from search engines.
+  - tag: meta
+    attrs:
+      name: robots
+      content: noindex, follow
 ---
 
 :::caution