@stackql/docusaurus-plugin-aeo 0.4.1 → 0.5.0

package/src/index.js

@@ -1,6 +1,8 @@
 const path = require('path');
 const emitCompanions = require('./features/companions');
+const { collectCompanionItems } = require('./features/companions');
 const emitLlmsTxt = require('./features/llmsTxt');
+const injectAlternateLinks = require('./features/alternateLinks');
 const { validateAiRoutes } = require('./features/aiRoutes');
 
 const DEFAULT_LLMS_EXCLUDE = [
@@ -12,10 +14,10 @@ const DEFAULT_LLMS_EXCLUDE = [
   '/blog/authors/**',
 ];
 
-const DEFAULT_PROVIDER_ORDER = ['claude', 'chatgpt', 'perplexity', 'gemini'];
+const DEFAULT_PROVIDER_ORDER = ['claude', 'chatgpt', 'perplexity'];
 const VALID_PROVIDERS = new Set(DEFAULT_PROVIDER_ORDER);
 const DEFAULT_PROMPT_TEMPLATE =
-  'Read {pageUrl}.md and help me with the following question about it: ';
+  'Read {companionUrl} and help me understand it. Summarize the key points, then ask me one clarifying question to dig deeper.';
 
 function normalizeOptions(raw) {
   const opts = raw || {};
@@ -28,8 +30,13 @@ function normalizeOptions(raw) {
   return {
     companions: {
       enabled: companions.enabled !== false,
-      format: companions.format || 'raw',
+      format: companions.format || 'plain',
       exclude: companions.exclude || [],
+      // <link rel="alternate" type="text/markdown"> in every page that has
+      // a companion, and optionally the same as a Link header via a
+      // Netlify-style _headers file.
+      alternateLink: companions.alternateLink !== false,
+      linkHeader: companions.linkHeader === true,
     },
     llmsTxt: {
       enabled: llmsTxt.enabled !== false,
@@ -45,7 +52,10 @@ function normalizeOptions(raw) {
       // When set, supersedes `sections` and switches feature 2 from
       // per-type grouping to per-instance grouping.
       instanceSections: llmsTxt.instanceSections || null,
-      fullTxt: llmsTxt.fullTxt !== false,
+      // true (everything), false, or { include: ['<plugin>@<id>'], maxBytes }
+      fullTxt: llmsTxt.fullTxt === undefined ? true : llmsTxt.fullTxt,
+      // "## Optional" section in llms.txt pointing at llms-full.txt
+      linkFullTxt: llmsTxt.linkFullTxt !== false,
     },
     askAi: {
       enabled: askAi.enabled !== false,
@@ -63,11 +73,33 @@ function normalizeOptions(raw) {
 function validateOptions(opts) {
   const errs = [];
 
-  if (!['raw', 'plain'].includes(opts.companions.format)) {
+  if (!['raw', 'plain', 'clean'].includes(opts.companions.format)) {
     errs.push(
-      `companions.format must be "raw" or "plain", got "${opts.companions.format}"`,
+      `companions.format must be "plain" (or its synonym "clean") or "raw", got "${opts.companions.format}"`,
     );
   }
+  if (typeof opts.companions.alternateLink !== 'boolean') {
+    errs.push('companions.alternateLink must be a boolean');
+  }
+  if (typeof opts.companions.linkHeader !== 'boolean') {
+    errs.push('companions.linkHeader must be a boolean');
+  }
+  const ft = opts.llmsTxt.fullTxt;
+  if (typeof ft !== 'boolean') {
+    if (!ft || typeof ft !== 'object' || Array.isArray(ft)) {
+      errs.push('llmsTxt.fullTxt must be a boolean or an object { include?: string[], maxBytes?: number }');
+    } else {
+      if (ft.include !== undefined && (!Array.isArray(ft.include) || ft.include.some((k) => typeof k !== 'string'))) {
+        errs.push('llmsTxt.fullTxt.include must be an array of "<plugin>@<id>" strings');
+      }
+      if (ft.maxBytes !== undefined && (!Number.isFinite(ft.maxBytes) || ft.maxBytes <= 0)) {
+        errs.push('llmsTxt.fullTxt.maxBytes must be a positive number');
+      }
+    }
+  }
+  if (typeof opts.llmsTxt.linkFullTxt !== 'boolean') {
+    errs.push('llmsTxt.linkFullTxt must be a boolean');
+  }
   if (!Array.isArray(opts.companions.exclude)) {
     errs.push('companions.exclude must be an array of glob patterns');
   }
@@ -117,8 +149,12 @@ function validateOptions(opts) {
   } else {
     for (const p of opts.askAi.providerOrder) {
       if (!VALID_PROVIDERS.has(p)) {
+        const hint =
+          p === 'gemini'
+            ? '. Gemini was removed in 0.4.2 because gemini.google.com does not accept URL-encoded prompts'
+            : '';
         errs.push(
-          `askAi.providerOrder contains unknown provider "${p}". Valid: ${[...VALID_PROVIDERS].join(', ')}`,
+          `askAi.providerOrder contains unknown provider "${p}"${hint}. Valid providers: ${[...VALID_PROVIDERS].join(', ')}`,
         );
       }
     }
@@ -156,10 +192,10 @@ module.exports = function pluginAeo(context, rawOptions) {
   const plugin = {
     name: '@stackql/docusaurus-plugin-aeo',
 
-    // Surface the askAi config to theme components. setGlobalData MUST be
-    // called from contentLoaded - Docusaurus does not accept it from
-    // allContentLoaded, and theme components read it via
-    // usePluginData('@stackql/docusaurus-plugin-aeo') at render time.
+    // Surface the askAi config to theme components, which read it via
+    // usePluginData('@stackql/docusaurus-plugin-aeo') at render time. The
+    // companion route list is added from allContentLoaded below; Docusaurus
+    // merges global data set from the two hooks (shallow, per plugin).
     async contentLoaded({ actions }) {
       await actions.setGlobalData({
         askAi: {
@@ -176,7 +212,7 @@ module.exports = function pluginAeo(context, rawOptions) {
     // allContentLoaded in Docusaurus 3.x. contentLoaded receives only the
     // current plugin's own content, so feature 1 needs this hook to see
     // the docs/blog source files it has to mirror.
-    async allContentLoaded({ allContent }) {
+    async allContentLoaded({ allContent, actions }) {
       if (allContent) {
         for (const [pluginName, byId] of Object.entries(allContent)) {
           if (!byId) continue;
@@ -196,6 +232,18 @@ module.exports = function pluginAeo(context, rawOptions) {
           verbose: options.verbose,
         });
       }
+
+      // Which routes will have a companion, so the Ask AI button can point
+      // at the file and stay hidden on pages without one (generated
+      // category indexes, React pages). Same list postBuild emits from.
+      if (actions && typeof actions.setGlobalData === 'function') {
+        const companionRoutes = options.companions.enabled
+          ? collectCompanionItems(loadedContentByPlugin, options.companions).map(
+              (item) => item.permalink,
+            )
+          : [];
+        await actions.setGlobalData({ companionRoutes });
+      }
     },
 
     async postBuild(props) {
@@ -212,6 +260,15 @@ module.exports = function pluginAeo(context, rawOptions) {
         console.log('[plugin-aeo] companions disabled, skipping feature 1');
       }
 
+      if (options.companions.enabled && options.companions.alternateLink) {
+        await injectAlternateLinks({
+          props,
+          emittedCompanions,
+          linkHeader: options.companions.linkHeader,
+          verbose: options.verbose,
+        });
+      }
+
       if (options.llmsTxt.enabled) {
         await emitLlmsTxt({
           props,

package/src/theme/AskAiButton/brand-icons/ChatGpt.jsx

@@ -0,0 +1,26 @@
+// OpenAI / ChatGPT petaled mark. SVG path lifted verbatim from
+// @lobehub/icons (MIT) before the React 19 hard-pin made the
+// runtime install impossible on React 18 hosts. Brand color #000000
+// is hardcoded to match OpenAI's brand guidelines (the black
+// monochrome mark is the canonical one).
+
+import React from 'react';
+
+const PATH =
+  'M9.205 8.658v-2.26c0-.19.072-.333.238-.428l4.543-2.616c.619-.357 1.356-.523 2.117-.523 2.854 0 4.662 2.212 4.662 4.566 0 .167 0 .357-.024.547l-4.71-2.759a.797.797 0 00-.856 0l-5.97 3.473zm10.609 8.8V12.06c0-.333-.143-.57-.429-.737l-5.97-3.473 1.95-1.118a.433.433 0 01.476 0l4.543 2.617c1.309.76 2.189 2.378 2.189 3.948 0 1.808-1.07 3.473-2.76 4.163zM7.802 12.703l-1.95-1.142c-.167-.095-.239-.238-.239-.428V5.899c0-2.545 1.95-4.472 4.591-4.472 1 0 1.927.333 2.712.928L8.23 5.067c-.285.166-.428.404-.428.737v6.898zM12 15.128l-2.795-1.57v-3.33L12 8.658l2.795 1.57v3.33L12 15.128zm1.796 7.23c-1 0-1.927-.332-2.712-.927l4.686-2.712c.285-.166.428-.404.428-.737v-6.898l1.974 1.142c.167.095.238.238.238.428v5.233c0 2.545-1.974 4.472-4.614 4.472zm-5.637-5.303l-4.544-2.617c-1.308-.761-2.188-2.378-2.188-3.948A4.482 4.482 0 014.21 6.327v5.423c0 .333.143.571.428.738l5.947 3.449-1.95 1.118a.432.432 0 01-.476 0zm-.262 3.9c-2.688 0-4.662-2.021-4.662-4.519 0-.19.024-.38.047-.57l4.686 2.71c.286.167.571.167.856 0l5.97-3.448v2.26c0 .19-.07.333-.237.428l-4.543 2.616c-.619.357-1.356.523-2.117.523zm5.899 2.83a5.947 5.947 0 005.827-4.756C22.287 18.339 24 15.84 24 13.296c0-1.665-.713-3.282-1.998-4.448.119-.5.19-.999.19-1.498 0-3.401-2.759-5.947-5.946-5.947-.642 0-1.26.095-1.88.31A5.962 5.962 0 0010.205 0a5.947 5.947 0 00-5.827 4.757C1.713 5.447 0 7.945 0 10.49c0 1.666.713 3.283 1.998 4.448-.119.5-.19 1-.19 1.499 0 3.401 2.759 5.946 5.946 5.946.642 0 1.26-.095 1.88-.309a5.96 5.96 0 004.162 1.713z';
+
+export default function ChatGptIcon({ size = 18 }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      role="img"
+      aria-hidden="true"
+      style={{ flex: 'none', lineHeight: 1 }}
+    >
+      <path d={PATH} fill="#000000" />
+    </svg>
+  );
+}

package/src/theme/AskAiButton/brand-icons/Claude.jsx

@@ -0,0 +1,25 @@
+// Claude wordmark / petal. SVG path lifted verbatim from simple-icons
+// (CC0-1.0) so the mark is faithful to the brand kit. Brand color
+// #D97757 is hardcoded; ListItemIcon's `color: 'inherit'` keeps MUI
+// from tinting it.
+
+import React from 'react';
+
+const PATH =
+  'm4.7144 15.9555 4.7174-2.6471.079-.2307-.079-.1275h-.2307l-.7893-.0486-2.6956-.0729-2.3375-.0971-2.2646-.1214-.5707-.1215-.5343-.7042.0546-.3522.4797-.3218.686.0608 1.5179.1032 2.2767.1578 1.6514.0972 2.4468.255h.3886l.0546-.1579-.1336-.0971-.1032-.0972L6.973 9.8356l-2.55-1.6879-1.3356-.9714-.7225-.4918-.3643-.4614-.1578-1.0078.6557-.7225.8803.0607.2246.0607.8925.686 1.9064 1.4754 2.4893 1.8336.3643.3035.1457-.1032.0182-.0728-.164-.2733-1.3539-2.4467-1.445-2.4893-.6435-1.032-.17-.6194c-.0607-.255-.1032-.4674-.1032-.7285L6.287.1335 6.6997 0l.9957.1336.419.3642.6192 1.4147 1.0018 2.2282 1.5543 3.0296.4553.8985.2429.8318.091.255h.1579v-.1457l.1275-1.706.2368-2.0947.2307-2.6957.0789-.7589.3764-.9107.7468-.4918.5828.2793.4797.686-.0668.4433-.2853 1.8517-.5586 2.9021-.3643 1.9429h.2125l.2429-.2429.9835-1.3053 1.6514-2.0643.7286-.8196.85-.9046.5464-.4311h1.0321l.759 1.1293-.34 1.1657-1.0625 1.3478-.8804 1.1414-1.2628 1.7-.7893 1.36.0729.1093.1882-.0183 2.8535-.607 1.5421-.2794 1.8396-.3157.8318.3886.091.3946-.3278.8075-1.967.4857-2.3072.4614-3.4364.8136-.0425.0304.0486.0607 1.5482.1457.6618.0364h1.621l3.0175.2247.7892.522.4736.6376-.079.4857-1.2142.6193-1.6393-.3886-3.825-.9107-1.3113-.3279h-.1822v.1093l1.0929 1.0686 2.0035 1.8092 2.5075 2.3314.1275.5768-.3218.4554-.34-.0486-2.2039-1.6575-.85-.7468-1.9246-1.621h-.1275v.17l.4432.6496 2.3436 3.5214.1214 1.0807-.17.3521-.6071.2125-.6679-.1214-1.3721-1.9246L14.38 17.959l-1.1414-1.9428-.1397.079-.674 7.2552-.3156.3703-.7286.2793-.6071-.4614-.3218-.7468.3218-1.4753.3886-1.9246.3157-1.53.2853-1.9004.17-.6314-.0121-.0425-.1397.0182-1.4328 1.9672-2.1796 2.9446-1.7243 1.8456-.4128.164-.7164-.3704.0667-.6618.4008-.5889 2.386-3.0357 1.4389-1.882.929-1.0868-.0062-.1579h-.0546l-6.3385 4.1164-1.1293.1457-.4857-.4554.0608-.7467.2307-.2429 1.9064-1.3114Z';
+
+export default function ClaudeIcon({ size = 18 }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      role="img"
+      aria-hidden="true"
+      style={{ flex: 'none', lineHeight: 1 }}
+    >
+      <path d={PATH} fill="#D97757" />
+    </svg>
+  );
+}

package/src/theme/AskAiButton/brand-icons/Perplexity.jsx

@@ -0,0 +1,23 @@
+// Perplexity wordmark. SVG path lifted verbatim from simple-icons
+// (CC0-1.0). Brand color #21808D is hardcoded.
+
+import React from 'react';
+
+const PATH =
+  'M22.3977 7.0896h-2.3106V.0676l-7.5094 6.3542V.1577h-1.1554v6.1966L4.4904 0v7.0896H1.6023v10.3976h2.8882V24l6.932-6.3591v6.2005h1.1554v-6.0469l6.9318 6.1807v-6.4879h2.8882V7.0896zm-3.4657-4.531v4.531h-5.355l5.355-4.531zm-13.2862.0676 4.8691 4.4634H5.6458V2.6262zM2.7576 16.332V8.245h7.8476l-6.1149 6.1147v1.9723H2.7576zm2.8882 5.0404v-3.8852h.0001v-2.6488l5.7763-5.7764v7.0111l-5.7764 5.2993zm12.7086.0248-5.7766-5.1509V9.0618l5.7766 5.7766v6.5588zm2.8882-5.0652h-1.733v-1.9723L13.3948 8.245h7.8478v8.087z';
+
+export default function PerplexityIcon({ size = 18 }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      role="img"
+      aria-hidden="true"
+      style={{ flex: 'none', lineHeight: 1 }}
+    >
+      <path d={PATH} fill="#21808D" />
+    </svg>
+  );
+}

package/src/theme/AskAiButton/icons.js

@@ -1,45 +1,26 @@
-// Brand icons for the four supported AI providers, sourced from
-// @lobehub/icons. Each provider's package exports a default Mono
-// component with .Color, .Text, .Combine, .Avatar attached as
-// properties. We prefer .Color (multi-color brand variant) when the
-// provider ships one; OpenAI does not, so we fall back to Mono and
-// tint it with the ChatGPT brand green via inline style.
+// Provider brand icons. Hand-rolled inline SVGs lifted from
+// publicly-available marks (simple-icons paths under CC0-1.0 for
+// Claude and Perplexity; the @lobehub/icons OpenAI Mono path for
+// ChatGPT). Brand color is hardcoded on each path so MUI's
+// ListItemIcon color override doesn't tint them.
 //
-// Deep import paths (@lobehub/icons/es/<Provider>) are used because
-// the package does not declare a subpath exports map; the deep path
-// is stable across the 5.x line and tree-shakes cleanly because each
-// per-provider module's dependency footprint is just React.
-
-import React from 'react';
-import ClaudeIcons from '@lobehub/icons/es/Claude';
-import OpenAIIcons from '@lobehub/icons/es/OpenAI';
-import PerplexityIcons from '@lobehub/icons/es/Perplexity';
-import GeminiIcons from '@lobehub/icons/es/Gemini';
-
-const ICON_SIZE = 18;
-
-// OpenAI ships only the monochrome mark (Color variant absent from
-// @lobehub/icons as of 5.10.0). Use the known ChatGPT brand green so
-// the row visually matches the other three colored marks.
-const CHATGPT_GREEN = '#10A37F';
+// We hand-roll rather than depend on @lobehub/icons because lobehub
+// pinned react@^19 from 5.x onward, breaking React 18 consumers.
+// simple-icons works on any Node + React but no longer ships an
+// OpenAI mark following a 2024 trademark request, so a unified
+// "single library" path is no longer available - hand-rolled is the
+// only zero-conflict option.
+//
+// Bundle cost: ~3KB across the three SVG components combined.
 
-function makeColorIcon(IconNamespace, fallbackColor) {
-  const Component = IconNamespace.Color || IconNamespace;
-  const usingFallback = !IconNamespace.Color;
-  return function Icon() {
-    const props = { size: ICON_SIZE };
-    if (usingFallback && fallbackColor) {
-      props.style = { color: fallbackColor };
-    }
-    return React.createElement(Component, props);
-  };
-}
+import Claude from './brand-icons/Claude.jsx';
+import ChatGpt from './brand-icons/ChatGpt.jsx';
+import Perplexity from './brand-icons/Perplexity.jsx';
 
 const icons = {
-  claude: makeColorIcon(ClaudeIcons),
-  chatgpt: makeColorIcon(OpenAIIcons, CHATGPT_GREEN),
-  perplexity: makeColorIcon(PerplexityIcons),
-  gemini: makeColorIcon(GeminiIcons),
+  claude: Claude,
+  chatgpt: ChatGpt,
+  perplexity: Perplexity,
 };
 
 export default icons;

package/src/theme/AskAiButton/index.jsx

@@ -10,23 +10,29 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import { usePluginData } from '@docusaurus/useGlobalData';
 import icons from './icons.js';
 import styles from './styles.module.css';
+// CommonJS, shared with the Node-side features so the button and the
+// emitted file can never disagree about where the companion lives.
+import companionPathModule from '../../companionPath.js';
+import askAiPromptModule from '../../askAiPrompt.js';
+
+const { companionUrl, normalizeRoute } = companionPathModule;
+const { fillPrompt } = askAiPromptModule;
 
 const PROVIDER_LABELS = {
   claude: 'Ask Claude',
   chatgpt: 'Ask ChatGPT',
   perplexity: 'Ask Perplexity',
-  gemini: 'Ask Gemini',
 };
 
 const PROVIDER_URLS = {
   claude: 'https://claude.ai/new?q=',
   chatgpt: 'https://chatgpt.com/?q=',
   perplexity: 'https://www.perplexity.ai/search?q=',
-  gemini: 'https://gemini.google.com/app?q=',
 };
 
 const DEFAULT_PROMPT_TEMPLATE =
-  'Read {pageUrl}.md and help me with the following question about it: ';
+  'Read {companionUrl} and help me understand it. Summarize the key points, then ask me one clarifying question to dig deeper.';
+
 
 export default function AskAiButton() {
   const { siteConfig } = useDocusaurusContext();
@@ -39,16 +45,34 @@ export default function AskAiButton() {
 
   if (cfg.enabled === false) return null;
 
-  const baseUrl = (siteConfig.url || '').replace(/\/$/, '');
-  const pageUrl = `${baseUrl}${location.pathname.replace(/\/$/, '') || ''}`;
+  const siteUrl = (siteConfig.url || '').replace(/\/+$/, '');
+  const route = normalizeRoute(location.pathname);
+  const pageUrl = route === '/' ? siteUrl : `${siteUrl}${route}`;
+
+  // Only pages with a companion get the button: a generated category index
+  // or a React page has no .md file, so a prompt pointing at one would
+  // send the reader to a 404. `companionRoutes` arrives from
+  // allContentLoaded; if an older core did not merge it, fall back to
+  // showing the button everywhere as before. With companions disabled the
+  // prompt uses the page itself.
+  const companionsEnabled = cfg.companionsEnabled !== false;
+  const routes = data.companionRoutes;
+  if (companionsEnabled && Array.isArray(routes)) {
+    const known = routes.some((r) => normalizeRoute(r) === route);
+    if (!known) return null;
+  }
+  const mdUrl = companionsEnabled
+    ? companionUrl(siteUrl, route, siteConfig.trailingSlash)
+    : pageUrl;
+
   const promptTemplate = cfg.promptTemplate || DEFAULT_PROMPT_TEMPLATE;
-  const prompt = promptTemplate.replace('{pageUrl}', pageUrl);
+  const prompt = fillPrompt(promptTemplate, { pageUrl, companionUrl: mdUrl });
   const encoded = encodeURIComponent(prompt);
 
   const order =
     Array.isArray(cfg.providerOrder) && cfg.providerOrder.length > 0
       ? cfg.providerOrder
-      : ['claude', 'chatgpt', 'perplexity', 'gemini'];
+      : ['claude', 'chatgpt', 'perplexity'];
 
   const handleOpen = (e) => setAnchorEl(e.currentTarget);
   const handleClose = () => setAnchorEl(null);