Search Setup

The Feel++ Antora UI provides two search options: Lunr.js for client-side search and Algolia DocSearch for server-based search. The UI automatically detects which search system to use based on your site configuration.

The UI includes the Lunr browser client. Enable index generation explicitly in every documentation repository with @feelpp/antora-extensions.

1. Lunr Search

1.1. Configure the Site

Add the extension to site.yml:

# site.yml
antora:
  extensions:
    - require: '@feelpp/antora-extensions'
      lunr:
        indexFile: search-index.json
        maxContentLength: 1000
        minContentLength: 50

Set site.url to the public deployment URL. Its pathname is used both to fetch the index and to create result links. For example, a GitHub Pages project site must use its project path:

site:
  url: https://feelpp.github.io/course-rom/

Install the extension with the other Antora build dependencies:

{
  "dependencies": {
    "@antora/cli": "^3.1.12",
    "@antora/site-generator": "^3.1.12",
    "@feelpp/antora-extensions": "1.0.0"
  },
  "scripts": {
    "build": "npx antora site.yml --stacktrace"
  }
}

Run the normal Antora build:

npm run build

1.2. How It Works

The extension listens for Antora’s sitePublished event and then:

  • Scans generated HTML pages, excluding the fallback 404.html page.

  • Extracts titles and readable page text.

  • Writes search-index.json to the site output directory.

  • Prefixes result URLs with the pathname from site.url.

1.3. Configuration Options

The lunr mapping supports these optional fields:

  • indexFile: output filename; defaults to search-index.json.

  • maxContentLength: maximum indexed characters per page; defaults to 1000.

  • minContentLength: minimum indexed characters required to include a page; defaults to 50.

  • debug: writes extraction diagnostics when true.

2. Algolia DocSearch Integration

For sites using Algolia DocSearch (like docs.feelpp.org), the UI automatically detects and uses the existing configuration.

When a DocSearch API key is present in the UI configuration, the UI does not initialize Lunr. No Lunr index configuration is needed for such a site.

3. Troubleshooting

3.1. Lunr.js Issues

Search index not loading

  • Verify @feelpp/antora-extensions is installed and configured in site.yml

  • Verify that site.url matches the public URL, including a GitHub Pages project pathname

  • Ensure the generated search-index.json is accessible via HTTP(S)

  • Check browser console for loading errors

No search results

  • Verify the search index contains documents at the deployment path, for example /course-rom/search-index.json

  • Adjust minContentLength when short pages need to be indexed

  • Try rebuilding the site completely

Performance issues

  • Large search indexes (>1MB) may cause slow loading

  • Use maxContentLength to limit document size

Extension not running

  • Verify @feelpp/antora-extensions is listed in your site.yml extensions

  • Check the terminal output during build for extension loading messages

  • Ensure you’re using a compatible Antora version (3.1+)

3.2. Algolia DocSearch Issues

Search not initializing

  • Verify your API credentials are correct

  • Check that the index name matches your Algolia configuration

  • Ensure the DocSearch script is loading properly

Missing CSS styling

  • Verify the DocSearch CSS is being loaded

  • Check for CSS conflicts with the UI theme

4. Development

4.1. Local Development

For local development with search:

# Build site with automatic search index generation
npm run build

# Start development server
cd build/site
python3 -m http.server 8080

# Open browser to http://localhost:8080

The search index is automatically generated during the build process, so there’s no need for separate search generation commands.

4.2. Search Index Structure

The automatically generated Lunr.js search index has this structure:

{
  "documents": [
    {
      "id": 1,
      "title": "Page Title",
      "content": "Page content text...",
      "url": "/page-path.html"
    }
  ]
}

4.3. Customization

To customize search behavior:

  • Extension configuration: Modify search index generation in site.yml

  • UI behavior: Edit src/js/07-search.js for search logic and UI behavior

  • Styling: Modify src/css/lunr-search.css for search styling and responsive design

  • Content extraction: Use extension configuration options rather than modifying generation scripts

5. Migration from Manual to Automated Search

If migrating from the old manual search setup to @feelpp/antora-extensions:

5.1. From Manual Lunr.js Setup

  1. Remove manual dependencies: Remove lunr and jsdom from devDependencies

  2. Remove manual scripts: Delete build:search and generate-search-index.js

  3. Add extension: Install and configure @feelpp/antora-extensions

  4. Update build process: Use single npm run build command instead of build:full

  5. Clean up: Remove old search generation files and scripts

5.2. From Algolia to Lunr.js

If migrating from Algolia DocSearch to automated Lunr.js:

  1. Remove Algolia configuration from your site

  2. Add @feelpp/antora-extensions to your site.yml

  3. Install the extension via npm

  4. Run your normal build - search index will be generated automatically

  5. Test search functionality thoroughly

The transition should be seamless as both systems use the same search input element and similar styling.

5.3. Benefits of Automated Approach

  • Zero maintenance: No manual scripts to maintain or copy between projects

  • Consistent behavior: Same search functionality across all Feel++ documentation sites

  • Automatic updates: Extension updates provide improvements and bug fixes

  • Simplified builds: Single command builds everything including search

  • Better performance: Optimized index generation and content extraction