Options

The plugin should work out of the box for most websites, but there are options you can tweak if needed. All the options should be added under the algolia section of your _config.yml file.

You should be familiar with how this plugin works under the hood to better understand what some options are doing.

extensions_to_index

This options defines which source files should be indexed, based on their file extension. If an extension is not in the list, then the file will not be indexed.

By default, all HTML and markdown source files will be indexed.

If you are using another markup language (such as AsciiDoc or Textile), you might want to update the value like this:

algolia:
  # Also index AsciiDoc and Textile files
  extensions_to_index:
    - html
    - md
    - adoc
    - textile

files_to_exclude

This option lets you define a list of source files you don’t want to index.

By default it will exclude the index.html and index.md files found at the root. Those files are usually not containing much text (landing pages) or containing redundant text (latest blog articles) so they are not included by default.

If you want to index those files, you should set the value to an empty array.

algolia:
  # Actually index the index.html/index.md pages
  files_to_exclude: []

If you want to exclude more files, you should add them to the array. Note that you can use glob patterns (* and **) to exclude several files at once.

algolia:
  # Exclude more files from indexing
  files_to_exclude:
    - index.html
    - index.md
    - excluded-file.html
    - _posts/2017-01-20-date-to-forget.md
    - subdirectory/*.html
    - **/*.tmp.html

Note that some files (pagination pages, static assets, etc) will always be excluded and you don’t have to specify them.

nodes_to_index

This options defines how each page is split into chunks. It expects a CSS selector that will be applied on the HTML content generated by Jekyll. Each matching node will be indexed as a different record.

The default value is p, meaning that one record will be created for each <p> paragraph of content.

If you would like to index other elements, like <blockquote>, <li> or a custom <div class="paragraph">, you should edit the value like this:

algolia:
  # Also index quotes, list items and custom paragraphs
  nodes_to_index: 'p,blockquote,li,div.paragraph'

settings

This option let you pass specific settings to your Algolia index.

By default the plugin will configure your Algolia index with settings tailored to the format of the extracted records. You are of course free to overwrite them or configure them as best suits your needs. Every option passed to the settings entry will be set as setting to your index.

For example if you want to change the HTML tag used for the highlighting, you can overwrite it like this:

algolia:
  settings:
    highlightPreTag: '<em class="custom_highlight">'
    highlightPostTag: '</em>'

Settings defined here will take precedence over any setting you manually defined through the Algolia dashboard UI, though. If you’d like this not to happen at all, and only take the dashboard settings in account, pass false to the settings configuration.

algolia:
  settings: false

We suggest users to at least run with the default settings once, so that the default relevance settings are set, which you can override via the dashboard after.

indexing_batch_size

This option defines the number of operations that will be grouped as part of one updating batch. All operations of one batch are applied atomically. The default value is 1000.

You might want to increase this value if you are doing a lot of updates on each run and still want to have your changes done atomically.

You might want to decrease this value if you’re using an unstable internet connection. Smaller batches are easier to send that large ones.

algolia:
  # Send fewer records per batch
  indexing_batch_size: 500

max_record_size

This is an advanced option. It has no effect on Community plans.

If you’re using a paid Algolia plan, you can push records that weight up to 20Kb (as opposed to 10Kb with the free Community plan). This option allows you to adjust the maximum size of one record (in bytes).

algolia:
  # Recommended setting for paid plans
  max_record_size: 20000

Note that if you push a record that is larger than your allowed limit, the push will be rejected by the API. This might result in incomplete data being uploaded.