Algolia Search Integration

A cloud account with Algolia is required to implement Algolia as a cloud-search provider.

By default, AsciiDocsy’s own Algolia application is configured in the repo. You will be able to generate local content packages for it, or query its live indices, but you will not be able to write (push) to the cloud indices.

The Algolia signup is free. You only start paying when you use certain thresholds of index space or query bandwidth.

AsciiDocsy’s implementation of Algolia’s Jekyll plugin (source) (docs) and instantsearch form (docs).

Search Settings

The site.algolia object, by default defined in _config.yml.

Object: site.algolia
algolia:
  application_id: 'SELDDHION6'
  search_only_api_key: 'b9112b0485d58729c3e7c7b64291cbd9'

Additionally, each search form on your site needs some more data. By default the search forms draw this info from objects inside site.data.theme.search, such as search-site and search-subject. These objects need properties for show.spot and meta.index.

Object: site.data.theme.search.site
  show:
    text: Search non-docs PAGES…
    spot: "#nav-site"
  meta:
    index: asciidocsy-pages
    id: search-site
These settings are only used for searching.

Index Settings

In order to index your site’s content, you will need an auxilliary configuration file with the algolia object at the root. This configuration file can be called instead of or in addition to the main Jekyll config.

_docs/_data/configs/search-index-pages.yml
algolia:
  application_id: 'SELDDHION6'
  index_name: asciidocsy-pages
  extensions_to_index: [adoc,html]
  files_to_exclude:
    - _docs/topics/**

The search is performed by running a jekyll algolia operation with your private API key added.

ENV Variable

One option is to add your key explicitly to the commandline as an environment variable.

Example commandline ENV variable option
ALGOLIA_API_KEY=01d664977165dbf4cded12199738fabf bundle exec jekyll algolia --config _config.yml,_data/configs/jekyll-search-x.yml

Stashed File

Alternatively, stash the key as in a file called _algolia_api_key (no file extension).

Entire contents of file _algolia_option_key
01d664977165dbf4cded12199738fabf
Be sure to add this file to your .gitignore file.

In this case, you may run the following.

Example commandline with no ENV variable
bundle exec jekyll algolia --config _config.yml,_data/configs/jekyll-search-x.yml`
To test your indexing process without pushing to Algolia, add --dry-run (or simply -n)

For full configuration options, refer to the Jekyll community documentation.

Feedback, please.