@stackql/docusaurus-plugin-aeo 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 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.
+
+## 0.1.1
+
+Bugfix release. v0.1.0 failed to build on a real Docusaurus 3.10 consumer with three distinct crashes; all three are fixed here.
+
+### Fixed
+
+- **Plugin construction crash: `plugin.options.id` is `undefined`.** v0.1.0 exported a `validateOptions` function that bypassed Docusaurus's option normalization, so the standard `id: 'default'` default was never applied. `@docusaurus/core` then crashed in `lib/server/plugins/actions.js` at `createPluginActionsUtils`:
+
+  ```text
+  TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string.
+  Received undefined
+    at Object.join (node:path:460:7)
+    at createPluginActionsUtils (.../@docusaurus/core/lib/server/plugins/actions.js:27:36)
+  ```
+
+  Fix: removed the `validateOptions` export so Docusaurus's built-in plugin schema runs. The plugin's handwritten construction-time validator (`normalizeOptions` + the internal `validateOptions` in `src/index.js`) still validates plugin-specific options.
+
+- **SSR stack overflow on every doc and blog page.** The footer wrappers at `src/theme/DocItem/Footer/index.jsx` and `src/theme/BlogPostItem/Footer/index.jsx` imported `@theme-original/DocItem/Footer` and `@theme-original/BlogPostItem/Footer`. When a *plugin* (not a *theme*) contributes the wrapper and is the only contributor in the wrapper layer, `@theme-original/X` resolves back to the wrapper itself, recursing during SSG:
+
+  ```text
+  Error: Can't render static file for pathname "/docs/intro"
+    [cause]: RangeError: Maximum call stack size exceeded
+      at RegExp.exec (<anonymous>)
+      at F (server.bundle.js:15836:87)
+      at Ka (server.bundle.js:15845:249)
+      at Pa (server.bundle.js:15853:68)
+  ```
+
+  Fix: switched both wrappers to import from `@theme-init/X`, which always resolves to the un-wrapped initial component from the theme chain.
+
+- **`getThemePath()` returning `undefined` crashes core.** With `askAi.enabled: false` (or `askAi.placement: 'none'`), v0.1.0's `getThemePath` returned `undefined`, which `@docusaurus/core` then handed to `path.join` inside `webpack/server.js`. Fix: the plugin now constructs its plugin object conditionally and only attaches `getThemePath` when the theme is enabled. This is the idiomatic signal that a plugin contributes no theme.
+
+### Notes for consumers
+
+No config changes required. Bump the version and rebuild.
+
 ## 0.1.0
 
 Initial release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackql/docusaurus-plugin-aeo",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {

package/src/index.js

@@ -113,23 +113,33 @@ module.exports = function pluginAeo(context, rawOptions) {
   // Map<pluginName, { plugin: { name, id }, content: any }>
   const loadedContentByPlugin = new Map();
 
-  return {
-    name: '@stackql/docusaurus-plugin-aeo',
+  const themeEnabled =
+    options.askAi.enabled && options.askAi.placement !== 'none';
 
-    getThemePath() {
-      if (!options.askAi.enabled || options.askAi.placement === 'none') {
-        return undefined;
-      }
-      return path.resolve(__dirname, './theme');
-    },
+  const plugin = {
+    name: '@stackql/docusaurus-plugin-aeo',
 
-    getClientModules() {
-      return [];
+    // 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.
+    async contentLoaded({ actions }) {
+      await actions.setGlobalData({
+        askAi: {
+          enabled: options.askAi.enabled,
+          providerOrder: options.askAi.providerOrder,
+          promptTemplate: options.askAi.promptTemplate,
+          placement: options.askAi.placement,
+          companionsEnabled: options.companions.enabled,
+        },
+      });
     },
 
-    // Surface the askAi config to theme components via a global data
-    // injection. Docusaurus client code can read this through useDocusaurusContext().
-    async contentLoaded({ actions, allContent }) {
+    // Cross-plugin loaded content (docs, blog, pages) is only delivered to
+    // 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 }) {
       if (allContent) {
         for (const [pluginName, byId] of Object.entries(allContent)) {
           if (!byId) continue;
@@ -143,16 +153,6 @@ module.exports = function pluginAeo(context, rawOptions) {
         }
       }
 
-      await actions.setGlobalData({
-        askAi: {
-          enabled: options.askAi.enabled,
-          providerOrder: options.askAi.providerOrder,
-          promptTemplate: options.askAi.promptTemplate,
-          placement: options.askAi.placement,
-          companionsEnabled: options.companions.enabled,
-        },
-      });
-
       if (options.aiRoutes.validate) {
         validateAiRoutes({
           loadedContentByPlugin,
@@ -188,13 +188,18 @@ module.exports = function pluginAeo(context, rawOptions) {
       }
     },
   };
-};
 
-module.exports.validateOptions = function validateDocusaurusOptions({
-  options,
-  validate: _validate,
-}) {
-  // Docusaurus passes a Joi validator we deliberately don't use - the plugin
-  // entry runs its own handwritten validator at construction time.
-  return options || {};
+  // Only contribute a theme path when the Ask AI button is enabled.
+  // Returning undefined or an invalid value from getThemePath crashes
+  // @docusaurus/core in webpack/server.js; omitting the method entirely
+  // is the idiomatic signal that this plugin contributes no theme.
+  if (themeEnabled) {
+    plugin.getThemePath = () => path.resolve(__dirname, './theme');
+  }
+
+  return plugin;
 };
+
+// Intentionally no validateOptions export: Docusaurus applies its own default
+// option normalization (including id: 'default') when this is absent.
+// The plugin's handwritten validator runs at construction time.

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

@@ -1,5 +1,8 @@
 import React from 'react';
-import Footer from '@theme-original/BlogPostItem/Footer';
+// 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) {

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

@@ -1,5 +1,10 @@
 import React from 'react';
-import Footer from '@theme-original/DocItem/Footer';
+// 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) {