@feelpp/antora-extensions 1.0.0-rc.1 → 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/data/css/listing.css

@@ -0,0 +1,79 @@
+.listing .listing-container {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-start;
+  margin-top: 5em;
+  margin-bottom: 5em;
+  gap: clamp(1.5em, 2vw, 5em);
+}
+
+.listing .listing-container .listing-card-container {
+  display: flex;
+  flex: 1 calc(33.33% - 5em);
+  max-width: 500px;
+}
+
+/* Media query for small screens */
+@media (max-width: 767px) {
+  .listing .listing-container .listing-card-container {
+    flex: 1 250px;
+  }
+}
+
+/* Media query for large screens */
+@media (min-width: 768px) {
+  .listing .listing-container .listing-card-container {
+    min-width: 250px;
+  }
+}
+
+.listing .listing-card:hover,
+.listing .listing-card:focus {
+  box-shadow: 0 6px 12px 1px #104d92ad;
+  text-decoration: none;
+}
+
+.listing .listing-card {
+  box-shadow: 0 3px 6px 1px #e0e0e0;
+  padding: 1.5em 1em 1em;
+  display: flex;
+  flex-direction: column;
+  color: initial;
+  border-radius: 0.5em;
+  flex: 1;
+}
+
+.listing .listing-card-illustration {
+  height: 150px;
+  object-fit: contain;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding-left: 1em;
+  padding-right: 1em;
+}
+
+.listing .listing-card-illustration > img {
+  max-width: 100%;
+  height: 100%;
+  object-fit: cover;
+  border-radius: 0.25em;
+}
+
+.listing .listing-card .listing-card-body {
+  border-top: 1px solid #e1e1e1;
+  margin-top: 1rem;
+  padding-bottom: 0.75rem;
+  margin-left: 0.75rem;
+  margin-right: 0.75rem;
+}
+
+.listing .listing-card .listing-card-body p {
+  font-size: 0.9em;
+  color: #56595c;
+}
+
+.listing .listing-card .listing-card-body h4 {
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}

package/data/helpers/image-spec.js

@@ -0,0 +1,17 @@
+'use strict'
+
+/**
+ * Adds image$ family if missing
+ * @param {string} spec
+ * @returns {string}
+ */
+module.exports = (spec) => {
+  if (!spec || spec.includes('image$') || spec.startsWith('http://') || spec.startsWith('https://')) {
+    return spec
+  }
+  const lastColon = spec.lastIndexOf(':')
+  if (lastColon > 0 && lastColon < spec.length - 1) {
+    return spec.slice(0, lastColon + 1) + 'image$' + spec.slice(lastColon + 1)
+  }
+  return 'image$' + spec
+}

package/data/helpers/listing-get-sections.js

@@ -0,0 +1,43 @@
+'use strict'
+
+const listingConfig = ${listingConfig}
+
+module.exports = (configName, page, {data: {root}}) => {
+  const {contentCatalog} = root
+  if (configName in listingConfig) {
+    const config = listingConfig[configName]
+    if (config) {
+      return config.map((section) => {
+        const selector = {
+          tag: section.tag,
+          withinParentModule: section.withinParentModule
+        }
+        const pages = getPages(contentCatalog, page, selector)
+        return {
+          title: section.sectionTitle,
+          pages,
+        }
+      })
+    }
+  }
+  return []
+}
+
+const getPages = function (contentCatalog, page, {tag, withinParentModule}) {
+  const pages = contentCatalog.getPages(({asciidoc, out, src}) => {
+    if (!out || !asciidoc) return
+    if (src.component !== page.componentVersion.name ||
+      (withinParentModule && src.module !== page.module) ||
+      src.version !== page.componentVersion.version) return
+    const pageTags = asciidoc.attributes['page-tags']
+    return pageTags && pageTags.split(',').map((v) => v.trim()).includes(tag)
+  }).sort((a, b) => (a.title || '').localeCompare((b.title || '')))
+  if (pages && pages.length > 0) {
+    while (pages.length % 3 !== 0) {
+      pages.push({
+        empty: true,
+      })
+    }
+  }
+  return pages
+}

package/data/helpers/resolve-resource-url.js

@@ -0,0 +1,13 @@
+'use strict'
+
+module.exports = (spec, { data, hash: context }) => {
+  if (!spec) return
+  const { contentCatalog, page } = data.root
+  if (page.component) {
+    context = Object.assign({ component: page.component.name, version: page.version, module: page.module }, context)
+  }
+  const file = contentCatalog.resolveResource(spec, context, 'page', ['page', 'attachment', 'image'])
+  if (file) {
+    return file.pub.url
+  }
+}

package/data/partials/listing-card.hbs

@@ -0,0 +1,13 @@
+{{#if empty}}
+  <div class="empty"></div>
+{{else}}
+  <a class="listing-card" href="{{{relativize pub.url}}}">
+    <div class="listing-card-illustration">
+      <img alt="" src="{{relativize (resolve-resource-url (image-spec asciidoc.attributes.page-illustration))}}"/>
+    </div>
+    <div class="listing-card-body">
+      <h4>{{title}}</h4>
+      <p class="listing-card-description">{{{asciidoc.attributes.description}}}</p>
+    </div>
+  </a>
+{{/if}}

package/data/partials/listing.hbs

@@ -0,0 +1,16 @@
+<div class="listing">
+  {{#with (listing-get-sections configName @root.page)}}
+    {{#if this.length}}
+      {{#each this}}
+        {{#if this.pages.length}}
+          <h2>{{{this.title}}}</h2>
+          <div class="listing-container">
+            {{#each this.pages}}
+              <div class="listing-card-container">{{> listing-card this}}</div>
+            {{/each}}
+          </div>
+        {{/if}}
+      {{/each}}
+    {{/if}}
+  {{/with}}
+</div>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@feelpp/antora-extensions",
   "private": false,
-  "version": "1.0.0-rc.1",
+  "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,5 +1,9 @@
-const { register: registerTooboxNavigation } = require('./toolbox-navigation.js')
+const {register: registerTooboxNavigation} = require('./toolbox-navigation.js')
+const {register: registerListing} = require('./listing.js')
+const {register: registerLunr} = require('./lunr.js')
 
-module.exports.register = (context) => {
-  registerTooboxNavigation(context)
+module.exports.register = (thisContext, args) => {
+  registerTooboxNavigation.call(thisContext, args)
+  registerListing.call(thisContext, args)
+  registerLunr.call(thisContext, args)
 }

package/src/lazy-readable.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const { PassThrough } = require('stream')
+
+// adapted from https://github.com/jpommerening/node-lazystream/blob/master/lib/lazystream.js | license: MIT
+class LazyReadable extends PassThrough {
+  constructor (fn, options) {
+    super(options)
+    this._read = function () {
+      delete this._read // restores original method
+      fn.call(this, options).on('error', this.emit.bind(this, 'error')).pipe(this)
+      return this._read.apply(this, arguments)
+    }
+    this.emit('readable')
+  }
+}
+
+module.exports = LazyReadable
+

package/src/listing.js

@@ -0,0 +1,108 @@
+'use strict'
+
+// The name of the package in order to give the Antora logger a useful name
+const fs = require('fs')
+const ospath = require('path')
+const { promises: fsp } = fs
+const LazyReadable = require('./lazy-readable')
+const template = require('./template')
+
+/**
+ * @module listing-extension
+ */
+function register ({ config: { listing, ...unknownOptions } }) {
+  const packageName = "@feelpp/antora-listing-extension"
+  const logger = this.getLogger(packageName)
+
+  if (Object.keys(unknownOptions).length) {
+    const keys = Object.keys(unknownOptions)
+    throw new Error(`Unrecognized option${keys.length > 1 ? 's' : ''} specified for ${packageName}: ${keys.join(', ')}`)
+  }
+
+  this.on('uiLoaded', async ({playbook, uiCatalog}) => {
+    playbook.env.SITE_LISTING_EXTENSION_ENABLED = 'true'
+    const uiOutputDir = playbook.ui.outputDir
+    assetFile(uiCatalog, logger, uiOutputDir, 'css', 'listing.css')
+    const helperPath = 'helpers/listing-get-sections.js'
+    if (uiCatalog.findByType('helper').some(({ path }) => path === helperPath)) {
+      // ignore
+    } else {
+      const helperFilePath = ospath.join(__dirname, '../data', helperPath)
+      uiCatalog.addFile({
+        contents: Buffer.from(template(await fsp.readFile(helperFilePath, 'utf8'), {listingConfig: JSON.stringify(listing)})),
+        path: helperPath,
+        stem: ospath.parse(helperPath).name,
+        type: 'helper',
+      })
+    }
+    await helperFile(uiCatalog, 'helpers/image-spec.js')
+    await helperFile(uiCatalog, 'helpers/resolve-resource-url.js')
+    await partialFile(uiCatalog, 'partials/listing.hbs')
+    await partialFile(uiCatalog, 'partials/listing-card.hbs')
+  })
+
+  this.on('beforePublish', ({ playbook }) => {
+    delete playbook.env.SITE_LISTING_EXTENSION_ENABLED
+  })
+
+
+  async function partialFile(uiCatalog, partialPath) {
+    if (uiCatalog.findByType('partial').some(({ path }) => path === partialPath)) {
+      // ignore
+    } else {
+      const partialFilePath = ospath.join(__dirname, '../data', partialPath)
+      uiCatalog.addFile({
+        contents: Buffer.from(await fsp.readFile(partialFilePath, 'utf8')),
+        path: partialPath,
+        stem: ospath.parse(partialPath).name,
+        type: 'partial',
+      })
+    }
+  }
+
+  async function helperFile(uiCatalog, helperPath) {
+    if (uiCatalog.findByType('helper').some(({ path }) => path === helperPath)) {
+      // ignore
+    } else {
+      const helperFilePath = ospath.join(__dirname, '../data', helperPath)
+      uiCatalog.addFile({
+        contents: Buffer.from(await fsp.readFile(helperFilePath, 'utf8')),
+        path: helperPath,
+        stem: ospath.parse(helperPath).name,
+        type: 'helper',
+      })
+    }
+  }
+
+  function assetFile (
+    uiCatalog,
+    logger,
+    uiOutputDir,
+    assetDir,
+    basename,
+    assetPath = assetDir + '/' + basename,
+    contents = new LazyReadable(() => fs.createReadStream(ospath.join(__dirname, '../data', assetPath))),
+    overwrite = false
+  ) {
+    const outputDir = uiOutputDir + '/' + assetDir
+    const existingFile = uiCatalog.findByType('asset').some(({path}) => path === assetPath)
+    if (existingFile) {
+      if (overwrite) {
+        logger.warn(`Please remove the following file from your UI since it is managed by ${packageName}: ${assetPath}`)
+        existingFile.contents = contents
+        delete existingFile.stat
+      } else {
+        logger.info(`The following file already exists in your UI: ${assetPath}, skipping`)
+      }
+    } else {
+      uiCatalog.addFile({
+        contents,
+        type: 'asset',
+        path: assetPath,
+        out: {dirname: outputDir, path: outputDir + '/' + basename, basename},
+      })
+    }
+  }
+}
+
+module.exports.register = register

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/src/template.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (string, vars) => string.replace(/\${(.+?)}/g, (_, name) => vars[name])

package/src/toolbox-navigation.js

@@ -16,9 +16,9 @@ function getToolboxPageModules(contentCatalog, version, tag) {
   }, {})
 }
 
-module.exports.register = (context) => {
-  const logger = context.getLogger('toolbox-navigation')
-  context.on('navigationBuilt', ({contentCatalog, navigationCatalog}) => {
+function register() {
+  const logger = this.getLogger('toolbox-navigation')
+  this.on('navigationBuilt', ({contentCatalog, navigationCatalog}) => {
     const toolboxComponent = contentCatalog.getComponent('toolboxes')
     if (toolboxComponent) {
       const componentVersions = toolboxComponent.versions
@@ -91,3 +91,5 @@ module.exports.register = (context) => {
     }
   })
 }
+
+module.exports.register = 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
+  })
+})