@pointsharp/antora-llm-generator 1.0.0 → 1.1.1

package/README.md

@@ -11,10 +11,8 @@ Both files help large-language models ingest your documentation with proper stru
 
 ## Installation
 
-This extension is used locally. Ensure the required dependencies are installed:
-
 ```bash
-npm install node-html-markdown minimatch
+npm install @pointsharp/antora-llm-generator
 ```
 
 ---
@@ -26,7 +24,7 @@ Add the extension to your `antora-playbook.yml`:
 ```yaml
 antora:
   extensions:
-    - require: ./extensions/antora-llm-generator/llm-generator.js
+    - require: "@pointsharp/antora-llm-generator"
       summary: "Brief summary about your documentation site"
       details: |
         Optional longer description or important notes.
@@ -40,6 +38,7 @@ antora:
 - **`summary`** - Optional. Appears as a blockquote at the top of both output files (following llmstxt.org spec).
 - **`details`** - Optional. Appears as regular text after the summary. Can be multi-line markdown.
 - **`skippaths`** - Optional. Array of glob patterns. Files matching these patterns are omitted from both output files.
+- **`debug`** - Optional. Set to `true` to enable verbose logging during build. Default: `false`.
 
 ### Navigation-based organization (default)
 
@@ -182,6 +181,40 @@ The duplicate filenames ensure compatibility with different naming conventions.
 
 ---
 
+## Logging
+
+The extension runs **silently** by default, showing only a success message when complete:
+
+```
+Generated llms.txt and llms-full.txt
+```
+
+### Enabling verbose output
+
+To see detailed processing information (pages collected, components processed, etc.), enable the `debug` flag in your playbook:
+
+```yaml
+antora:
+  extensions:
+    - require: "@pointsharp/antora-llm-generator"
+      debug: true
+      summary: "Your summary"
+```
+
+With `debug: true`, you'll see:
+- Navigation data source detection
+- Number of pages in the page map
+- Components and sections being processed
+- Item counts for each section
+
+### Error handling
+
+The extension always reports errors and critical warnings, regardless of the debug setting:
+- **Errors** - Processing failures or file write errors
+- **Warnings** - Navigator data parsing issues
+
+---
+
 ## Example configuration
 
 Here's a complete example following the [llmstxt.org](https://llmstxt.org/) best practices:
@@ -189,7 +222,7 @@ Here's a complete example following the [llmstxt.org](https://llmstxt.org/) best
 ```yaml
 antora:
   extensions:
-    - require: ./extensions/antora-llm-generator/llm-generator.js
+    - require: "@pointsharp/antora-llm-generator"
       summary: "Comprehensive documentation for the Acme API, including authentication, endpoints, and best practices."
       details: |
         Important notes:
@@ -224,3 +257,12 @@ Following [llmstxt.org guidelines](https://llmstxt.org/):
 This extension follows the official [llmstxt.org specification](https://llmstxt.org/) for maximum compatibility with LLM tools and agents.
 
 For more details about the specification, visit [https://llmstxt.org/](https://llmstxt.org/).
+
+---
+
+## Copyright and License
+
+Copyright © 2006-present Pointsharp AB.
+
+Use of this software is granted under the terms of the Apache License Version 2.0 (Apache-2.0).  
+See the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) for the full license text.

package/llm-generator.js

@@ -34,8 +34,7 @@ module.exports.register = function (context, { config }) {
   const skipPaths = config.skippaths || [];
   const summary = config.summary || null;
   const details = config.details || null;
-
-  logger.info(`Skip paths: ${JSON.stringify(skipPaths)}`);
+  const debug = config.debug !== undefined ? config.debug : false;
 
   // Helper: Check if a page path matches any skip pattern
   const shouldSkipPath = (path) => {
@@ -43,7 +42,7 @@ module.exports.register = function (context, { config }) {
   };
 
   context.on("beforePublish", ({ contentCatalog, siteCatalog }) => {
-    logger.info("Assembling content for LLM text files using Antora navigation.");
+    if (debug) logger.info("Assembling content for LLM text files using Antora navigation.");
     
     // =============================================================================
     // STEP 1: Detect navigation source
@@ -51,13 +50,15 @@ module.exports.register = function (context, { config }) {
     // Two navigation sources are supported:
     // 1. Antora native navigation (from nav.adoc files)
     // 2. Navigator extension (if installed, creates site-navigation-data.js)
-    const navDataFile = siteCatalog.getFiles().find(f => f.out?.path === 'site-navigation-data.js');
+    const navDataFile = siteCatalog.getFiles().find(f => f.out?.path?.endsWith('site-navigation-data.js'));
     const useNavigatorData = !!navDataFile;
     
-    if (useNavigatorData) {
-      logger.info("Found site-navigation-data.js - will use navigator extension data");
-    } else {
-      logger.info("Navigator extension not detected - will use Antora native navigation");
+    if (debug) {
+      if (useNavigatorData) {
+        logger.info("Found site-navigation-data.js - will use navigator extension data");
+      } else {
+        logger.info("Navigator extension not detected - will use Antora native navigation");
+      }
     }
 
     // =============================================================================
@@ -98,20 +99,20 @@ module.exports.register = function (context, { config }) {
       
       // Skip pages matching skippath patterns from config
       if (shouldSkipPath(page.out.path)) {
-        logger.info(`Skipping page matching skip pattern: ${page.out.path}`);
+        if (debug) logger.info(`Skipping page matching skip pattern: ${page.out.path}`);
         continue;
       }
       
       // Skip pages with :page-llms-ignore: attribute
       if (page.asciidoc.attributes["page-llms-ignore"]) {
-        logger.info(`Skipping page with 'page-llms-ignore' attribute: ${page.src.path}`);
+        if (debug) logger.info(`Skipping page with 'page-llms-ignore' attribute: ${page.src.path}`);
         continue;
       }
       
       pagesByPath.set(page.out.path, page);
     }
     
-    logger.info(`Built pagesByPath map with ${pagesByPath.size} pages`);
+    if (debug) logger.info(`Built pagesByPath map with ${pagesByPath.size} pages`);
 
     // =============================================================================
     // STEP 4: Build navigation sections
@@ -120,18 +121,16 @@ module.exports.register = function (context, { config }) {
     // Each item is a markdown string: "- [Page Title](url): Optional description"
     let componentSections;
     if (useNavigatorData) {
-      // Use navigator extension's site-navigation-data.js
-      logger.info("Using navigator extension data");
-      componentSections = buildSectionsFromNavigatorData(navDataFile, siteUrl, pagesByPath, logger);
+      componentSections = buildSectionsFromNavigatorData(navDataFile, siteUrl, pagesByPath, logger, debug);
     } else {
-      // Use Antora's native navigation structure from component versions
-      logger.info("Using Antora native navigation");
-      componentSections = buildSectionsFromAntoraNavigation(contentCatalog, siteUrl, pagesByPath, logger);
+      componentSections = buildSectionsFromAntoraNavigation(contentCatalog, siteUrl, pagesByPath, logger, debug);
     }
     
-    logger.info(`Component sections map has ${componentSections.size} sections`);
-    for (const [name, items] of componentSections.entries()) {
-      logger.info(`Section "${name}" has ${items.length} items`);
+    if (debug) {
+      logger.info(`Component sections map has ${componentSections.size} sections`);
+      for (const [name, items] of componentSections.entries()) {
+        logger.info(`Section "${name}" has ${items.length} items`);
+      }
     }
 
     // =============================================================================
@@ -154,7 +153,7 @@ module.exports.register = function (context, { config }) {
     for (const [path, page] of pagesByPath.entries()) {
       // Skip pages with :page-llms-full-ignore: attribute
       if (page.asciidoc.attributes["page-llms-full-ignore"]) {
-        logger.info(`Skipping page from full content with 'page-llms-full-ignore' attribute: ${page.src.path}`);
+        if (debug) logger.info(`Skipping page from full content with 'page-llms-full-ignore' attribute: ${page.src.path}`);
         continue;
       }
 
@@ -209,7 +208,7 @@ module.exports.register = function (context, { config }) {
       contents: Buffer.from(UTF8_BOM + indexContent, 'utf8'),
     });
 
-    logger.info("llms.txt and llms-full.txt files have been generated successfully.");
+    logger.info("Generated llms.txt and llms-full.txt");
   });
 };
 
@@ -223,9 +222,10 @@ module.exports.register = function (context, { config }) {
  * @param {string} siteUrl - Base URL of the site
  * @param {Map} pagesByPath - Map of page.out.path -> page object
  * @param {Object} logger - Antora logger instance
+ * @param {boolean} debug - Enable detailed logging
  * @returns {Map} Map of sectionName -> array of formatted navigation items
  */
-function buildSectionsFromNavigatorData(navDataFile, siteUrl, pagesByPath, logger) {
+function buildSectionsFromNavigatorData(navDataFile, siteUrl, pagesByPath, logger, debug) {
   const componentSections = new Map();
   
   try {
@@ -240,7 +240,7 @@ function buildSectionsFromNavigatorData(navDataFile, siteUrl, pagesByPath, logge
     }
     
     const siteNavigationData = JSON.parse(jsonMatch[1]);
-    logger.info(`Parsed ${siteNavigationData.length} components from navigator data`);
+    if (debug) logger.info(`Parsed ${siteNavigationData.length} components from navigator data`);
     
     // Process each component
     for (const component of siteNavigationData) {
@@ -259,8 +259,8 @@ function buildSectionsFromNavigatorData(navDataFile, siteUrl, pagesByPath, logge
         for (const set of version.sets || []) {
           if (set.items && set.items.length > 0) {
             // Recursively collect navigation items
-            const counts = collectNavItems(set.items, sectionArray, siteUrl, pagesByPath, logger);
-            logger.debug(`Component ${component.name}: collected ${counts.found} items`);
+            const counts = collectNavItems(set.items, sectionArray, siteUrl, pagesByPath);
+            if (debug) logger.info(`Component ${component.name}: collected ${counts.found} items`);
           }
         }
       }
@@ -287,9 +287,10 @@ function buildSectionsFromNavigatorData(navDataFile, siteUrl, pagesByPath, logge
  * @param {string} siteUrl - Base URL of the site
  * @param {Map} pagesByPath - Map of page.out.path -> page object
  * @param {Object} logger - Antora logger instance
+ * @param {boolean} debug - Enable detailed logging
  * @returns {Map} Map of sectionName -> array of formatted navigation items
  */
-function buildSectionsFromAntoraNavigation(contentCatalog, siteUrl, pagesByPath, logger) {
+function buildSectionsFromAntoraNavigation(contentCatalog, siteUrl, pagesByPath, logger, debug) {
   const componentSections = new Map();
   const components = contentCatalog.getComponents();
 
@@ -299,12 +300,12 @@ function buildSectionsFromAntoraNavigation(contentCatalog, siteUrl, pagesByPath,
       const componentTitle = version.title || componentName;
       const versionString = version.version;
       
-      logger.info(`Processing component: ${componentName} (${versionString || 'unversioned'})`);
+      if (debug) logger.info(`Processing component: ${componentName} (${versionString || 'unversioned'})`);
       
       // Check if version has parsed navigation tree
       // (version.navigation is populated by Antora after parsing nav.adoc files)
       if (!version.navigation || !Array.isArray(version.navigation) || version.navigation.length === 0) {
-        logger.debug(`No navigation tree found for ${componentName} ${versionString || 'unversioned'}`);
+        if (debug) logger.info(`No navigation tree found for ${componentName} ${versionString || 'unversioned'}`);
         continue;
       }
 
@@ -323,10 +324,9 @@ function buildSectionsFromAntoraNavigation(contentCatalog, siteUrl, pagesByPath,
             navTree.items, 
             sectionArray, 
             siteUrl, 
-            pagesByPath, 
-            logger
+            pagesByPath
           );
-          logger.info(`Section "${sectionName}": collected ${counts.found} pages from navigation`);
+          if (debug) logger.info(`Section "${sectionName}": collected ${counts.found} pages from navigation`);
         }
       }
     }
@@ -373,8 +373,8 @@ function convertRelativeLinksToAbsolute(markdown, baseUrl, logger) {
       const absoluteUrl = new URL(url, baseWithoutFragment).href;
       return `[${text}](${absoluteUrl})`;
     } catch (error) {
-      logger.debug(`Failed to resolve relative URL "${url}" against base "${baseUrl}": ${error.message}`);
-      return match; // Return original if resolution fails
+      // Return original if resolution fails
+      return match;
     }
   });
 }
@@ -400,7 +400,7 @@ function convertRelativeLinksToAbsolute(markdown, baseUrl, logger) {
  * @param {string} indent - Current indentation level (increases with nesting)
  * @returns {Object} Count object: { found: number, notFound: number }
  */
-function collectNavItems(items, collector, siteUrl, pagesByPath, logger, indent = '') {
+function collectNavItems(items, collector, siteUrl, pagesByPath, indent = '') {
   let foundCount = 0;
   let notFoundCount = 0;
   
@@ -439,7 +439,6 @@ function collectNavItems(items, collector, siteUrl, pagesByPath, logger, indent
       } else {
         // URL in navigation doesn't match any page in pagesByPath
         notFoundCount++;
-        logger.debug(`Navigation item URL not found in pages: ${urlPath}`);
       }
     }
     
@@ -456,7 +455,6 @@ function collectNavItems(items, collector, siteUrl, pagesByPath, logger, indent
         collector, 
         siteUrl, 
         pagesByPath, 
-        logger, 
         indent + '  '  // Add 2 spaces for each nesting level
       );
       

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pointsharp/antora-llm-generator",
   "private": false,
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "An Antora extension to generate llms.txt files for LLM consumption following llmstxt.org specification.",
   "main": "llm-generator.js",
   "keywords": [