@stackql/docusaurus-plugin-aeo 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 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.1",
   "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,19 +113,11 @@ module.exports = function pluginAeo(context, rawOptions) {
   // Map<pluginName, { plugin: { name, id }, content: any }>
   const loadedContentByPlugin = new Map();
 
-  return {
-    name: '@stackql/docusaurus-plugin-aeo',
-
-    getThemePath() {
-      if (!options.askAi.enabled || options.askAi.placement === 'none') {
-        return undefined;
-      }
-      return path.resolve(__dirname, './theme');
-    },
+  const themeEnabled =
+    options.askAi.enabled && options.askAi.placement !== 'none';
 
-    getClientModules() {
-      return [];
-    },
+  const plugin = {
+    name: '@stackql/docusaurus-plugin-aeo',
 
     // Surface the askAi config to theme components via a global data
     // injection. Docusaurus client code can read this through useDocusaurusContext().
@@ -188,13 +180,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) {