eskwayrd/antora-indexer-poc

Demonstrates how to add lunr.js indexing to Antora builds, and a search UI to the Antora default UI.

antora-indexer-poc

Caution

Antora search has matured notably since this repo was created. This repo is no longer maintained, and has been archived for posterity. You should use the antora-lunr extension with Antora 3.1.x for your Antora-generated documentation search needs.

This repo demonstrates how to add lunr.js indexing to Antora builds, and a search UI to the Antora default UI.

Note	This is a proof of concept. It should work, but there are no guarantees. The code has not been tested on Windows. The search UI has only been tested in Google Chrome. Improvements to make the search UI responsive have not yet been made.

Usage

Easy

Run make, which:

• Installs dependencies.

• Runs Antora to generate HTML and produce an index

• Runs serve so that you can browse the HTML and use the search UI

Individual steps

Follow these steps if you don’t have make installed, or you want to see how everything works:

1. Install all of the dependencies:

   npm i

2. Run Antora to generate HTML and an index:

   node_modules/.bin/antora --generator=./generator/generator.js antora-playbook.yml

By default, the HTML and index are place in the public folder.

1. Run serve to start a web service so that you can browse the HTML and use the search UI:

   node_modules/.bin/serve public/

   Serve emits URLs that you can use, e.g. http://localhost:5000. Copy the URL into your browser.

Search UI

The search UI is implemented as a drop-down menu, containing all matching entries. Results update immediately as you type. Use the kbd:[Arrow Up] and kbd:[Arrow Down] keys to select a result, and press kbd:[Enter] to navigate to that result (or just click). Press kbd:[Escape] to close the results.

Notes

• The included antora-playbook.yml is configured to use the Antora documentation. This demonstrates an excellent Antora feature: you can generate HTML for any documentation that exists in an Antora component in any accessible Git-based repository.

  Antora’s documentation is comprised of two components, one for Antora itself and another for its UI, and the Antora component has multiple versions. This is useful to demonstrate the 'faceting' of the search results, which are combined into groups based on the component
  version.

• You can use the search with your own documentation by revising the content: section of the antora-playbook.yml file.

• The supplemental_ui folder contains the search UI, as override files for Antora’s default UI.

• lunr indexes can often become quite large. The pako library is used to compress the index when it is created, and is also used to decompress the index in the browser. Typically, the compressed index is about 20% the size of the uncompressed index.

  As such, using lunr for search is best for sites with only a modest amount of content. Large sites likely require a search service, such as Algolia, to avoid distributing large indexes to all new users of your documentation site.

Authors

• Ewan Edwards

• Dan Allen, who wrote Asciidoctor and Antora

• Guillaume Grossetie, who wrote antora-lunr

Copyright and License

Copyright © 2019 by the contributing authors.

Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0). See LICENSE to find the full license text.

antora-indexer-poc's Issues

Use handlebars to template the search results

Currently, all search results are generated by Javascript manipulating the DOM.

It would be better if handlebars templates were used instead, so that the result presentation could be easily customized without having to understand everything else going on in the result processing.

Add configuration to permit definition of content to be indexed.

Currently, all content within the <article> tag is indexed. It could be useful to be more selective, and avoid including verbatim blocks, admonitions, etc.

The content selector would be mandatory, as it helps focus on the page content instead of header/footer content. All other selectors would be subtractive, thereby removing content from indexing consideration.