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.

Search functionality is now fully automated through the @feelpp/antora-extensions package, eliminating the need for manual search index generation.

1. Search Options Overview

Search Type Best For Requirements

Lunr.js (Default)

Small to medium sites, self-hosted sites, privacy-focused environments

@feelpp/antora-extensions package (automatic)

Algolia DocSearch

Large sites, sites with complex search requirements, existing Algolia integration

Algolia account and DocSearch configuration

2. Lunr.js Client-Side Search

Lunr.js provides full-text search capabilities directly in the browser without requiring any external services. Search index generation is completely automated through the @feelpp/antora-extensions package.

2.1. Automatic Setup

The UI includes Lunr.js search by default. When you build your site with the Feel++ Antora UI, search functionality is automatically available:

  1. The @feelpp/antora-extensions package automatically generates search-index.json during site builds

  2. The UI bundle includes Lunr.js for client-side search functionality

  3. No manual configuration or build steps required

2.2. Quick Start for New Sites

To add search to a new Antora site:

2.2.1. 1. Install the Extension

Add the Feel++ Antora extensions to your site configuration:

# site.yml
antora:
  extensions:
    - '@feelpp/antora-extensions'

2.2.2. 2. Update package.json

Add the extension to your dependencies:

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

2.2.3. 3. Build Your Site

Simply run your normal Antora build:

# Single command builds everything including search index
npm run build

That’s it! The search index is automatically generated during the build process.

2.3. How It Works

The @feelpp/antora-extensions package includes a Lunr extension that:

  • Automatically generates search index: During the sitePublished event, the extension scans all generated HTML files

  • Extracts content intelligently: Page titles, content, and URLs are extracted using JSDOM

  • Creates optimized index: Generates a compact search-index.json file in your site root

  • Supports configuration: Configurable content selectors and indexing options

The extension runs seamlessly during your normal Antora build process - no additional commands needed.

2.4. Configuration Options

You can customize the search index generation by adding configuration to your site.yml:

# site.yml
antora:
  extensions:
    - require: '@feelpp/antora-extensions'
      lunr_index_generation:
        content_selector: 'article.doc .content'  # CSS selector for content
        exclude_selectors:                        # Content to exclude
          - '.navigation'
          - '.page-toc'
          - 'pre code'
        boost_title: 10                          # Title importance multiplier

2.5. Advanced Configuration

For advanced use cases, you can configure multiple content areas or custom extraction logic:

# site.yml
antora:
  extensions:
    - require: '@feelpp/antora-extensions'
      lunr_index_generation:
        content_selectors:
          - selector: 'h1, h2, h3'
            boost: 5
          - selector: '.content p'
            boost: 1
          - selector: '.sidebar'
            boost: 0.5
        min_content_length: 10        # Minimum content length to index
        max_content_length: 1000      # Maximum content length per document

2.6. Search UI Features

The Lunr.js implementation provides:

  • Real-time search: Results appear as you type (minimum 2 characters)

  • Fuzzy matching: Finds results even with minor typos

  • Field boosting: Page titles are weighted higher than content

  • Responsive design: Adapts to different screen sizes

  • Keyboard navigation: Use arrow keys and Enter to navigate results

2.7. Responsive Search Results

The search dropdown automatically adjusts its width based on screen size:

  • Mobile (< 768px): Full-width dropdown with optimized touch targets

  • Tablets (768px - 1199px): Minimum 500px width, up to 80% of viewport

  • Desktop (≥ 1200px): Minimum 600px width, up to 70% of viewport

3. Algolia DocSearch Integration

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

3.1. Configuration Detection

The UI checks for Algolia configuration in this order:

  1. #search-script element with data attributes

  2. Global Algolia configuration variables

  3. Existing DocSearch initialization

3.2. Setup for Algolia DocSearch

If you want to use Algolia DocSearch:

3.2.1. 1. Add Configuration Script

Add this to your site’s head or before the closing body tag:

<script id="search-script"
        data-app-id="YOUR_APP_ID"
        data-api-key="YOUR_API_KEY"
        data-index-name="YOUR_INDEX_NAME"
        data-stylesheet="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css">
</script>

3.2.2. 2. Site Configuration

In your antora.yml or site configuration:

asciidoc:
  attributes:
    algolia-app-id: YOUR_APP_ID
    algolia-api-key: YOUR_API_KEY
    algolia-index-name: YOUR_INDEX_NAME

4. Search Behavior

4.1. Automatic Detection Logic

The UI uses this detection logic:

  1. Check for Algolia: If DocSearch configuration exists, use Algolia

  2. Check for Lunr Index: If search-index.json exists, use Lunr.js (automatically generated by @feelpp/antora-extensions)

  3. Fallback: Show "Search not available" message

4.2. Search Input

Both search systems use the same search input element:

<input type="text" id="search-query" placeholder="Search {site.title}">

4.3. Styling

The search interface is styled consistently regardless of the backend:

  • Search input integrates with the navigation bar

  • Results dropdown uses the same design language

  • Responsive behavior works with both systems

5. Troubleshooting

5.1. Lunr.js Issues

Search index not loading

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

  • Check that the extension is running during the build process

  • 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 by checking /search-index.json in your browser

  • Check that page content is being extracted properly (review content selectors)

  • Try rebuilding the site completely

Performance issues

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

  • Use exclude_selectors to remove unnecessary content from indexing

  • Consider using max_content_length 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+)

5.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

6. Development

6.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.

6.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"
    }
  ]
}

6.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

7. Migration from Manual to Automated Search

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

7.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

7.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.

7.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