@stackql/docusaurus-plugin-aeo 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.3.0
+
+Focused UX upgrade to the Ask AI button (feature 3). No changes to features 1, 2, or 4.
+
+### Changed (breaking)
+
+- Default Ask AI button placement moved from doc / blog footer to the breadcrumb row at the top of each page. On doc pages the button sits right-aligned in the breadcrumb row; on blog posts (which have no breadcrumbs) it sits right-aligned above the post title.
+- `askAi.placement` no longer accepts `'doc-footer'`. Valid values are `'breadcrumb-row'` (the new default) and `'none'`. The v0.1.x-v0.2.x `DocItem/Footer` and `BlogPostItem/Footer` swizzles have been deleted; there is no config flag that restores them. Consumers who want footer placement (or any other custom location) should set `askAi.placement: 'none'` and swizzle `@theme/AskAiButton` manually.
+- Ask AI button restyled as a solid pill dropdown (themed background, rounded-full corners, animated caret). The trigger reads "Ask AI about this page". The menu is a right-aligned card with rounded corners and a subtle shadow.
+
+### Changed
+
+- Provider icons replaced with real brand SVGs sourced from [simple-icons](https://simpleicons.org) where available - Claude, Perplexity, Gemini. OpenAI / ChatGPT was removed from simple-icons in 2024 following a takedown; the ChatGPT menu row renders a neutral chat-bubble glyph instead. No build failure; the missing icon is logged as a warning when verbose.
+
+### Added
+
+- `simple-icons` (`^16.22.0`, CC0-1.0) as a runtime dependency. Bundle-size impact is bounded by webpack tree-shaking: the icons module uses named ESM imports so only the three referenced icons end up in the production bundle.
+
+Even though placement changes are breaking, this is 0.3.0 (not 1.0.0) - the project is still pre-1.0 and the README never promised a stable placement option set.
+
+### Migration
+
+Bump the plugin version. If `askAi.placement: 'doc-footer'` is set in plugin options, remove it (or change it to `'breadcrumb-row'` for explicitness). No other config changes needed. After rebuild, the button appears at the top of each doc and blog page.
+
+## 0.2.0
+
+- Added: `llmsTxt.instanceSections` option for per-content-plugin-instance llms.txt section grouping. Use case: consumers with multiple content-docs instances (e.g. human docs + AI reference) can split them into named sections. Map keys are `"${pluginName}@${pluginId}"`; values are `{ title, order? }`. Unmapped instances are collected into a single appended "Other" section. `llms-full.txt` mirrors the same section structure as `llms.txt`.
+- No breaking changes: when `llmsTxt.instanceSections` is unset (the default), grouping is identical to v0.1.x — per content-plugin type, using `llmsTxt.sections` titles.
+
 ## 0.1.2
 
 Fix: cross-plugin loaded content was not captured because contentLoaded does not receive allContent in Docusaurus 3.x. Use allContentLoaded hook. Without this fix, feature 1 (.md companions) emitted zero files and feature 2 (llms.txt / llms-full.txt) was empty.

package/README.md

@@ -93,14 +93,89 @@ Options:
 | `llmsTxt.exclude` | `["/search", "/404", "/blog/tags/**", "/blog/page/**", "/blog/archive", "/blog/authors/**"]` | Route glob patterns to skip. |
 | `llmsTxt.include` | `null` | If set, only routes matching at least one pattern are included. Use for opt-in mode. |
 | `llmsTxt.header` | `null` | String prepended to `llms.txt` above the section list. Good for a project intro paragraph or links to key external resources. |
-| `llmsTxt.sections` | `{ docs: 'Documentation', blog: 'Blog', pages: 'Pages' }` | Section title overrides. |
+| `llmsTxt.sections` | `{ docs: 'Documentation', blog: 'Blog', pages: 'Pages' }` | Section title overrides for the default per-type grouping. |
+| `llmsTxt.instanceSections` | `null` | Per-content-plugin-instance section map. When set, supersedes `sections` (see below). |
 | `llmsTxt.fullTxt` | `true` | Emit `llms-full.txt`. |
 
 Glob patterns are matched against route permalinks. `**` matches across path segments; `*` matches within a single segment.
 
+### Per-instance sectioning
+
+By default, `llms.txt` groups by content-plugin TYPE: every `@docusaurus/plugin-content-docs` instance lands under one `## Documentation` heading, every blog instance under `## Blog`, and so on. This is fine for sites with a single docs instance, but it breaks down for sites that run multiple docs instances with different audiences — for example, one for human-facing docs at `/docs/*` and one for AI-targeted reference content at `/ai/*`. In that case, `llms.txt` and `llms-full.txt` interleave both surfaces under one heading, hiding the corpus shape from the crawlers and agents the file exists to serve.
+
+Set `llmsTxt.instanceSections` to switch to per-instance grouping. Keys are `"${pluginName}@${pluginId}"`; each value is `{ title, order? }`.
+
+Two content-docs instances + blog in `docusaurus.config.js`:
+
+```js
+module.exports = {
+  plugins: [
+    '@docusaurus/plugin-content-blog',           // id: 'default'
+    '@docusaurus/plugin-content-docs',           // id: 'default'
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        id: 'ai',
+        routeBasePath: '/ai',
+        path: 'ai-content',
+        sidebarPath: false,
+      },
+    ],
+    [
+      '@stackql/docusaurus-plugin-aeo',
+      {
+        llmsTxt: {
+          instanceSections: {
+            'docusaurus-plugin-content-docs@default': { title: 'Documentation', order: 1 },
+            'docusaurus-plugin-content-docs@ai':      { title: 'AI Reference',  order: 2 },
+            'docusaurus-plugin-content-blog@default': { title: 'Blog',          order: 3 },
+          },
+        },
+      },
+    ],
+  ],
+};
+```
+
+Resulting `llms.txt`:
+
+```text
+# Your site
+
+> Your tagline.
+
+## Documentation
+
+- [Getting started](/docs/intro/index.md): Install and run your first query.
+- [Providers](/docs/providers/index.md): Catalog of supported cloud APIs.
+
+## AI Reference
+
+- [What is StackQL](/ai/faqs/what-is-stackql/index.md): Canonical one-paragraph definition.
+- [Connecting to AWS](/ai/howto/connect-to-aws/index.md): Step-by-step authentication.
+
+## Blog
+
+- [Querying Snowflake](/blog/snowflake/index.md): ...
+```
+
+`llms-full.txt` mirrors the same section structure: each section's title is emitted as an `## H2` heading above its concatenated companion blocks, in the same order.
+
+Behavior:
+
+- Sections appear in ascending `order`. Ties break alphabetically by title. Entries with no `order` go last.
+- Instances not present in `instanceSections` are collected into a single appended `## Other` section, sorted alphabetically by page title. When `verbose: true`, each unmapped instance name is logged once so you notice and can map it.
+- `llmsTxt.sections` (the per-type titles) is ignored when `instanceSections` is set. When `verbose: true`, the plugin logs a one-line notice if both are configured.
+- When `instanceSections` is `null` (default), behavior is identical to v0.1.x: per-type grouping using `llmsTxt.sections` titles.
+
 ## Feature 3: "Ask AI" button
 
-A swizzle-friendly dropdown is injected above the existing `DocItem/Footer` and `BlogPostItem/Footer`. Each item opens the corresponding AI surface in a new tab with a prefilled prompt that references the current page's `.md` companion.
+A solid pill dropdown reading "Ask AI about this page" is injected at the top of every doc and blog-post content area, right-aligned in the breadcrumb row. Each item in the dropdown opens the corresponding AI surface in a new tab with a prefilled prompt that references the current page's `.md` companion.
+
+Placement specifics:
+
+- **Doc pages** - the button sits on the same row as the breadcrumb trail, flex-aligned to the right edge of the content area.
+- **Blog posts** - blog posts have no breadcrumbs, so the button sits at the very top of the post, right-aligned above the post title (the closest visual equivalent to the docs breadcrumb-row position).
 
 Providers and URL patterns:
 
@@ -119,6 +194,10 @@ Read https://your-site.example/path/to/page.md and help me with the following qu
 
 The trailing space is intentional - the cursor lands ready for the user to type.
 
+Provider icons are real brand SVGs sourced from [simple-icons](https://simpleicons.org). Three of four (Claude, Perplexity, Gemini) come from the upstream catalog directly. OpenAI / ChatGPT was removed from simple-icons in 2024 following a takedown, so the ChatGPT row shows a neutral chat-bubble glyph as a placeholder.
+
+**Trademark note.** Brand logos are trademarks of their respective owners; their inclusion via simple-icons does not imply endorsement. Consumers using the Ask AI button in commercial contexts should review each provider's brand-usage policy.
+
 Options:
 
 | Option | Default | Description |
@@ -126,17 +205,19 @@ Options:
 | `askAi.enabled` | `true` | When `false`, the theme components are not registered. |
 | `askAi.providerOrder` | `['claude', 'chatgpt', 'perplexity', 'gemini']` | Order of items in the dropdown. Drop entries to hide them. |
 | `askAi.promptTemplate` | `'Read {pageUrl}.md and help me with the following question about it: '` | Prompt sent to each provider. `{pageUrl}` is the page's canonical URL (no trailing slash). If feature 1 is disabled, the consumer should remove the `.md` from the template. |
-| `askAi.placement` | `'doc-footer'` | `'doc-footer'` injects above doc and blog footers. `'none'` does not register any theme components - swizzle manually if you want to place the button elsewhere. |
+| `askAi.placement` | `'breadcrumb-row'` | `'breadcrumb-row'` puts the button at the top of every doc/blog page (docs breadcrumb row, or above the blog title). `'none'` does not register any theme components - swizzle the button into your preferred location manually. |
 
-Styling uses CSS modules and reads from Docusaurus's theme tokens (`--ifm-color-primary`, etc.) so dark/light mode work automatically.
+Styling uses CSS modules and reads from Docusaurus's theme tokens (`--ifm-color-primary`, `--ifm-color-primary-darker`, `--ifm-color-emphasis-300`, etc.) so dark/light mode work automatically without extra rules.
 
-Swizzle to move the button:
+### Customizing placement
 
-```bash
-npm run swizzle @stackql/docusaurus-plugin-aeo AskAiButton -- --wrap
+To put the button somewhere other than the breadcrumb row - sidebar, header, a specific page region - set `askAi.placement: 'none'` to disable the bundled swizzles, then import and place the component manually wherever you want:
+
+```jsx
+import AskAiButton from '@theme/AskAiButton';
 ```
 
-The component lives at `@theme/AskAiButton`. Import and place it wherever you want.
+Wrap an existing theme component (e.g. `@theme/Layout`) the same way Docusaurus documents for any swizzle.
 
 ## Feature 4: `/ai/*` routing convention
 
@@ -255,11 +336,15 @@ The `sitemapExclude` helper, by contrast, does work with globs because `@docusau
     ],
     include: null,            // null = all not-excluded
     header: null,             // optional string prepended to llms.txt
-    sections: {
-      docs: 'Documentation',
+    sections: {               // per-type section titles (used when
+      docs: 'Documentation',  // instanceSections is null)
       blog: 'Blog',
       pages: 'Pages',
     },
+    instanceSections: null,   // per-instance section map, supersedes
+                              // sections when set. Shape:
+                              //   { '${pluginName}@${pluginId}':
+                              //       { title: string, order?: number } }
     fullTxt: true,            // emit llms-full.txt
   },
 
@@ -268,7 +353,7 @@ The `sitemapExclude` helper, by contrast, does work with globs because `@docusau
     enabled: true,
     providerOrder: ['claude', 'chatgpt', 'perplexity', 'gemini'],
     promptTemplate: 'Read {pageUrl}.md and help me with the following question about it: ',
-    placement: 'doc-footer',  // 'doc-footer' | 'none'
+    placement: 'breadcrumb-row',  // 'breadcrumb-row' | 'none'
   },
 
   // Feature 4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackql/docusaurus-plugin-aeo",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "AEO (Answer Engine Optimization) helpers for Docusaurus: .md companion files, llms.txt / llms-full.txt, an Ask AI dropdown, and /ai/* route conventions.",
   "main": "src/index.js",
   "exports": {
@@ -25,7 +25,8 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "gray-matter": "^4.0.3"
+    "gray-matter": "^4.0.3",
+    "simple-icons": "^16.22.0"
   },
   "overrides": {
     "serialize-javascript": "^7.0.5",

package/src/features/llmsTxt.js

@@ -52,6 +52,103 @@ function groupKind(kind, pluginId) {
   return 'pages';
 }
 
+function instanceKey(item) {
+  return `${item.pluginName}@${item.pluginId}`;
+}
+
+// Returns an ordered array of { key, title, items[] }. The same shape is
+// consumed by both llms.txt and llms-full.txt emitters so their section
+// structure stays in lock-step.
+function buildSections(filtered, options, verbose) {
+  if (options.instanceSections) {
+    if (verbose && options.sections && Object.keys(options.sections).length > 0) {
+      // Both options set is allowed; instanceSections wins. Log so the
+      // consumer isn't confused that their `sections` titles aren't
+      // appearing.
+      console.log(
+        '[plugin-aeo] llmsTxt: both `sections` and `instanceSections` are set; `instanceSections` takes precedence',
+      );
+    }
+
+    const mapped = new Map(); // key -> { title, order, items[] }
+    const unmapped = []; // items that don't match any configured instance
+    const seenUnmappedKeys = new Set();
+
+    for (const [key, cfg] of Object.entries(options.instanceSections)) {
+      mapped.set(key, { title: cfg.title, order: cfg.order, items: [] });
+    }
+
+    for (const item of filtered) {
+      const key = instanceKey(item);
+      if (mapped.has(key)) {
+        mapped.get(key).items.push(item);
+      } else {
+        unmapped.push(item);
+        if (verbose && !seenUnmappedKeys.has(key)) {
+          seenUnmappedKeys.add(key);
+          console.log(
+            `[plugin-aeo] llmsTxt: instance "${key}" is not in instanceSections; routing to "Other"`,
+          );
+        }
+      }
+    }
+
+    const sections = [];
+    const ordered = [...mapped.entries()]
+      .map(([key, v]) => ({
+        key,
+        title: v.title,
+        order: typeof v.order === 'number' ? v.order : Number.POSITIVE_INFINITY,
+        items: v.items,
+      }))
+      .sort((a, b) => {
+        if (a.order !== b.order) return a.order - b.order;
+        return a.title.localeCompare(b.title);
+      });
+
+    for (const s of ordered) {
+      if (s.items.length === 0) continue;
+      s.items.sort((a, b) => a.permalink.localeCompare(b.permalink));
+      sections.push({ key: s.key, title: s.title, items: s.items });
+    }
+
+    if (unmapped.length > 0) {
+      // Spec: unmapped items go in a single "Other" section, sorted by
+      // page title (alphabetical). Stable tiebreak on permalink.
+      unmapped.sort((a, b) => {
+        const at = a.title || a.permalink;
+        const bt = b.title || b.permalink;
+        const cmp = at.localeCompare(bt);
+        return cmp !== 0 ? cmp : a.permalink.localeCompare(b.permalink);
+      });
+      sections.push({ key: '__other__', title: 'Other', items: unmapped });
+    }
+
+    return sections;
+  }
+
+  // Default path - per-type grouping, identical to v0.1.x behavior.
+  const groups = { docs: [], blog: [], pages: [] };
+  for (const item of filtered) {
+    const g = groupKind(item.kind, item.pluginId);
+    groups[g].push(item);
+  }
+
+  const sections = [];
+  const order = [
+    ['docs', options.sections.docs],
+    ['blog', options.sections.blog],
+    ['pages', options.sections.pages],
+  ];
+  for (const [key, title] of order) {
+    const items = groups[key];
+    if (!items || items.length === 0) continue;
+    items.sort((a, b) => a.permalink.localeCompare(b.permalink));
+    sections.push({ key, title, items });
+  }
+  return sections;
+}
+
 module.exports = async function emitLlmsTxt({
   props,
   options,
@@ -73,12 +170,7 @@ module.exports = async function emitLlmsTxt({
     return true;
   });
 
-  // Group by kind.
-  const groups = { docs: [], blog: [], pages: [] };
-  for (const item of filtered) {
-    const g = groupKind(item.kind, item.pluginId);
-    groups[g].push(item);
-  }
+  const sections = buildSections(filtered, options, verbose);
 
   // Build llms.txt.
   const lines = [];
@@ -93,20 +185,10 @@ module.exports = async function emitLlmsTxt({
     lines.push('');
   }
 
-  const sectionOrder = [
-    ['docs', options.sections.docs],
-    ['blog', options.sections.blog],
-    ['pages', options.sections.pages],
-  ];
-
-  for (const [key, title] of sectionOrder) {
-    const items = groups[key];
-    if (!items || items.length === 0) continue;
-    lines.push(`## ${title}`);
+  for (const section of sections) {
+    lines.push(`## ${section.title}`);
     lines.push('');
-    // Stable order: by permalink.
-    items.sort((a, b) => a.permalink.localeCompare(b.permalink));
-    for (const item of items) {
+    for (const item of section.items) {
       const url = companionsEnabled
         ? companionUrl(item.permalink, trailingSlash)
         : item.permalink;
@@ -128,7 +210,8 @@ module.exports = async function emitLlmsTxt({
   }
 
   // Build llms-full.txt by concatenating the companion files that we just
-  // emitted in feature 1. Requires feature 1 to have been enabled.
+  // emitted in feature 1. Requires feature 1 to have been enabled. Section
+  // headings mirror llms.txt so an LLM can navigate the corpus by H2.
   if (options.fullTxt) {
     if (!companionsEnabled) {
       if (verbose) {
@@ -139,11 +222,10 @@ module.exports = async function emitLlmsTxt({
       return;
     }
 
-    const blocks = [];
-    for (const [key] of sectionOrder) {
-      const items = groups[key];
-      if (!items) continue;
-      for (const item of items) {
+    const sectionChunks = [];
+    for (const section of sections) {
+      const blocks = [];
+      for (const item of section.items) {
         let body;
         try {
           body = await fs.readFile(item.companionPath, 'utf8');
@@ -164,10 +246,12 @@ module.exports = async function emitLlmsTxt({
         ].join('\n');
         blocks.push(`${header}${body.trim()}\n`);
       }
+      if (blocks.length === 0) continue;
+      sectionChunks.push(`## ${section.title}\n\n${blocks.join('\n---\n\n')}`);
     }
 
     const fullPath = path.join(outDir, 'llms-full.txt');
-    await fs.writeFile(fullPath, blocks.join('\n---\n\n'), 'utf8');
+    await fs.writeFile(fullPath, sectionChunks.join('\n---\n\n'), 'utf8');
     if (verbose) {
       console.log(`[plugin-aeo] llmsTxt: wrote ${fullPath}`);
     }

package/src/index.js

@@ -41,13 +41,17 @@ function normalizeOptions(raw) {
         blog: llmsSections.blog || 'Blog',
         pages: llmsSections.pages || 'Pages',
       },
+      // Per-instance section map. Keys are "${pluginName}@${pluginId}".
+      // When set, supersedes `sections` and switches feature 2 from
+      // per-type grouping to per-instance grouping.
+      instanceSections: llmsTxt.instanceSections || null,
       fullTxt: llmsTxt.fullTxt !== false,
     },
     askAi: {
       enabled: askAi.enabled !== false,
       providerOrder: askAi.providerOrder || DEFAULT_PROVIDER_ORDER,
       promptTemplate: askAi.promptTemplate || DEFAULT_PROMPT_TEMPLATE,
-      placement: askAi.placement || 'doc-footer',
+      placement: askAi.placement || 'breadcrumb-row',
     },
     aiRoutes: {
       validate: aiRoutes.validate === true,
@@ -77,6 +81,36 @@ function validateOptions(opts) {
   if (opts.llmsTxt.header !== null && typeof opts.llmsTxt.header !== 'string') {
     errs.push('llmsTxt.header must be a string or null');
   }
+  if (opts.llmsTxt.instanceSections !== null) {
+    const is = opts.llmsTxt.instanceSections;
+    if (typeof is !== 'object' || Array.isArray(is)) {
+      errs.push(
+        'llmsTxt.instanceSections must be an object keyed by "${pluginName}@${pluginId}" or undefined',
+      );
+    } else {
+      for (const [key, value] of Object.entries(is)) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+          errs.push(
+            `llmsTxt.instanceSections["${key}"] must be an object with { title, order? }`,
+          );
+          continue;
+        }
+        if (typeof value.title !== 'string' || value.title.length === 0) {
+          errs.push(
+            `llmsTxt.instanceSections["${key}"].title must be a non-empty string`,
+          );
+        }
+        if (
+          value.order !== undefined &&
+          (typeof value.order !== 'number' || !Number.isFinite(value.order))
+        ) {
+          errs.push(
+            `llmsTxt.instanceSections["${key}"].order must be a finite number when set`,
+          );
+        }
+      }
+    }
+  }
 
   if (!Array.isArray(opts.askAi.providerOrder)) {
     errs.push('askAi.providerOrder must be an array');
@@ -92,9 +126,12 @@ function validateOptions(opts) {
   if (typeof opts.askAi.promptTemplate !== 'string') {
     errs.push('askAi.promptTemplate must be a string');
   }
-  if (!['doc-footer', 'none'].includes(opts.askAi.placement)) {
+  if (!['breadcrumb-row', 'none'].includes(opts.askAi.placement)) {
+    // 'doc-footer' was the v0.1.x-v0.2.x default and is no longer
+    // accepted in v0.3.0. The wrappers that implemented it have been
+    // removed. See CHANGELOG for migration notes.
     errs.push(
-      `askAi.placement must be "doc-footer" or "none", got "${opts.askAi.placement}"`,
+      `askAi.placement must be "breadcrumb-row" or "none", got "${opts.askAi.placement}"`,
     );
   }
 

package/src/theme/AskAiButton/icons.js

@@ -1,55 +1,72 @@
-// Hand-rolled minimal SVGs for the four supported AI providers. Glyphs only;
-// outer wrapper supplies size and color. Using `currentColor` so the icon
-// inherits theme colors via CSS.
+// Brand icons for the four supported AI providers.
+//
+// Three of four come from simple-icons (siClaude, siPerplexity,
+// siGooglegemini). OpenAI / ChatGPT was removed from simple-icons in
+// 2024 following a takedown, so for that one we ship a neutral inline
+// chat-bubble glyph. The same fallback path is reused for any future
+// icon that disappears from upstream.
+//
+// All icons render as a 24x24 viewBox SVG with `fill="currentColor"`,
+// so the menu CSS can size them via font-size or width/height and tint
+// them via the surrounding text color. ESM `import` is used so webpack
+// can tree-shake unused simple-icons exports out of the bundle.
 
-const React = require('react');
+import React from 'react';
+import { siClaude, siPerplexity, siGooglegemini } from 'simple-icons';
 
-function svg(children, viewBox = '0 0 24 24') {
+function svg(children) {
   return React.createElement(
     'svg',
     {
       xmlns: 'http://www.w3.org/2000/svg',
       width: '1em',
       height: '1em',
-      viewBox,
+      viewBox: '0 0 24 24',
       fill: 'currentColor',
+      role: 'img',
       'aria-hidden': 'true',
     },
     children,
   );
 }
 
-const ClaudeIcon = () =>
-  svg(
-    React.createElement('path', {
-      d: 'M5.5 17.5 9.6 6.6h2.6l4.1 10.9h-2.4l-.9-2.5h-3.9l-.9 2.5H5.5Zm4.6-4.5h2.8l-1.4-4-1.4 4Zm6.4 4.5V6.6h2.2v10.9h-2.2Z',
-    }),
-  );
+function fromSimpleIcons(si) {
+  if (!si || typeof si.path !== 'string') {
+    return GenericAiIcon;
+  }
+  return function BrandIcon() {
+    return svg(React.createElement('path', { d: si.path }));
+  };
+}
 
-const ChatGptIcon = () =>
-  svg(
+// Neutral chat-bubble glyph - used when a brand icon isn't available
+// upstream. Not a brand mark, no trademark concerns.
+function GenericAiIcon() {
+  return svg(
     React.createElement('path', {
-      d: 'M12 2a10 10 0 1 0 10 10A10 10 0 0 0 12 2Zm4.6 12.4-3.9 2.3a1.5 1.5 0 0 1-1.4 0L7.4 14.4a1.5 1.5 0 0 1-.7-1.3V8.6a1.5 1.5 0 0 1 .7-1.3l3.9-2.3a1.5 1.5 0 0 1 1.4 0l3.9 2.3a1.5 1.5 0 0 1 .7 1.3v4.5a1.5 1.5 0 0 1-.7 1.3ZM12 8.5l-3.2 1.8v3.4L12 15.5l3.2-1.8v-3.4Z',
+      d: 'M4 4h16a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2h-8l-5 4v-4H4a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2Zm3 6h2v2H7v-2Zm4 0h2v2h-2v-2Zm4 0h2v2h-2v-2Z',
     }),
   );
+}
 
-const PerplexityIcon = () =>
-  svg(
-    React.createElement('path', {
-      d: 'M12 2 3 7v10l9 5 9-5V7l-9-5Zm0 2.3 6.7 3.7L12 11.7 5.3 8 12 4.3ZM5 9.7l6 3.3v6.6l-6-3.3V9.7Zm14 0v6.6l-6 3.3V13l6-3.3Z',
-    }),
-  );
+const icons = {
+  claude: fromSimpleIcons(siClaude),
+  // simple-icons dropped OpenAI/ChatGPT in 2024; fall back to a neutral
+  // chat-bubble glyph rather than failing the build or shipping a guess
+  // at the wordmark.
+  chatgpt: GenericAiIcon,
+  perplexity: fromSimpleIcons(siPerplexity),
+  gemini: fromSimpleIcons(siGooglegemini),
+};
 
-const GeminiIcon = () =>
-  svg(
-    React.createElement('path', {
-      d: 'M12 2 9.5 9.5 2 12l7.5 2.5L12 22l2.5-7.5L22 12l-7.5-2.5L12 2Z',
-    }),
-  );
+if (typeof console !== 'undefined') {
+  for (const [name, icon] of Object.entries(icons)) {
+    if (icon === GenericAiIcon && name !== 'chatgpt') {
+      console.warn(
+        `[plugin-aeo] AskAiButton: brand icon for "${name}" missing from simple-icons; using generic AI glyph`,
+      );
+    }
+  }
+}
 
-module.exports = {
-  claude: ClaudeIcon,
-  chatgpt: ChatGptIcon,
-  perplexity: PerplexityIcon,
-  gemini: GeminiIcon,
-};
+export default icons;

package/src/theme/AskAiButton/index.jsx

@@ -81,7 +81,21 @@ export default function AskAiButton(props) {
         onClick={toggle}
       >
         <span>Ask AI about this page</span>
-        <span className={styles.caret}>{open ? '▲' : '▼'}</span>
+        <span
+          className={`${styles.caret}${open ? ` ${styles.caretOpen}` : ''}`}
+          aria-hidden="true"
+        >
+          {/* Inline chevron-down so we don't depend on a font glyph. */}
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="0.75em"
+            height="0.75em"
+            viewBox="0 0 24 24"
+            fill="currentColor"
+          >
+            <path d="M6 9l6 6 6-6H6z" />
+          </svg>
+        </span>
       </button>
       {open && (
         <ul className={styles.menu} role="menu">

package/src/theme/AskAiButton/styles.module.css

@@ -1,50 +1,58 @@
 .wrapper {
   position: relative;
   display: inline-block;
-  margin: 1.5rem 0;
 }
 
 .trigger {
   display: inline-flex;
   align-items: center;
   gap: 0.5rem;
-  padding: 0.5rem 1rem;
+  padding: 0.4rem 0.9rem;
   background: var(--ifm-color-primary);
   color: var(--ifm-color-primary-contrast-foreground, #fff);
-  border: 1px solid var(--ifm-color-primary-dark);
-  border-radius: var(--ifm-button-border-radius, 0.4rem);
-  font: inherit;
-  font-weight: 600;
+  border: none;
+  border-radius: 999px;
+  font-size: 0.875rem;
+  font-weight: 500;
+  line-height: 1.2;
   cursor: pointer;
-  transition: background-color 0.15s ease, transform 0.05s ease;
+  white-space: nowrap;
+  transition: background-color 0.15s ease;
 }
 
 .trigger:hover {
-  background: var(--ifm-color-primary-dark);
+  background: var(--ifm-color-primary-darker, var(--ifm-color-primary-dark));
 }
 
-.trigger:active {
-  transform: translateY(1px);
+.trigger:focus-visible {
+  outline: 2px solid var(--ifm-color-primary-light, currentColor);
+  outline-offset: 2px;
 }
 
 .caret {
+  display: inline-block;
   font-size: 0.7em;
-  opacity: 0.85;
+  opacity: 0.9;
+  transition: transform 0.15s ease;
+}
+
+.caretOpen {
+  transform: rotate(180deg);
 }
 
 .menu {
   position: absolute;
-  top: calc(100% + 0.25rem);
-  left: 0;
-  z-index: 50;
-  min-width: 12rem;
+  top: calc(100% + 0.4rem);
+  right: 0;
+  z-index: 100;
+  min-width: 200px;
   margin: 0;
   padding: 0.25rem 0;
   list-style: none;
   background: var(--ifm-background-surface-color, var(--ifm-background-color));
   border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: var(--ifm-button-border-radius, 0.4rem);
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
+  border-radius: 0.5rem;
+  box-shadow: 0 6px 24px -8px rgba(0, 0, 0, 0.18);
 }
 
 .item {
@@ -54,21 +62,26 @@
 .itemLink {
   display: flex;
   align-items: center;
-  gap: 0.6rem;
+  gap: 0.65rem;
   padding: 0.5rem 0.85rem;
-  color: var(--ifm-font-color-base);
+  color: var(--ifm-color-content, var(--ifm-font-color-base));
   text-decoration: none;
-  font-size: 0.95em;
+  font-size: 0.875rem;
 }
 
 .itemLink:hover {
   background: var(--ifm-color-emphasis-100);
+  color: var(--ifm-color-content, var(--ifm-font-color-base));
   text-decoration: none;
 }
 
 .icon {
   display: inline-flex;
   align-items: center;
-  font-size: 1.1em;
-  color: var(--ifm-color-primary);
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  font-size: 18px;
+  color: var(--ifm-color-content, var(--ifm-font-color-base));
+  flex: 0 0 auto;
 }

package/src/theme/BlogPostItem/Header/Title/index.jsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import Title from '@theme-init/BlogPostItem/Header/Title';
+import AskAiButton from '@theme/AskAiButton';
+import styles from './styles.module.css';
+
+// Mirror the docs breadcrumb-row placement: render a flex row above the
+// post title with the Ask AI button right-aligned. Blog posts have no
+// breadcrumbs, so the title block is the closest visual analog to the
+// docs "above the H1, top of content" position.
+export default function TitleWrapper(props) {
+  return (
+    <>
+      <div className={styles.row}>
+        <AskAiButton />
+      </div>
+      <Title {...props} />
+    </>
+  );
+}

package/src/theme/BlogPostItem/Header/Title/styles.module.css

@@ -0,0 +1,8 @@
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  margin-bottom: 0.5rem;
+}

package/src/theme/DocBreadcrumbs/index.jsx

@@ -0,0 +1,17 @@
+import React from 'react';
+// See note in the AskAiButton swizzle: @theme-init resolves to the
+// initial component from the theme chain (theme-classic), avoiding the
+// recursion that @theme-original produces when a plugin (not a theme)
+// is the only contributor in the wrapper layer.
+import DocBreadcrumbs from '@theme-init/DocBreadcrumbs';
+import AskAiButton from '@theme/AskAiButton';
+import styles from './styles.module.css';
+
+export default function DocBreadcrumbsWrapper(props) {
+  return (
+    <div className={styles.row}>
+      <DocBreadcrumbs {...props} />
+      <AskAiButton />
+    </div>
+  );
+}

package/src/theme/DocBreadcrumbs/styles.module.css

@@ -0,0 +1,8 @@
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  margin-bottom: 1rem;
+}

package/src/theme/BlogPostItem/Footer/index.jsx

@@ -1,15 +0,0 @@
-import React from 'react';
-// See note in src/theme/DocItem/Footer/index.jsx - @theme-init avoids the
-// SSR recursion that @theme-original triggers when a plugin (not a theme)
-// contributes the wrapper.
-import Footer from '@theme-init/BlogPostItem/Footer';
-import AskAiButton from '@theme/AskAiButton';
-
-export default function FooterWrapper(props) {
-  return (
-    <>
-      <AskAiButton />
-      <Footer {...props} />
-    </>
-  );
-}

package/src/theme/DocItem/Footer/index.jsx

@@ -1,17 +0,0 @@
-import React from 'react';
-// Use @theme-init (the initial component from the theme chain, before any
-// wrappers) instead of @theme-original. When a plugin contributes both the
-// wrapper and is the only contributor in the wrapper layer,
-// @theme-original/X resolves back to this wrapper file and renders infinitely
-// on every SSR pass. @theme-init/X always resolves to the un-wrapped origin.
-import Footer from '@theme-init/DocItem/Footer';
-import AskAiButton from '@theme/AskAiButton';
-
-export default function FooterWrapper(props) {
-  return (
-    <>
-      <AskAiButton />
-      <Footer {...props} />
-    </>
-  );
-}