@feelpp/antora-extensions 1.0.0-rc.2 → 1.0.0-rc.3

package/README.md

@@ -1,3 +1,62 @@
 # Antora Extensions by Feel++
 
+![NPM Version](https://img.shields.io/npm/v/%40feelpp%2Fantora-extensions)
+
 A set of Antora extensions.
+
+## Extensions
+
+### Lunr Search Index
+
+Automatically generates a Lunr.js compatible search index during the Antora build process.
+
+#### Usage
+
+Add the extension to your `site.yml`:
+
+```yaml
+antora:
+  extensions:
+  - '@feelpp/antora-extensions'
+
+config:
+  lunr:
+    indexFile: 'search-index.json'  # Output filename (optional)
+    maxContentLength: 1000          # Max content per document (optional)
+    minContentLength: 50            # Min content to include document (optional)
+    debug: false                    # Enable debug logging (optional)
+```
+
+The search index will be automatically generated at `build/site/search-index.json` after the site is built.
+
+#### Features
+
+- **Zero configuration**: Works out of the box with sensible defaults
+- **Smart content extraction**: Focuses on main content, excludes navigation and footers
+- **Configurable**: Customize content length limits and output location
+- **Performance optimized**: Efficient processing during site generation
+- **Error handling**: Graceful handling of malformed HTML or missing content
+
+## Listing
+
+### UI assumptions
+
+This extension relies on a contract with the UI in order to minimize the configuration the user must perform to get the extension working.
+
+#### Environment variable
+
+When this extension is enabled, it sets the `SITE_LISTING_EXTENSION_ENABLED` environment variable to the value `true`.
+This variable is available to the UI templates as `env.SITE_LISTING_EXTENSION_ENABLED`.
+The existence of this variable informs the UI template that the listing extension is enabled.
+When this variable is set, the UI is expected to add certain elements to support the extension.
+
+#### Listing styles
+
+This package provides additional CSS to style the listing results (`data/css/listing.css`).
+The creator of the UI can either bundle those styles or reference them (for instance in `head-styles.hbs`):
+
+```hbs
+{{#if env.SITE_LISTING_EXTENSION_ENABLED}}
+    <link rel="stylesheet" href="{{{uiRootPath}}}/css/listing.css">
+{{/if}}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@feelpp/antora-extensions",
   "private": false,
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.3",
   "description": "Antora Extensions by Feel++.",
   "main": "src/index.js",
   "repository": {
@@ -11,12 +11,20 @@
   "keywords": [],
   "author": "Guillaume Grossetie <ggrossetie@yuzutech.fr>",
   "license": "MIT",
+  "scripts": {
+    "test": "mocha tests/*-test.js"
+  },
   "bugs": {
     "url": "https://github.com/feelpp/feelpp-antora-extensions/issues"
   },
   "homepage": "https://github.com/feelpp/feelpp-antora-extensions#readme",
   "devDependencies": {
+    "chai": "^4.3.7",
+    "mocha": "^10.2.0",
     "libnpmpublish": "^4.0.2",
     "pacote": "^12.0.2"
+  },
+  "dependencies": {
+    "jsdom": "^20.0.3"
   }
 }

package/src/index.js

@@ -1,7 +1,9 @@
 const {register: registerTooboxNavigation} = require('./toolbox-navigation.js')
 const {register: registerListing} = require('./listing.js')
+const {register: registerLunr} = require('./lunr.js')
 
 module.exports.register = (thisContext, args) => {
   registerTooboxNavigation.call(thisContext, args)
   registerListing.call(thisContext, args)
+  registerLunr.call(thisContext, args)
 }

package/src/lunr.js

@@ -0,0 +1,145 @@
+/**
+ * Antora extension for automatic Lunr.js search index generation
+ * 
+ * This extension automatically generates a Lunr.js compatible search index
+ * after the site is published. It extracts content from all HTML files
+ * and creates a JSON index that can be used for client-side search.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+// Lazy load JSDOM only when needed
+let JSDOM
+function loadJSDOM() {
+  if (!JSDOM) {
+    try {
+      JSDOM = require('jsdom').JSDOM
+    } catch (error) {
+      throw new Error('JSDOM is required for the Lunr extension. Install it with: npm install jsdom')
+    }
+  }
+  return JSDOM
+}
+
+function register({ config, playbook }) {
+  const logger = this.getLogger('lunr-extension')
+  
+  this.once('sitePublished', (event) => {
+    logger.info('Generating Lunr.js search index...')
+    
+    try {
+      // Get output directory from the playbook
+      const outputDir = playbook.output?.dir || 'build/site'
+      logger.info(`Output directory: ${outputDir}`)
+      
+      generateSearchIndex(outputDir, config.lunr || {}, logger)
+    } catch (error) {
+      logger.error('Failed to generate search index:', error)
+      throw error
+    }
+  })
+}
+
+function generateSearchIndex(outputDir, config = {}, logger) {
+  const searchIndexFile = path.join(outputDir, config.indexFile || 'search-index.json')
+  const maxContentLength = config.maxContentLength || 1000
+  const minContentLength = config.minContentLength || 50
+  
+  // Find all HTML files
+  const htmlFiles = walkDirectory(outputDir).filter(file => file.endsWith('.html'))
+  const documents = []
+  let id = 0
+  
+  htmlFiles.forEach(filePath => {
+    try {
+      const html = fs.readFileSync(filePath, 'utf8')
+      const title = getTitle(html)
+      const content = extractTextContent(html)
+      
+      // Skip empty content
+      if (!content || content.length < minContentLength) {
+        return
+      }
+      
+      // Generate relative URL
+      const relativePath = path.relative(outputDir, filePath)
+      const url = '/' + relativePath.replace(/\\/g, '/').replace(/\/index\.html$/, '/')
+      
+      documents.push({
+        id: ++id,
+        title: title,
+        content: content.substring(0, maxContentLength),
+        url: url
+      })
+      
+      if (config.debug) {
+        logger.debug(`Indexed: ${title} (${url})`)
+      }
+    } catch (error) {
+      logger.warn(`Failed to process ${filePath}:`, error.message)
+    }
+  })
+  
+  const searchIndex = {
+    documents: documents
+  }
+  
+  // Write search index
+  fs.writeFileSync(searchIndexFile, JSON.stringify(searchIndex, null, 2))
+  logger.info(`Search index generated: ${documents.length} documents → ${searchIndexFile}`)
+}
+
+function extractTextContent(html) {
+  try {
+    const JSDOM = loadJSDOM()
+    const dom = new JSDOM(html)
+    const document = dom.window.document
+    
+    // Remove script and style elements
+    const scripts = document.querySelectorAll('script, style, nav, .navbar, .footer')
+    scripts.forEach(el => el.remove())
+    
+    // Get main content area
+    const main = document.querySelector('main, .main, .content, article')
+    const content = main || document.body
+    
+    return content.textContent.trim().replace(/\s+/g, ' ')
+  } catch (error) {
+    return ''
+  }
+}
+
+function getTitle(html) {
+  try {
+    const JSDOM = loadJSDOM()
+    const dom = new JSDOM(html)
+    const titleEl = dom.window.document.querySelector('title, h1, .page-title')
+    return titleEl ? titleEl.textContent.trim() : 'Untitled'
+  } catch (error) {
+    return 'Untitled'
+  }
+}
+
+function walkDirectory(dir, fileList = []) {
+  if (!fs.existsSync(dir)) {
+    return fileList
+  }
+  
+  const files = fs.readdirSync(dir)
+  
+  files.forEach(file => {
+    const filePath = path.join(dir, file)
+    const stat = fs.statSync(filePath)
+    
+    if (stat.isDirectory()) {
+      walkDirectory(filePath, fileList)
+    } else {
+      fileList.push(filePath)
+    }
+  })
+  
+  return fileList
+}
+
+module.exports = { register }

package/tests/lunr-test.js

@@ -0,0 +1,36 @@
+const { describe, it } = require('mocha')
+const { expect } = require('chai')
+const fs = require('fs')
+const path = require('path')
+
+describe('Lunr extension', () => {
+  const { register } = require('../src/lunr.js')
+  
+  it('should export a register function', () => {
+    expect(register).to.be.a('function')
+  })
+  
+  it('should register with Antora context', () => {
+    let eventRegistered = false
+    const mockContext = {
+      getLogger: () => ({
+        info: () => {},
+        error: () => {},
+        debug: () => {},
+        warn: () => {}
+      }),
+      once: (event, handler) => {
+        if (event === 'sitePublished') {
+          eventRegistered = true
+        }
+      }
+    }
+    
+    const config = {}
+    const playbook = { output: { dir: 'build/site' } }
+    
+    register.call(mockContext, { config, playbook })
+    
+    expect(eventRegistered).to.be.true
+  })
+})