@eox/pages-theme-eox 2.0.0-alpha.6 → 2.0.0-alpha.7

package/README.md

@@ -21,6 +21,45 @@ See also the [Vitepress Docs](https://vitepress.dev/guide/custom-theme#consuming
 
 This theme supports standard [VitePress Default Theme Configuration](https://vitepress.dev/reference/default-theme-config) with some specific adaptations.
 
+### LLMs Configuration (`llms.txt`)
+
+This theme integrates [vitepress-plugin-llms](https://github.com/nmoodev/vitepress-plugin-llms) to automatically generate AI-friendly documentation (`llms.txt` and `llms-full.txt`), along with custom support for VitePress story routes and remote story manifests.
+
+Generation is enabled by default. You can configure options via `brandConfig.llms` in your brand configuration:
+
+```javascript
+// Example brandConfig:
+export const config = {
+  // ... other brand settings ...
+  llms: {
+    // Upstream vitepress-plugin-llms options
+    domain: "https://yourdomain.com", // Base URL to resolve absolute links in llms.txt
+    copyButtons: true, // (Optional) Adds copy buttons to code blocks in documentation
+
+    // Theme-specific Story Routes config
+    stories: {
+      heading: "Stories", // (Optional) Heading used in llms.txt and route pages (default: "Stories")
+      path: "narratives/[narrative]", // (Optional) Story route pattern (e.g. "narratives/[narrative]" or "story"). Also accepts `storyPath`
+      manifest: "https://cdn.example.com/narratives.json", // (Optional) URL to stories manifest (auto-detected from gallery components if omitted)
+      concurrency: 8, // (Optional) Maximum concurrent story downloads (default: 8)
+    },
+  },
+};
+```
+
+#### Disabling LLMs
+
+- To disable LLM documentation generation entirely: set `llms: false`.
+- To generate general docs without stories: set `stories: false` inside `llms`:
+
+```javascript
+export const config = {
+  llms: {
+    stories: false,
+  },
+};
+```
+
 ### Navigation Bar
 
 The Navigation Bar follows the [Default Theme Nav](https://vitepress.dev/reference/default-theme-nav) structure with the following differences:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eox/pages-theme-eox",
-  "version": "2.0.0-alpha.6",
+  "version": "2.0.0-alpha.7",
   "type": "module",
   "description": "Vitepress Theme with EOX branding",
   "main": "src/index.js",
@@ -13,7 +13,7 @@
     "format": "npx prettier --write .",
     "format:check": "npx prettier --check .",
     "test": "npm run test:unit && npm run test:component",
-    "test:unit": "node --test src/helpers.test.js",
+    "test:unit": "node --test src/helpers.test.js src/llms/llms.test.js",
     "test:component": "cypress run --component",
     "release": "release-it"
   },
@@ -21,7 +21,8 @@
     "@eox/eslint-config": "^2.0.0",
     "@eox/feedback": "^1.1.1",
     "@eox/ui": "^1.0.1",
-    "vitepress": "^1.6.3"
+    "vitepress": "^1.6.3",
+    "vitepress-plugin-llms": "^1.13.5"
   },
   "devDependencies": {
     "@release-it/conventional-changelog": "^10.0.6",

package/src/llms/index.js

@@ -0,0 +1,64 @@
+import llmstxt from "vitepress-plugin-llms";
+import { createStoriesPlugin } from "./storiesPlugin.js";
+
+const LLMS_DEFAULTS = {};
+
+/**
+ * Normalizes a URL by stripping trailing slashes.
+ * @param {string | undefined | null} url
+ * @returns {string | null}
+ */
+export const normalizeDomain = (url) => {
+  if (!url || typeof url !== "string") return null;
+  return url.replace(/\/+$/, "");
+};
+
+/**
+ * Resolve the llms option into Vite plugins and package-owned flags.
+ * @param {boolean | Record<string, any>} [option] The `llms` option
+ * @param {Record<string, any>} [brandConfig] Brand configuration object
+ * @returns {{ plugins: any[], copyButtons: boolean, stories: any, domain: string | null }}
+ */
+export const resolveLlms = (option, brandConfig = {}) => {
+  if (option === false) {
+    return {
+      plugins: [],
+      copyButtons: false,
+      stories: null,
+      domain: null,
+    };
+  }
+
+  const {
+    copyButtons = false,
+    stories = null,
+    ...settings
+  } = option === true || option === undefined ? {} : option;
+
+  const rawDomain = settings.domain;
+  const domain = normalizeDomain(rawDomain);
+
+  const upstreamPlugins = llmstxt({
+    ...LLMS_DEFAULTS,
+    ...settings,
+    ...(domain ? { domain } : {}),
+  });
+
+  const plugins = [...upstreamPlugins];
+  if (stories !== false) {
+    plugins.push(
+      createStoriesPlugin({
+        storiesOption: stories,
+        brandConfig,
+        domain,
+      }),
+    );
+  }
+
+  return {
+    plugins,
+    copyButtons: Boolean(copyButtons),
+    stories,
+    domain,
+  };
+};