diff --git a/docs/README.md b/docs/README.md
new file mode 100755
index 0000000..642402b
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,431 @@
+# Framework Integration Guides
+
+Comprehensive guides for integrating aeo.js with popular web frameworks to optimize your site for AI search engines like ChatGPT, Claude, Perplexity, and more.
+
+## Overview
+
+aeo.js (Answer Engine Optimization) helps make your website discoverable and understandable by AI-powered search engines. These guides provide step-by-step instructions for integrating aeo.js with your preferred framework.
+
+## What is AEO?
+
+Answer Engine Optimization (AEO) is the process of optimizing your website to be better understood and indexed by AI search engines. Unlike traditional SEO which focuses on keyword rankings, AEO focuses on:
+
+- **Structured content** - Making your content machine-readable
+- **Semantic markup** - Using JSON-LD and schema.org
+- **AI discovery files** - Generating llms.txt, robots.txt, sitemaps
+- **Context signals** - Providing clear page descriptions and metadata
+
+## Supported Frameworks
+
+aeo.js provides native integrations for the following frameworks:
+
+| Framework | Guide | Integration Type | Status |
+|-----------|-------|------------------|--------|
+| Next.js | [nextjs.md](./nextjs.md) | Plugin + Middleware | ✅ Stable |
+| Astro | [astro.md](./astro.md) | Native Integration | ✅ Stable |
+| Nuxt | [nuxt.md](./nuxt.md) | Module | ✅ Stable |
+| Vite | [vite.md](./vite.md) | Plugin | ✅ Stable |
+| Angular | [angular.md](./angular.md) | Post-build | ✅ Stable |
+| Webpack | [webpack.md](./webpack.md) | Plugin | ✅ Stable |
+
+## Quick Start
+
+Choose your framework:
+
+### Next.js
+```bash
+npm install aeo.js
+```
+
+```js
+// next.config.mjs
+import { withAeo } from 'aeo.js/next';
+
+export default withAeo({
+ aeo: {
+ title: 'My Site',
+ description: 'Optimized for AI discovery',
+ url: 'https://mysite.com',
+ },
+});
+```
+
+[→ Full Next.js Guide](./nextjs.md)
+
+### Astro
+```bash
+npm install aeo.js
+```
+
+```js
+// astro.config.mjs
+import { aeoAstroIntegration } from 'aeo.js/astro';
+
+export default defineConfig({
+ integrations: [
+ aeoAstroIntegration({
+ title: 'My Site',
+ url: 'https://mysite.com',
+ }),
+ ],
+});
+```
+
+[→ Full Astro Guide](./astro.md)
+
+### Nuxt
+```bash
+npm install aeo.js
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+ modules: ['aeo.js/nuxt'],
+ aeo: {
+ title: 'My Site',
+ url: 'https://mysite.com',
+ },
+});
+```
+
+[→ Full Nuxt Guide](./nuxt.md)
+
+### Vite
+```bash
+npm install aeo.js
+```
+
+```js
+// vite.config.ts
+import { aeoVitePlugin } from 'aeo.js/vite';
+
+export default defineConfig({
+ plugins: [
+ aeoVitePlugin({
+ title: 'My Site',
+ url: 'https://mysite.com',
+ }),
+ ],
+});
+```
+
+[→ Full Vite Guide](./vite.md)
+
+### Angular
+```bash
+npm install aeo.js
+```
+
+```json
+{
+ "scripts": {
+ "build": "ng build",
+ "postbuild": "node -e \"import('aeo.js/angular').then(m => m.postBuild({ title: 'My App', url: 'https://myapp.com' }))\""
+ }
+}
+```
+
+[→ Full Angular Guide](./angular.md)
+
+### Webpack
+```bash
+npm install aeo.js
+```
+
+```js
+// webpack.config.js
+const { AeoWebpackPlugin } = require('aeo.js/webpack');
+
+module.exports = {
+ plugins: [
+ new AeoWebpackPlugin({
+ title: 'My Site',
+ url: 'https://mysite.com',
+ }),
+ ],
+};
+```
+
+[→ Full Webpack Guide](./webpack.md)
+
+## What Gets Generated?
+
+When you integrate aeo.js, it automatically generates:
+
+### 1. llms.txt
+A structured file that AI search engines use to understand your site's content and structure.
+
+```
+# My Site
+
+> Optimized for AI discovery
+
+## Site Information
+- URL: https://mysite.com
+- Description: A comprehensive resource for...
+- Last Updated: 2026-05-09
+
+## Pages
+- /about: About our company and mission
+- /blog: Technical articles and tutorials
+- /products: Our product offerings
+```
+
+### 2. Enhanced robots.txt
+```
+User-agent: *
+Allow: /
+
+User-agent: GPTBot
+Allow: /
+
+User-agent: Claude-Web
+Allow: /
+
+Sitemap: https://mysite.com/sitemap.xml
+```
+
+### 3. XML Sitemap
+```xml
+
+
+
+ https://mysite.com/
+ 2026-05-09
+ 1.0
+
+
+
+```
+
+### 4. JSON-LD Structured Data
+Automatically injects schema.org structured data into your pages:
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "WebSite",
+ "name": "My Site",
+ "url": "https://mysite.com",
+ "description": "Optimized for AI discovery"
+}
+```
+
+## Configuration Options
+
+All framework integrations accept the same `AeoConfig` shape:
+
+> All fields are optional in TypeScript, but **`url` should always be set** for production. Omitting it causes `sitemap.xml`, `llms.txt`, and JSON-LD to fall back to `https://example.com` (`validateConfig` will also warn).
+
+```typescript
+type AeoConfig = {
+ // Strongly recommended
+ title?: string; // Your site title (defaults to "My Site")
+ url?: string; // Your production URL (defaults to "https://example.com")
+
+ // Optional
+ description?: string; // Site description
+ contentDir?: string; // Directory of handwritten markdown
+ outDir?: string; // Where to write AEO files
+ pages?: PageEntry[]; // Explicit pages (mostly auto-discovered by plugins)
+
+ // Toggle individual generators (all default true)
+ generators?: {
+ robotsTxt?: boolean;
+ llmsTxt?: boolean;
+ llmsFullTxt?: boolean;
+ rawMarkdown?: boolean;
+ manifest?: boolean;
+ sitemap?: boolean;
+ aiIndex?: boolean;
+ schema?: boolean;
+ };
+
+ // robots.txt directives
+ robots?: {
+ allow?: string[]; // Default: ['/']
+ disallow?: string[];
+ crawlDelay?: number; // Seconds
+ sitemap?: string;
+ };
+
+ // JSON-LD structured data
+ schema?: {
+ enabled?: boolean;
+ organization?: {
+ name?: string;
+ url?: string;
+ logo?: string;
+ sameAs?: string[];
+ };
+ defaultType?: 'Article' | 'WebPage';
+ };
+
+ // Open Graph tags
+ og?: {
+ enabled?: boolean;
+ image?: string;
+ twitterHandle?: string;
+ type?: 'website' | 'article';
+ };
+
+ // The Human/AI widget injected into pages
+ widget?: {
+ enabled?: boolean;
+ position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+ size?: 'default' | 'small' | 'icon-only';
+ theme?: { background?: string; text?: string; accent?: string; badge?: string };
+ humanLabel?: string;
+ aiLabel?: string;
+ showBadge?: boolean;
+ };
+
+ // ai-index.json chunking & keyword extraction
+ aiIndex?: {
+ maxChunkLength?: number; // Default: 2000 (soft limit; splits on paragraph)
+ maxKeywords?: number; // Default: 10
+ };
+};
+
+type PageEntry = {
+ pathname: string; // e.g. '/about'
+ title?: string;
+ description?: string;
+ content?: string;
+};
+```
+
+> See [aeojs.org/reference/configuration](https://aeojs.org/reference/configuration/) for the full reference.
+
+## Common Use Cases
+
+### Blog / Content Site
+Perfect for making your articles discoverable by AI assistants:
+
+```js
+{
+ title: 'Tech Blog',
+ description: 'In-depth technical tutorials and guides',
+ schema: {
+ enabled: true, // Generates Article schema for FAQ/HowTo patterns
+ organization: { name: 'Tech Blog', url: 'https://techblog.com' },
+ },
+}
+```
+
+### Documentation Site
+Optimize technical documentation for AI-powered search:
+
+```js
+{
+ title: 'API Documentation',
+ description: 'Complete API reference and guides',
+ pages: [
+ { pathname: '/api', title: 'API Reference', description: 'Full endpoint reference' },
+ { pathname: '/guides', title: 'Getting Started Guides' },
+ ],
+}
+```
+
+### E-commerce Site
+Help AI understand your product catalog. Use `robots.disallow` to block crawler access to private routes (it does not remove them from generated AEO files; for those, scope `contentDir` instead):
+
+```js
+{
+ title: 'Online Store',
+ description: 'Quality products delivered fast',
+ robots: {
+ disallow: ['/checkout', '/account', '/api'],
+ },
+ schema: {
+ enabled: true,
+ organization: { name: 'My Store', url: 'https://mystore.com' },
+ },
+}
+```
+
+### SaaS Product
+Optimize your marketing site and product pages:
+
+```js
+{
+ title: 'My SaaS Product',
+ description: 'The best tool for...',
+ pages: [
+ { pathname: '/', title: 'Home' },
+ { pathname: '/features', title: 'Features' },
+ { pathname: '/pricing', title: 'Pricing' },
+ { pathname: '/docs', title: 'Documentation' },
+ ],
+}
+```
+
+## Best Practices
+
+1. **Set accurate metadata** - Provide clear, descriptive titles and descriptions
+2. **Use semantic HTML** - Structure your content with proper headings
+3. **Include alt text** - Describe images for better AI understanding
+4. **Add structured data** - Use JSON-LD for rich content markup
+5. **Keep content fresh** - Update llms.txt when content changes
+6. **Test with AI** - Ask ChatGPT or Claude about your site
+7. **Monitor performance** - Track AI referrals in analytics
+
+## Troubleshooting
+
+### Files not generating?
+
+Check that:
+- Build process completes successfully
+- Output directory has write permissions
+- Configuration is valid
+
+### AI not finding my site?
+
+Ensure:
+- llms.txt is publicly accessible at `/llms.txt`
+- robots.txt allows AI crawlers
+- Sitemap is linked in robots.txt
+- DNS and SSL are properly configured
+
+### Framework-specific issues?
+
+See the detailed framework guides:
+- [Next.js Troubleshooting](./nextjs.md#troubleshooting)
+- [Astro Troubleshooting](./astro.md#troubleshooting)
+- [Nuxt Troubleshooting](./nuxt.md#troubleshooting)
+- [Vite Troubleshooting](./vite.md#troubleshooting)
+
+## Migration Guides
+
+### From Manual AEO
+If you've been manually creating llms.txt and robots.txt:
+
+1. Remove manual files from your public directory
+2. Install and configure aeo.js
+3. Run build to generate files automatically
+4. Verify generated files match your requirements
+5. Commit the configuration, delete manual files
+
+### From Other AEO Tools
+Coming soon - guides for migrating from other AEO solutions.
+
+## Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/multivmlabs/aeo.js/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/multivmlabs/aeo.js/discussions)
+- **Updates**: Follow [@multivmlabs](https://twitter.com/multivmlabs)
+
+## Contributing
+
+Found a better way to configure aeo.js for your framework? Have an example to share?
+
+We welcome contributions! See the main [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT - See [LICENSE](../LICENSE) for details.
+
+---
+
+**Ready to optimize your site for AI discovery? Choose your framework guide above and get started!**
diff --git a/docs/angular.md b/docs/angular.md
new file mode 100644
index 0000000..bed46db
--- /dev/null
+++ b/docs/angular.md
@@ -0,0 +1,280 @@
+# Angular Integration Guide
+
+Make your Angular site discoverable by AI search engines like ChatGPT, Claude, Perplexity, and SearchGPT.
+
+## Prerequisites
+
+- Node.js 18+
+- An Angular 15+ project (works with both standalone components and `NgModule` projects)
+- TypeScript is the default for Angular
+
+## Installation
+
+```bash
+npm install aeo.js
+# or
+yarn add aeo.js
+# or
+pnpm add aeo.js
+```
+
+## Quick Start
+
+The Angular integration is a **post-build** step: after `ng build` produces your `dist/` output, `aeo.js/angular` scans the emitted HTML and writes AEO files alongside them.
+
+### Step 1: Add the post-build script
+
+```json
+{
+ "scripts": {
+ "build": "ng build",
+ "postbuild": "node -e \"import('aeo.js/angular').then(m => m.postBuild({ title: 'My App', url: 'https://myapp.com' }))\""
+ }
+}
+```
+
+npm automatically runs `postbuild` after `build`, so a single `npm run build` produces the Angular bundle **and** the AEO files.
+
+### Step 2: Build and verify
+
+```bash
+npm run build
+```
+
+You should now have these files inside your Angular `outputPath` (typically `dist//browser` for Angular 17+):
+
+- `robots.txt` — AI crawler directives
+- `llms.txt` — short summary for LLMs
+- `llms-full.txt` — full content dump
+- `sitemap.xml` — sitemap
+- `ai-index.json` — chunked content for embedding
+- `docs.json` — site manifest
+- `schema.json` — JSON-LD structured data (when `schema.enabled`)
+- Per-page `.md` files (when `generators.rawMarkdown` is enabled)
+
+## Configuration
+
+### Basic Configuration
+
+`postBuild` and `generate` accept the standard `AeoConfig`. The minimum useful shape:
+
+```typescript
+type AeoConfig = {
+ title?: string; // Strongly recommended (defaults to "My Site")
+ url?: string; // Strongly recommended (your production URL)
+ description?: string; // Recommended
+ outDir?: string; // Output directory (defaults to detected Angular dist)
+};
+```
+
+> Although `title` and `url` are optional in the type, omitting `url` causes `sitemap.xml`, `llms.txt`, and JSON-LD to fall back to `https://example.com`. Always set it for production builds. See [README.md](./README.md#configuration-options) for the full reference.
+
+### Advanced Configuration
+
+```json
+{
+ "scripts": {
+ "postbuild": "node ./scripts/aeo.mjs"
+ }
+}
+```
+
+```js
+// scripts/aeo.mjs
+import { postBuild } from 'aeo.js/angular';
+
+await postBuild({
+ title: 'My App',
+ description: 'An Angular app optimized for AI discovery',
+ url: 'https://myapp.com',
+
+ generators: {
+ robotsTxt: true,
+ llmsTxt: true,
+ llmsFullTxt: true,
+ sitemap: true,
+ aiIndex: true,
+ schema: true,
+ rawMarkdown: true,
+ },
+
+ schema: {
+ enabled: true,
+ organization: {
+ name: 'My Company',
+ url: 'https://myapp.com',
+ },
+ },
+
+ aiIndex: {
+ maxChunkLength: 2000,
+ maxKeywords: 10,
+ },
+});
+```
+
+### `postBuild` vs `generate`
+
+| Function | Scans build HTML? | Use it when |
+|---|---|---|
+| `postBuild(config)` | ✅ Yes, plus `src/app/**/*.routes.ts` | You ran `ng build` and want AEO files generated from the actual emitted HTML |
+| `generate(config)` | ❌ No — source routes only | Build output isn't available (dev/CI scripts, route discovery only) |
+
+`postBuild` is what you want for almost everything. `generate` is the lower-level escape hatch.
+
+```js
+// scripts/aeo-source-only.mjs
+import { generate } from 'aeo.js/angular';
+
+await generate({
+ title: 'My App',
+ url: 'https://myapp.com',
+ outDir: 'dist/my-app/browser',
+});
+```
+
+### Inject the Widget
+
+The Human/AI widget is **injected by default** when `widget.enabled !== false`. The Quick Start example above will already inject it into `index.html`. To customize the widget appearance:
+
+```js
+import { postBuild } from 'aeo.js/angular';
+
+await postBuild({
+ title: 'My App',
+ url: 'https://myapp.com',
+ widget: {
+ enabled: true, // default
+ position: 'bottom-right',
+ size: 'small',
+ },
+});
+```
+
+To **disable** widget injection without touching widget config elsewhere:
+
+```js
+await postBuild({
+ title: 'My App',
+ url: 'https://myapp.com',
+ injectWidget: false,
+});
+```
+
+## How It Works
+
+1. `ng build` produces a static `dist//browser` directory.
+2. The post-build hook fires; aeo.js does **two** scans:
+ - Walks the build output for `*.html` files (skipping `404.html` / `500.html`, `assets/`, `media/`). For each page it extracts the ``, meta description, and rendered text content.
+ - Walks `src/app` for `*.routes.ts` files and extracts the `path:` values declared in route configs. These add route entries to `sitemap.xml` even when no HTML was prerendered.
+3. The two sets are merged: build-output pages (with content) take priority over source-scanned routes.
+4. It writes the AEO files (`llms.txt`, `sitemap.xml`, etc.) into the same `dist` directory.
+
+For projects using **Angular Universal** (SSR) or **prerendering**, the prerendered HTML is what gets scanned — which is exactly the content AI crawlers see, so generation is accurate.
+
+## Common Setups
+
+### Angular 17+ Standalone Components
+
+No special configuration needed. The post-build script reads whatever HTML Angular emits.
+
+### Angular 16 and Below (`NgModule`)
+
+Same setup — the post-build script is build-pipeline-agnostic.
+
+### Multi-project Workspaces
+
+If your workspace has multiple Angular projects, point `outDir` at each one's output directory:
+
+```js
+// scripts/aeo-all.mjs
+import { postBuild } from 'aeo.js/angular';
+
+for (const project of ['app-a', 'app-b']) {
+ await postBuild({
+ title: `My ${project}`,
+ url: `https://${project}.example.com`,
+ outDir: `dist/${project}/browser`,
+ });
+}
+```
+
+### Angular with SSR / Prerendering
+
+Make sure the post-build script runs **after** prerendering produces the final HTML.
+
+**Angular 17+** (prerendering is configured in `angular.json` under the build target):
+
+```json
+{
+ "scripts": {
+ "build": "ng build",
+ "postbuild": "node -e \"import('aeo.js/angular').then(m => m.postBuild({ title: 'My App', url: 'https://myapp.com' }))\""
+ }
+}
+```
+
+**Angular 16 and below** (separate prerender command):
+
+```json
+{
+ "scripts": {
+ "build": "ng build && ng run my-app:prerender",
+ "postbuild": "node -e \"import('aeo.js/angular').then(m => m.postBuild({ title: 'My App', url: 'https://myapp.com' }))\""
+ }
+}
+```
+
+## Best Practices
+
+- **Set `url` to your production hostname.** It seeds `sitemap.xml`, absolute URLs in `llms.txt`, and JSON-LD.
+- **Prerender as many routes as you can.** Without prerendering, declared routes from `*.routes.ts` still appear in `sitemap.xml` — but `llms.txt` / `ai-index.json` only carry content for pages that produced HTML. Prerendered routes get the full treatment.
+- **Add `pages` for routes not declared in `*.routes.ts`.** When the auto-scan misses a route (e.g. it's defined in code, not a route config), list it explicitly:
+
+ ```js
+ await postBuild({
+ title: 'My App',
+ url: 'https://myapp.com',
+ pages: [
+ { pathname: '/', title: 'Home' },
+ { pathname: '/pricing', title: 'Pricing' },
+ ],
+ });
+ ```
+- **Verify after deploy.** Visit `https://myapp.com/llms.txt`, `/robots.txt`, and `/sitemap.xml`.
+
+## Troubleshooting
+
+### `outDir` not found
+The post-build step reads `angular.json` to detect your output directory (typically `dist/<project>/browser` for Angular 17+, `dist/<project>` for older). If your workspace uses a non-standard layout, pass `outDir` explicitly. Top-level `await` works inside an `.mjs` file or any module with `"type": "module"`:
+
+```js
+// scripts/aeo.mjs
+import { postBuild } from 'aeo.js/angular';
+
+await postBuild({
+ title: 'My App',
+ url: 'https://myapp.com',
+ outDir: 'public',
+});
+```
+
+### `sitemap.xml` only contains the root URL
+The plugin scans **both** the build output for HTML **and** `src/app/**/*.routes.ts` for declared route paths, so an empty sitemap usually means both are empty:
+
+- No prerendering, **and** no `*.routes.ts` files found (e.g. routes defined inline in components or via `provideRouter([...])` in a non-routes file).
+- Fix one of: enable Angular prerendering, move routes into a `*.routes.ts` file, or pass `pages` explicitly (see [Add `pages` for routes not declared](#best-practices) above).
+
+### `llms.txt` text is empty
+The extractor strips scripts and boilerplate, prefers `<main>`. If your Angular template renders everything inside a custom root without `<main>`, AEO content extraction may produce empty pages. Wrap your routed view in `<main>`:
+```html
+<main>
+ <router-outlet></router-outlet>
+</main>
+```
+
+## Further Reading
+
+- [aeo.js Reference Configuration](https://aeojs.org/reference/configuration/)
+- [Generated Files](https://aeojs.org/features/generated-files/)
+- [GEO Audit & Citability](https://aeojs.org/features/audit/)
diff --git a/docs/astro.md b/docs/astro.md
new file mode 100755
index 0000000..b466c13
--- /dev/null
+++ b/docs/astro.md
@@ -0,0 +1,420 @@
+# Astro Integration Guide
+
+Complete guide for integrating aeo.js with Astro to optimize your site for AI-powered search engines.
+
+## Prerequisites
+
+- **Astro**: 3.0 or higher
+- **Node.js**: 18.0 or higher
+- **Package Manager**: npm, yarn, or pnpm
+
+## Installation
+
+### Step 1: Install aeo.js
+
+```bash
+npm install aeo.js
+# or
+yarn add aeo.js
+# or
+pnpm add aeo.js
+```
+
+### Step 2: Add Integration to Astro Config
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { aeoAstroIntegration } from 'aeo.js/astro';
+
+export default defineConfig({
+ site: 'https://mysite.com',
+ integrations: [
+ aeoAstroIntegration({
+ title: 'My Astro Site',
+ description: 'Built with Astro and optimized for AI discovery',
+ url: 'https://mysite.com',
+ }),
+ ],
+});
+```
+
+### Step 3: Build and Verify
+
+```bash
+npm run build
+```
+
+Check that these files were generated in your `dist` directory:
+- `dist/llms.txt`
+- `dist/robots.txt`
+- `dist/sitemap.xml`
+
+## Configuration
+
+### Basic Configuration
+
+`aeoAstroIntegration` accepts the standard `AeoConfig`. See [README.md](./README.md#configuration-options) for the full reference.
+
+### Advanced Configuration
+
+```javascript
+export default defineConfig({
+ site: 'https://mysite.com',
+ integrations: [
+ aeoAstroIntegration({
+ title: 'My Astro Site',
+ url: 'https://mysite.com',
+ description: 'Lightning-fast static site built with Astro',
+
+ // Toggle individual generators (all default true)
+ generators: {
+ llmsTxt: true,
+ llmsFullTxt: true,
+ robotsTxt: true,
+ sitemap: true,
+ aiIndex: true,
+ schema: true,
+ },
+
+ // Optional explicit page metadata (the plugin auto-discovers from src/pages/)
+ pages: [
+ { pathname: '/', title: 'Home', description: 'Welcome to our lightning-fast site' },
+ { pathname: '/blog', title: 'Blog', description: 'Latest articles' },
+ ],
+
+ // robots.txt — block crawlers from private routes
+ robots: {
+ allow: ['/'],
+ disallow: ['/admin', '/api'],
+ },
+
+ // JSON-LD structured data
+ schema: {
+ enabled: true,
+ organization: {
+ name: 'My Astro Site',
+ url: 'https://mysite.com',
+ },
+ },
+ }),
+ ],
+});
+```
+
+## Content Collections Integration
+
+Astro's content collections work seamlessly with aeo.js:
+
+```typescript
+// src/content/config.ts
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+ schema: z.object({
+ title: z.string(),
+ description: z.string(),
+ pubDate: z.date(),
+ author: z.string(),
+ tags: z.array(z.string()),
+ }),
+});
+
+export const collections = { blog };
+```
+
+## Adding Structured Data
+
+> Astro's `set:html` directive injects the value verbatim — it does **not** escape characters that can terminate the surrounding `<script>` tag. A schema value containing `</script>` (or U+2028/U+2029) would break out and execute as JavaScript. Run the payload through a serializer that escapes those characters first — the helper below is the same `serializeJsonForHtml` aeo.js uses internally ([src/core/schema.ts](https://github.com/multivmlabs/aeo.js/blob/main/src/core/schema.ts)). aeo.js's own injected JSON-LD is already safe; only your custom additions need this.
+
+```ts
+// src/lib/serialize-json-ld.ts
+export function serializeJsonForHtml(value: unknown): string {
+ return JSON.stringify(value)
+ .replace(/</g, '\\u003C')
+ .replace(/>/g, '\\u003E')
+ .replace(/&/g, '\\u0026')
+ .replace(/\u2028/g, '\\u2028')
+ .replace(/\u2029/g, '\\u2029');
+}
+```
+
+### Page-Level JSON-LD
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import { getEntry } from 'astro:content';
+import { serializeJsonForHtml } from '../lib/serialize-json-ld';
+
+const { slug } = Astro.params;
+if (!slug) return Astro.redirect('/404');
+const post = await getEntry('blog', slug);
+if (!post) return Astro.redirect('/404');
+
+const schema = {
+ '@context': 'https://schema.org',
+ '@type': 'BlogPosting',
+ headline: post.data.title,
+ description: post.data.description,
+ datePublished: post.data.pubDate.toISOString(),
+ author: {
+ '@type': 'Person',
+ name: post.data.author,
+ },
+};
+---
+
+<html>
+ <head>
+ <title>{post.data.title}
+
+
+
+
+
+ {post.data.title}
+
+
+
+