@stackql/docusaurus-plugin-aeo 0.4.2 → 0.5.1

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 = [
@@ -15,7 +17,7 @@ const DEFAULT_LLMS_EXCLUDE = [
 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 understand it. Summarize the key points, then ask me one clarifying question to dig deeper.';
+  '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');
   }
@@ -150,6 +182,12 @@ module.exports = function pluginAeo(context, rawOptions) {
   const options = normalizeOptions(rawOptions);
   validateOptions(options);
 
+  // siteConfig.baseUrl for this build. Docusaurus constructs the plugin
+  // once per locale, and a localized build has its own base URL ('/de/');
+  // routes carry it, and the route conventions below are relative to it.
+  const baseUrl =
+    (context && ((context.siteConfig && context.siteConfig.baseUrl) || context.baseUrl)) || '/';
+
   // Captured from contentLoaded for downstream postBuild use.
   // Map<pluginName, { plugin: { name, id }, content: any }>
   const loadedContentByPlugin = new Map();
@@ -160,10 +198,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: {
@@ -180,7 +218,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;
@@ -197,9 +235,22 @@ module.exports = function pluginAeo(context, rawOptions) {
       if (options.aiRoutes.validate) {
         validateAiRoutes({
           loadedContentByPlugin,
+          baseUrl,
           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, baseUrl).map(
+              (item) => item.permalink,
+            )
+          : [];
+        await actions.setGlobalData({ companionRoutes });
+      }
     },
 
     async postBuild(props) {
@@ -216,6 +267,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/routeGlob.js

@@ -0,0 +1,60 @@
+// Route glob matching for the `exclude` / `include` options.
+//
+// A pattern describes a route of the site: '/blog/tags/**', '/search'.
+// Docusaurus permalinks carry siteConfig.baseUrl, and that differs between
+// builds of the same site: a localized build runs with baseUrl '/de/', so
+// the page a pattern names is '/de/blog/tags/x' there. A pattern is
+// therefore tried against the route with the base URL removed as well as
+// the route as Docusaurus reports it:
+//
+//   - one configuration covers every locale and any baseUrl, and
+//   - a pattern that spells the base out keeps working ('/docs/guide/**' on
+//     a site built at '/docs/') and can single out one locale
+//     ('/de/blog/**').
+//
+// Minimal matcher, to avoid pulling micromatch in directly: `**` matches
+// across path segments, `*` and `?` within one.
+
+const { stripBase } = require('./companionPath');
+
+function toRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if ('.+^$()|{}[]\\'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+// True when `value` matches at least one glob. No patterns, no match.
+function matchAny(value, patterns) {
+  if (!patterns || patterns.length === 0) return false;
+  for (const p of patterns) {
+    if (toRegExp(p).test(value)) return true;
+  }
+  return false;
+}
+
+// True when a permalink matches at least one glob, with or without
+// `baseUrl` (siteConfig.baseUrl) in front of it.
+function matchesRoute(permalink, patterns, baseUrl) {
+  if (matchAny(permalink, patterns)) return true;
+  const relative = stripBase(permalink, baseUrl);
+  return relative !== permalink && matchAny(relative, patterns);
+}
+
+module.exports = { toRegExp, matchAny, matchesRoute };

package/src/theme/AskAiButton/index.jsx

@@ -8,14 +8,39 @@ import KeyboardArrowDownIcon from '@mui/icons-material/KeyboardArrowDown';
 import { useLocation } from '@docusaurus/router';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import { usePluginData } from '@docusaurus/useGlobalData';
+import { translate } from '@docusaurus/Translate';
 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 PROVIDER_LABELS = {
-  claude: 'Ask Claude',
-  chatgpt: 'Ask ChatGPT',
-  perplexity: 'Ask Perplexity',
-};
+const { companionUrl, pageUrl: pageUrlFor, normalizeRoute } = companionPathModule;
+const { fillPrompt } = askAiPromptModule;
+
+// Visible strings go through translate() so a localized site can override
+// them in i18n/<locale>/code.json (`docusaurus write-translations` extracts
+// them from this theme component).
+function providerLabels() {
+  return {
+    claude: translate({
+      id: 'aeo.askAi.provider.claude',
+      message: 'Ask Claude',
+      description: 'Ask AI menu entry',
+    }),
+    chatgpt: translate({
+      id: 'aeo.askAi.provider.chatgpt',
+      message: 'Ask ChatGPT',
+      description: 'Ask AI menu entry',
+    }),
+    perplexity: translate({
+      id: 'aeo.askAi.provider.perplexity',
+      message: 'Ask Perplexity',
+      description: 'Ask AI menu entry',
+    }),
+  };
+}
 
 const PROVIDER_URLS = {
   claude: 'https://claude.ai/new?q=',
@@ -24,7 +49,8 @@ const PROVIDER_URLS = {
 };
 
 const DEFAULT_PROMPT_TEMPLATE =
-  'Read {pageUrl}.md and help me understand it. Summarize the key points, then ask me one clarifying question to dig deeper.';
+  '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();
@@ -37,10 +63,30 @@ 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);
+  // siteConfig.baseUrl is the locale's base (/de/) in a localized build, so
+  // the localized home page resolves like the site root.
+  const pageUrl = pageUrlFor(siteUrl, route, siteConfig.baseUrl);
+
+  // 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, siteConfig.baseUrl)
+    : 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 =
@@ -50,6 +96,7 @@ export default function AskAiButton() {
 
   const handleOpen = (e) => setAnchorEl(e.currentTarget);
   const handleClose = () => setAnchorEl(null);
+  const labels = providerLabels();
 
   return (
     <div className={styles.dropdownWrapper}>
@@ -69,11 +116,16 @@ export default function AskAiButton() {
           color: 'var(--ifm-color-primary)',
           '&:hover': {
             borderColor: 'var(--ifm-color-primary)',
-            backgroundColor: 'rgba(0, 65, 101, 0.04)',
+            // a 4% tint of the site's own primary colour
+            backgroundColor: 'color-mix(in srgb, var(--ifm-color-primary) 4%, transparent)',
           },
         }}
       >
-        Ask AI about this page
+        {translate({
+          id: 'aeo.askAi.button',
+          message: 'Ask AI about this page',
+          description: 'Label of the Ask AI dropdown button',
+        })}
       </Button>
       <Menu
         anchorEl={anchorEl}
@@ -90,7 +142,7 @@ export default function AskAiButton() {
       >
         {order.map((key) => {
           const Icon = icons[key];
-          const label = PROVIDER_LABELS[key];
+          const label = labels[key];
           const base = PROVIDER_URLS[key];
           if (!base || !Icon) return null;
           const href = `${base}${encoded}`;