nuxt-llms 0.0.1 → 0.1.0

package/README.md

@@ -1,3 +1,5 @@
+![nuxt-llms-social-card](https://github.com/user-attachments/assets/4570398c-0e49-4199-bc30-ab72f6680f4b)
+
 # Nuxt LLMs
 
 [![npm version][npm-version-src]][npm-version-href]
@@ -13,7 +15,8 @@ Nuxt LLMs automatically generates [`llms.txt` markdown documentation](https://ll
 
 ## Features
 
-- Generates & prerenders `/llms.txt` and `/llms_full.txt` routes automatically
+- Generates & prerenders `/llms.txt` automatically
+- Generate & prerenders `/llms_full.txt` when enabled
 - Customizable sections directly from your `nuxt.config.ts`
 - Integrates with Nuxt modules and your application via the runtime hooks system
 
@@ -80,7 +83,166 @@ That's it! You can visit `/llms.txt` to see the generated documentation ✨
     - `title`(required): The title of the link
     - `description`: The description of the link
     - `href`(required): The href of the link
-- `notes`: The notes of the documentation. Notes are a special section which always appears at the end of the documentation. Notes are usefull to add any information about the application or documentation itself.
+- `notes`: The notes of the documentation. Notes are a special section which always appears at the end of the documentation. Notes are useful to add any information about the application or documentation itself.
+- `full`: The `llms_full.txt` configuration. Setting this option will enable the `llms_full.txt` route.
+  - `title`: The title of the llms_full documentation
+  - `description`: The description of the llms_full documentation
+
+## Documentation Formats
+
+The module generates two different documentation formats:
+
+### llms.txt
+
+The `/llms.txt` route generates a concise, structured documentation that follows the [llms.txt specification](https://llmstxt.org/). This format is optimized for both human readability and AI consumption. It includes:
+
+- Application title and description
+- Organized sections with titles and descriptions
+- Links with titles, descriptions, and URLs
+- Optional notes section
+
+### llms_full.txt
+
+The `/llms_full.txt` route provides a more detailed, free-form documentation format. This is useful to reduce crawler traffic on your application and provide a more detailed documentation to your users and LLMs.
+
+By default module does not generate the `llms_full.txt` route, you need to enable it by setting `full.title` and `full.description` in your `nuxt.config.ts`.
+
+```ts
+export default defineNuxtConfig({
+  llms: {
+    domain: 'https://example.com',
+    title: 'My Application',
+    full: {
+      title: 'Full Documentation',
+      description: 'Full documentation of the application',
+    },
+  },
+})
+```
+
+## Extending the documentation using hooks
+
+The module provides a hooks system that allows you to dynamically extend both documentation formats. There are two main hooks:
+
+### Available Hooks
+
+#### `llms:generate(event, options)`
+
+This hook is called for every request to `/llms.txt`. Use this hook to modify the structured documentation, It allows you to add sections, links, and metadata.
+
+**Parameters:**
+  - `event`: H3Event - The current request event
+  - `options`: ModuleOptions - The module options that you can modify to add sections, links, etc.
+
+
+#### `llms:generate:llms_full(event, options, contents)`
+
+This hook is called for every request to `/llms_full.txt`. It allows you to add custom content sections in any format.
+
+**Parameters:**
+  - `event`: H3Event - The current request event
+  - `options`: ModuleOptions - The module options that you can modify to add sections, links, etc.
+  - `contents`: string[] - Array of content sections you can add to or modify
+
+### Using Hooks in Your Application
+
+Create a server plugin in your `server/plugins` directory:
+
+```ts
+// server/plugins/llms.ts
+export default defineNitroPlugin((nitroApp) => {
+  // Method 1: Using the hooks directly
+  nitroApp.hooks.hook('llms:generate', (event, options) => {
+    // Add a new section to llms.txt
+    options.sections.push({
+      title: 'API Documentation',
+      description: 'REST API endpoints and usage',
+      links: [
+        {
+          title: 'Authentication',
+          description: 'API authentication methods',
+          href: `${options.domain}/api/auth`
+        }
+      ]
+    })
+  })
+
+  // Method 2: Using the helper function
+  nitroApp.hooks.hook('llms:generate:full', (event, options, contents) => {
+    // Add detailed documentation to llms_full.txt
+    contents.push(`## API Authentication
+
+### Bearer Token
+To authenticate API requests, include a Bearer token in the Authorization header:
+
+\`\`\`
+Authorization: Bearer <your-token>
+\`\`\`
+
+### API Keys
+For server-to-server communication, use API keys:
+
+\`\`\`
+X-API-Key: <your-api-key>
+\`\`\`
+    `)
+  })
+})
+```
+
+### Using Hooks in Nuxt Modules
+
+If you're developing a Nuxt module that needs to extend the LLMs documentation:
+
+1. Create a server plugin in your module:
+```ts
+// module/runtime/server/plugins/my-module-llms.ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('llms:generate', (event, options) => {
+    options.sections.push({
+      title: 'My Module',
+      description: 'Documentation for my module features',
+      links: [/* ... */]
+    })
+  })
+})
+```
+
+2. Register the plugin in your module setup:
+```ts
+import { defineNuxtModule, addServerPlugin } from '@nuxt/kit'
+import { fileURLToPath } from 'url'
+
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    const runtimeDir = fileURLToPath(new URL('./runtime', import.meta.url))
+    addServerPlugin(resolve(runtimeDir, 'server/plugins/my-module-llms'))
+  }
+})
+```
+
+## Integrations
+
+### Nuxt Content
+
+Nuxt Content ^3.2.0 comes with built-in support for LLMs documentation. You can use `nuxt-llms` with `@nuxt/content` to efficiently write content and documentation for your website and generate LLM-friendly documentation without extra effort. Content module uses `nuxt-llms` hooks and automatically adds all your contents into `llms.txt` and `llms_full.txt` documentation.
+
+All you need is to install both modules and write your content files in the `content` directory.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-llms', '@nuxt/content'],
+  llms: {
+    domain: 'https://example.com',
+    title: 'My Application',
+    description: 'My Application Description',
+  },
+})
+```
+
+Checkout the [Nuxt Content documentation](https://content.nuxt.com/docs/usage/content-pages) for more information on how to write your content files.
+
+And checkout the [Nuxt Content llms documentation](https://content.nuxt.com/docs/advanced/llms) for more information on how to customize LLMs contents with `nuxt-llms` and `@nuxt/content`.
 
 ## 💻 Development
 

package/dist/module.d.mts

@@ -1,32 +1,7 @@
 import * as _nuxt_schema from '@nuxt/schema';
-
-interface LLMsSection {
-    title: string;
-    description?: string;
-    links?: Array<{
-        title: string;
-        description?: string;
-        href: string;
-    }>;
-}
-interface ModuleOptions {
-    /**
-     * Domain of the documentation
-     */
-    domain: string;
-    /**
-     * Enable the full documentation
-     */
-    llmsFull?: {
-        title: string;
-        description: string;
-    };
-    sections: Array<LLMsSection>;
-    title?: string;
-    description?: string;
-    notes?: string[];
-}
+import { ModuleOptions } from '../dist/runtime/types.js';
+export * from '../dist/runtime/types.js';
 
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
-export { type LLMsSection, type ModuleOptions, _default as default };
+export { _default as default };

package/dist/module.d.ts

@@ -1,32 +1,7 @@
 import * as _nuxt_schema from '@nuxt/schema';
-
-interface LLMsSection {
-    title: string;
-    description?: string;
-    links?: Array<{
-        title: string;
-        description?: string;
-        href: string;
-    }>;
-}
-interface ModuleOptions {
-    /**
-     * Domain of the documentation
-     */
-    domain: string;
-    /**
-     * Enable the full documentation
-     */
-    llmsFull?: {
-        title: string;
-        description: string;
-    };
-    sections: Array<LLMsSection>;
-    title?: string;
-    description?: string;
-    notes?: string[];
-}
+import { ModuleOptions } from '../dist/runtime/types.js';
+export * from '../dist/runtime/types.js';
 
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
-export { type LLMsSection, type ModuleOptions, _default as default };
+export { _default as default };

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "Nuxt LLMS",
   "configKey": "llms",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "2.0.0"

package/dist/module.mjs

@@ -23,13 +23,13 @@ const module = defineNuxtModule({
     addServerImports([{ name: "llmsHooks", from: resolve("./runtime/server/utils/hooks") }]);
     addServerHandler({ route: "/llms.txt", handler: resolve("./runtime/server/routes/llms.txt.get") });
     addPrerenderRoutes("/llms.txt");
-    if (options.llmsFull) {
+    if (options.full) {
       llmsConfig.sections.unshift({
         title: "Documentation Sets",
         links: [
           {
-            title: options.llmsFull.title,
-            description: options.llmsFull.description,
+            title: options.full.title,
+            description: options.full.description,
             href: `${options.domain}/llms_full.txt`
           }
         ]

package/dist/runtime/server/routes/llms.txt.get.js

@@ -1,9 +1,10 @@
 import { eventHandler, setHeader } from "h3";
 import { llmsHooks } from "nuxt-llms/runtime";
-import { useRuntimeConfig } from "#imports";
+import { useRuntimeConfig, useNitroApp } from "#imports";
 export default eventHandler(async (event) => {
   const options = useRuntimeConfig(event).llms;
   const llms = JSON.parse(JSON.stringify(options));
+  await useNitroApp().hooks.callHook("llms:generate", event, llms);
   await llmsHooks.callHook("generate", event, llms);
   const document = [
     `# ${llms.title || "Documentation"}`

package/dist/runtime/server/routes/llms_full.txt.get.js

@@ -1,20 +1,12 @@
 import { eventHandler, setHeader } from "h3";
 import { llmsHooks } from "nuxt-llms/runtime";
-import { useRuntimeConfig } from "#imports";
+import { useRuntimeConfig, useNitroApp } from "#imports";
 export default eventHandler(async (event) => {
   const options = useRuntimeConfig(event).llms;
   const contents = [];
   const llms = JSON.parse(JSON.stringify(options));
+  await useNitroApp().hooks.callHook("llms:generate:full", event, llms, contents);
   await llmsHooks.callHook("generate:full", event, llms, contents);
-  const document = [
-    `# ${llms.llmsFull?.title || "Documentation"}`
-  ];
-  if (llms.description) {
-    document.push(`> ${llms.llmsFull?.description}`);
-  }
-  for (const content of contents) {
-    document.push(content);
-  }
   setHeader(event, "Content-Type", "text/plain");
   return contents.join("\n\n");
 });

package/dist/runtime/server/utils/hooks.d.ts

@@ -1,15 +1,26 @@
 import type { H3Event } from 'h3';
 import type { ModuleOptions } from 'nuxt-llms';
+import type { NitroRuntimeHooks } from 'nitropack/types';
+/**
+ * @deprecated Custom hooks are deprecated in favor of NitroRuntimeHooks.
+ */
 export interface LLMSHooks {
     'generate': (event: H3Event, options: ModuleOptions) => void;
     'generate:full': (event: H3Event, options: ModuleOptions, contents: string[]) => void;
 }
+/**
+ * @deprecated Custom hooks are deprecated in favor of NitroRuntimeHooks.
+ */
 export declare const llmsHooks: import("hookable").Hookable<LLMSHooks, import("hookable").HookKeys<LLMSHooks>>;
 /**
  * Run a callback when LLMs is being generated.
+ *
+ * @deprecated Use `useNitroApp().hooks.hook('llms:generate', (event, options) => {})` instead
  */
-export declare function onLLMsGenerate(cb: LLMSHooks['generate']): () => void;
+export declare function onLLMsGenerate(cb: NitroRuntimeHooks['llms:generate']): any;
 /**
  * Run a callback when Full LLMs is being generated.
+ *
+ * @deprecated Use `useNitroApp().hooks.hook('llms:generate:full', (event, options, contents) => {})` instead
  */
-export declare function onLLMsGenerateFull(cb: LLMSHooks['generate:full']): () => void;
+export declare function onLLMsGenerateFull(cb: NitroRuntimeHooks['llms:generate:full']): any;

package/dist/runtime/server/utils/hooks.js

@@ -1,8 +1,12 @@
 import { createHooks } from "hookable";
+import { useNitroApp } from "#imports";
 export const llmsHooks = createHooks();
+llmsHooks.beforeEach(() => {
+  console.warn("[nuxt-llms] `llmsHooks` are deprecated and will be removed in future versions. Use `useNitroApp().hooks.hook('llms:generate', (event, options) => {})` instead");
+});
 export function onLLMsGenerate(cb) {
-  return llmsHooks.hook("generate", cb);
+  return useNitroApp().hooks.hook("llms:generate", cb);
 }
 export function onLLMsGenerateFull(cb) {
-  return llmsHooks.hook("generate:full", cb);
+  return useNitroApp().hooks.hook("llms:generate:full", cb);
 }

package/dist/runtime/types.d.ts

@@ -0,0 +1,33 @@
+import type { H3Event } from 'h3';
+declare module 'nitropack/types' {
+    interface NitroRuntimeHooks {
+        'llms:generate': (event: H3Event, options: ModuleOptions) => void;
+        'llms:generate:full': (event: H3Event, options: ModuleOptions, contents: string[]) => void;
+    }
+}
+export interface LLMsSection {
+    title: string;
+    description?: string;
+    links?: Array<{
+        title: string;
+        description?: string;
+        href: string;
+    }>;
+}
+export interface ModuleOptions {
+    /**
+     * Domain of the documentation
+     */
+    domain: string;
+    /**
+     * Enable the full documentation
+     */
+    full?: {
+        title: string;
+        description: string;
+    };
+    sections: Array<LLMsSection>;
+    title?: string;
+    description?: string;
+    notes?: string[];
+}

package/dist/types.d.mts

@@ -1 +1,7 @@
-export { type LLMsSection, type ModuleOptions, default } from './module.js'
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.js'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.js'

package/dist/types.d.ts

@@ -1 +1,7 @@
-export { type LLMsSection, type ModuleOptions, default } from './module'
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-llms",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Generate llms.txt documentation for your Nuxt application",
   "repository": {
     "type": "git",
@@ -10,7 +10,7 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/types.d.ts",
+      "types": "./dist/module.d.ts",
       "import": "./dist/module.mjs",
       "require": "./dist/module.cjs"
     },
@@ -21,7 +21,7 @@
     }
   },
   "main": "./dist/module.cjs",
-  "types": "./dist/types.d.ts",
+  "types": "./dist/module.d.ts",
   "files": [
     "dist"
   ],

package/dist/runtime/server/tsconfig.json

@@ -1,3 +0,0 @@
-{
-  "extends": "../../../.nuxt/tsconfig.server.json",
-}