From 8296bd97a5a8a8b24ce6b5aa4d4594f79687bcd4 Mon Sep 17 00:00:00 2001
From: KimHyeongRae0 <42205606+KimHyeongRae0@users.noreply.github.com>
Date: Thu, 7 May 2026 00:28:40 +0900
Subject: [PATCH 1/3] docs(api): align examples with exported signatures

---
 website/src/content/docs/features/audit.mdx   | 26 ++++---
 .../src/content/docs/features/schema-og.mdx   | 15 ++--
 website/src/content/docs/reference/api.mdx    | 70 ++++++++++++++-----
 3 files changed, 80 insertions(+), 31 deletions(-)

diff --git a/website/src/content/docs/features/audit.mdx b/website/src/content/docs/features/audit.mdx
index 2106b95..d41c891 100644
--- a/website/src/content/docs/features/audit.mdx
+++ b/website/src/content/docs/features/audit.mdx
@@ -8,12 +8,18 @@ description: Audit your AEO setup and measure your site's citability score.
 The `auditSite` function checks your site for AEO best practices and returns a detailed report:
 
 ```ts
-import { auditSite, formatAuditReport, getGrade } from 'aeo.js';
+import { auditSite, formatAuditReport, getGrade, resolveConfig } from 'aeo.js';
 
-const result = await auditSite('https://mysite.com');
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
+
+const result = auditSite(config);
 
 console.log(formatAuditReport(result));
-console.log('Grade:', getGrade(result));
+console.log('Grade:', getGrade(result.score));
 ```
 
 The audit checks for:
@@ -38,11 +44,15 @@ Measure how likely AI engines are to cite your content:
 import { scorePageCitability, scoreSiteCitability, formatPageCitability } from 'aeo.js';
 
 // Score a single page
-const pageScore = await scorePageCitability(url, html);
+const pageScore = scorePageCitability({
+  pathname: '/',
+  title: 'Home',
+  content: '# Home\n\nMy site publishes practical guides for AI-ready content.',
+});
 console.log(formatPageCitability(pageScore));
 
 // Score the whole site
-const siteScore = await scoreSiteCitability('https://mysite.com', pages);
+const siteScore = scoreSiteCitability(config);
 ```
 
 The citability score evaluates:
@@ -60,7 +70,7 @@ Generate a comprehensive AEO report:
 ```ts
 import { generateReport, formatReportMarkdown, formatReportJson } from 'aeo.js';
 
-const report = await generateReport(config);
+const report = generateReport(config);
 
 // Get as markdown
 console.log(formatReportMarkdown(report));
@@ -76,6 +86,6 @@ Get platform-specific optimization suggestions:
 ```ts
 import { generatePlatformHints } from 'aeo.js';
 
-const hints = generatePlatformHints('next');
-// Returns hints specific to Next.js optimization
+const hints = generatePlatformHints(result, siteScore);
+// Returns platform-specific optimization hints for ChatGPT, Perplexity, Google AI, and Bing Copilot
 ```
diff --git a/website/src/content/docs/features/schema-og.mdx b/website/src/content/docs/features/schema-og.mdx
index ff90d01..4845e9b 100644
--- a/website/src/content/docs/features/schema-og.mdx
+++ b/website/src/content/docs/features/schema-og.mdx
@@ -63,21 +63,26 @@ This generates meta tags like:
 
 ## Programmatic API
 
+The lower-level helpers expect a resolved config and a page entry.
+
 ```ts
-import { generateSchema, generateSchemaObjects, generateJsonLdScript } from 'aeo.js';
+import { generateSchemaObjects, generateJsonLdScript } from 'aeo.js';
 import { generateOGTags, generateOGTagsHtml } from 'aeo.js';
 
 // Get schema objects
-const schemas = generateSchemaObjects(config);
+const schemas = generateSchemaObjects(resolvedConfig);
 
 // Get a <script> tag string
-const script = generateJsonLdScript(config);
+const script = generateJsonLdScript([
+  ...schemas.site,
+  ...(schemas.pages[page.pathname] ?? []),
+]);
 
 // Get OG meta tag objects
-const tags = generateOGTags(config, page);
+const tags = generateOGTags(page, resolvedConfig);
 
 // Get OG meta tags as HTML string
-const html = generateOGTagsHtml(config, page);
+const html = generateOGTagsHtml(page, resolvedConfig);
 ```
 
 <Aside type="tip">
diff --git a/website/src/content/docs/reference/api.mdx b/website/src/content/docs/reference/api.mdx
index e20dce3..3b4e17a 100644
--- a/website/src/content/docs/reference/api.mdx
+++ b/website/src/content/docs/reference/api.mdx
@@ -43,6 +43,8 @@ const resolved = resolveConfig({ title: 'My Site' });
 // All fields now have defaults
 ```
 
+The examples below use `resolvedConfig` for a config object returned by `resolveConfig`.
+
 ### `validateConfig(config)`
 
 Validate a config object and return any errors:
@@ -66,15 +68,19 @@ const info = detectFramework();
 
 ## HTML Extraction
 
-### `htmlToMarkdown(html)`
+### `htmlToMarkdown(html, pagePath, config)`
 
 Convert HTML to clean markdown:
 
 ```ts
 import { htmlToMarkdown } from 'aeo.js';
 
-const md = htmlToMarkdown('<h1>Hello</h1><p>World</p>');
-// '# Hello\n\nWorld'
+const md = htmlToMarkdown(
+  '<html><head><title>Hello</title></head><body><main><p>World</p></main></body></html>',
+  '/',
+  { url: 'https://mysite.com' }
+);
+// Returns a markdown document with YAML frontmatter
 ```
 
 ### `extractTextFromHtml(html)`
@@ -107,65 +113,79 @@ import { generateSchemaObjects } from 'aeo.js';
 const schemas = generateSchemaObjects(resolvedConfig);
 ```
 
-### `generateJsonLdScript(config)`
+### `generateJsonLdScript(schemas)`
 
 Generate a `<script type="application/ld+json">` tag:
 
 ```ts
-import { generateJsonLdScript } from 'aeo.js';
+import { generateJsonLdScript, generateSiteSchemas } from 'aeo.js';
 
-const script = generateJsonLdScript(resolvedConfig);
+const schemas = generateSiteSchemas(resolvedConfig);
+const script = generateJsonLdScript(schemas);
 ```
 
-### `generateSiteSchemas(config)` / `generatePageSchemas(config, page)`
+### `generateSiteSchemas(config)` / `generatePageSchemas(page, config)`
 
 Generate schemas for the site or individual pages.
 
 ## Open Graph
 
-### `generateOGTags(config, page)`
+### `generateOGTags(page, config)`
 
 Returns an array of `MetaTag` objects:
 
 ```ts
 import { generateOGTags } from 'aeo.js';
 
-const tags = generateOGTags(config, { pathname: '/', title: 'Home' });
+const tags = generateOGTags(
+  { pathname: '/', title: 'Home' },
+  resolvedConfig
+);
 // [{ property: 'og:title', content: 'Home' }, ...]
 ```
 
-### `generateOGTagsHtml(config, page)`
+### `generateOGTagsHtml(page, config)`
 
 Returns OG tags as an HTML string.
 
 ## Audit
 
-### `auditSite(url)`
+### `auditSite(config)`
 
 Audit a site for AEO best practices:
 
 ```ts
-import { auditSite, formatAuditReport, getGrade } from 'aeo.js';
+import { auditSite, formatAuditReport, getGrade, resolveConfig } from 'aeo.js';
 
-const result = await auditSite('https://mysite.com');
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
+
+const result = auditSite(config);
 console.log(formatAuditReport(result));
-console.log(getGrade(result)); // 'A', 'B', 'C', etc.
+console.log(getGrade(result.score)); // 'Excellent', 'Good', 'Fair', etc.
 ```
 
 ## Citability
 
-### `scorePageCitability(url, html)`
+### `scorePageCitability(page)`
 
 Score how likely a page is to be cited by AI:
 
 ```ts
 import { scorePageCitability, formatPageCitability } from 'aeo.js';
 
-const score = await scorePageCitability(url, html);
+const score = scorePageCitability({
+  pathname: '/',
+  title: 'Home',
+  content: '# Home\n\nMy site publishes practical guides for AI-ready content.',
+});
 console.log(formatPageCitability(score));
 ```
 
-### `scoreSiteCitability(url, pages)`
+### `scoreSiteCitability(config)`
 
 Score citability across your entire site.
 
@@ -178,10 +198,24 @@ Generate a comprehensive AEO report:
 ```ts
 import { generateReport, formatReportMarkdown } from 'aeo.js';
 
-const report = await generateReport(config);
+const report = generateReport(resolvedConfig);
 console.log(formatReportMarkdown(report));
 ```
 
+## Platform Hints
+
+### `generatePlatformHints(audit, citability)`
+
+Generate platform-specific optimization hints from audit and citability results:
+
+```ts
+import { auditSite, generatePlatformHints, scoreSiteCitability } from 'aeo.js';
+
+const audit = auditSite(resolvedConfig);
+const citability = scoreSiteCitability(resolvedConfig);
+const hints = generatePlatformHints(audit, citability);
+```
+
 ## Types
 
 All types are exported from the main entry:

From 4ef81492b0bc5951c918389cdbfcaa8e69d0ab77 Mon Sep 17 00:00:00 2001
From: KimHyeongRae0 <42205606+KimHyeongRae0@users.noreply.github.com>
Date: Sun, 10 May 2026 08:23:57 +0900
Subject: [PATCH 2/3] docs(audit): make examples self-contained

---
 website/src/content/docs/features/audit.mdx | 28 ++++++++++++++++++---
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/website/src/content/docs/features/audit.mdx b/website/src/content/docs/features/audit.mdx
index d41c891..12b1a6d 100644
--- a/website/src/content/docs/features/audit.mdx
+++ b/website/src/content/docs/features/audit.mdx
@@ -41,7 +41,7 @@ npx aeo.js check
 Measure how likely AI engines are to cite your content:
 
 ```ts
-import { scorePageCitability, scoreSiteCitability, formatPageCitability } from 'aeo.js';
+import { formatPageCitability, resolveConfig, scorePageCitability, scoreSiteCitability } from 'aeo.js';
 
 // Score a single page
 const pageScore = scorePageCitability({
@@ -52,6 +52,12 @@ const pageScore = scorePageCitability({
 console.log(formatPageCitability(pageScore));
 
 // Score the whole site
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
+
 const siteScore = scoreSiteCitability(config);
 ```
 
@@ -68,7 +74,13 @@ The citability score evaluates:
 Generate a comprehensive AEO report:
 
 ```ts
-import { generateReport, formatReportMarkdown, formatReportJson } from 'aeo.js';
+import { formatReportJson, formatReportMarkdown, generateReport, resolveConfig } from 'aeo.js';
+
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
 
 const report = generateReport(config);
 
@@ -84,8 +96,16 @@ console.log(formatReportJson(report));
 Get platform-specific optimization suggestions:
 
 ```ts
-import { generatePlatformHints } from 'aeo.js';
+import { auditSite, generatePlatformHints, resolveConfig, scoreSiteCitability } from 'aeo.js';
+
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
 
-const hints = generatePlatformHints(result, siteScore);
+const audit = auditSite(config);
+const citability = scoreSiteCitability(config);
+const hints = generatePlatformHints(audit, citability);
 // Returns platform-specific optimization hints for ChatGPT, Perplexity, Google AI, and Bing Copilot
 ```

From 05d55da4f3ee5fa3b1920194fab08c453d910e3a Mon Sep 17 00:00:00 2001
From: KimHyeongRae0 <42205606+KimHyeongRae0@users.noreply.github.com>
Date: Sun, 10 May 2026 08:28:56 +0900
Subject: [PATCH 3/3] docs(schema-og): declare programmatic api inputs

---
 .../src/content/docs/features/schema-og.mdx   | 23 +++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/website/src/content/docs/features/schema-og.mdx b/website/src/content/docs/features/schema-og.mdx
index 4845e9b..2c98d15 100644
--- a/website/src/content/docs/features/schema-og.mdx
+++ b/website/src/content/docs/features/schema-og.mdx
@@ -66,8 +66,27 @@ This generates meta tags like:
 The lower-level helpers expect a resolved config and a page entry.
 
 ```ts
-import { generateSchemaObjects, generateJsonLdScript } from 'aeo.js';
-import { generateOGTags, generateOGTagsHtml } from 'aeo.js';
+import {
+  generateJsonLdScript,
+  generateOGTags,
+  generateOGTagsHtml,
+  generateSchemaObjects,
+  resolveConfig,
+} from 'aeo.js';
+
+const page = {
+  pathname: '/page',
+  title: 'Page Title',
+  description: 'Page description',
+  content: 'Page content',
+};
+
+const resolvedConfig = resolveConfig({
+  title: 'My Company',
+  description: 'My company website',
+  url: 'https://mysite.com',
+  pages: [page],
+});
 
 // Get schema objects
 const schemas = generateSchemaObjects(resolvedConfig);