Algolia Jekyll Plugin

Jekyll plugin to automatically index your Jekyll posts and pages into an Algolia index by simply running jekyll algolia push.

Usage

$ jekyll algolia push

This will push the content of your jekyll website to your Algolia index.

You can specify any option you would normally pass to jekyll build, like --config, --source, --destination, etc.

Installation

First, add the algoliasearch-jekyll gem to your Gemfile, in the :jekyll_plugins section. If you do not yet have a Gemfile, here is the minimum content to get your started.

source 'https://rubygems.org'

gem 'jekyll', '~> 2.5.3'

group :jekyll_plugins do
  gem 'algoliasearch-jekyll', '~> 0.4.3'
end

Once this is done, download all dependencies with bundle install.

Then, add algoliasearch-jekyll to your _config.yml file, under the gems section, like this:

gems:
  - algoliasearch-jekyll

If everything went well, you should be able to execute jekyll help and see the algolia subcommand listed.

Configuration

Add information about your Algolia configuration into the _config.yml file, under the algolia section, like this:

algolia:
  application_id: 'your_application_id'
  index_name:     'your_index_name'

You write api key will be read from the ALGOLIA_API_KEY environment variable. You can define it on the same line as your command, allowing you to type ALGOLIA_API_KEY='your_write_api_key' jekyll algolia push.

⚠ Other, unsecure, method ⚠

You can also store your write api key in a file named _algolia_api_key, in your source directory. If you do this we very, very, very strongly encourage you to make sure the file is not tracked in your versioning system.

Options

The plugin uses sensible defaults, but you may want to override some of its configuration. Here are the various options you can add to your _config.yml file, under the algolia section:

`excluded_files`

Defines which files should not be indexed for search.

algolia:
  excluded_files:
    - index.html
    - 2015-01-01-post.md

`record_css_selector`

Defines the css selector inside a page/post used to choose which parts to index. It is set to all paragraphs (<p>) by default.

If you would like to also index lists, you could set it like this:

algolia:
  record_css_selector: 'p,ul'

`settings`

Here you can pass any specific index settings to your Algolia index. All the settings supported by the API can be passed here.

Examples

If you want to activate distinct and some snippets for example, you would do:

algolia:
  settings:
    attributeForDistinct: 'hierarchy'
    distinct: true
    attributesToSnippet: ['text:20']

If you want to search in other fields than the default ones, you'll have to edit the attributesToIndex (default is %w(title h1 h2 h3 h4 h5 h6 unordered(text) unordered(tags))

algolia:
  settings:
    attributesToIndex:
      - title
      - h1
      - h2
      - h3
      - h4
      - h5
      - h6
      - unordered(text)
      - unordered(tags)
      - your_custom_attribute_1
      - your_custom_attribute_2
      - ...

Hooks

The AlgoliaSearchRecordExtractor contains two methods (custom_hook_each and custom_hook_all) that are here so you can overwrite them to add your custom logic. They currently simply return the argument they take as input.

class AlgoliaSearchRecordExtractor
  # Hook to modify a record after extracting
  # `node` refers to the Nokogiri HTML node of the element
  def custom_hook_each(item, node)
    item
  end

  # Hook to modify all records after extracting
  def custom_hook_all(items)
    items
  end
end

The AlgoliaSearchJekyllPush class also lets user define the custom_hook_excluded_file? method. This method is called on every file that the plugin thinks it should parse and index. If it returns true, the file is not indexed. You can add here your custom logic to exclude some files.

class AlgoliaSearchJekyllPush < Jekyll::Command
  class << self
    # Hook to exclude some files from indexing
    def custom_hook_excluded_file?(file)
      return true if filepath =~ %r{^/excluded_dir/}
      false
    end
  end
end

Command line

Here is the list of command line options you can pass to the jekyll algolia push command:

Flag	Description
`--config ./_config.yml`	You can here specify the config file to use. Default is `_config.yml`
`--future`	With this flag, the command will also index posts with a future date
`--limit_posts 10`	Limits the number of posts to parse and index
`--drafts`	Index drafts in the `_drafts` folder as well
`--dry-run` or `-n`	Do a dry run, do not actually push anything to your index
`--verbose`	Display more information about what is going to be indexed

Dependencies

The algoliasearch-jekyll plugin works for versions of Jekyll starting from 2.5, with a version of Ruby of at least 2.0. You also need Bundler to easily add the gem as a dependency to Jekyll.

Searching

This plugin will only index your data in your Algolia index. Adding search capabilities is quite easy. You can follow our tutorials or use our forked version of the popular Hyde theme.

GitHub Pages

GitHub does not allow custom plugins to be run on GitHub Pages. This means that you'll either have to run jekyll algolia push manually, or configure TravisCI to do it for you.

Travis CI is an hosted continuous integration service, and it's free for open-source projects. Properly configured, it can automatically reindex your data whenever you push to gh-pages.

For it to work, you'll have 3 steps to perform.

1. Create a `.travis.yml` file

Create a file named .travis.yml at the root of your project, with the following content:

language: ruby
cache: bundler
branches:
  only:
    - gh-pages
script: 
  - bundle exec jekyll algolia push
rvm:
 - 2.2

This file will be read by Travis and instruct it to fetch all dependencies defined in the Gemfile, then run jekyll algolia push. This will only be triggered when data is pushed to the gh-pages branch.

2. Update your `_config.yml` file to exclude `vendor`

Travis will download all you Gemfile dependencies into a directory named vendor. You have to tell Jekyll to ignore this directory, otherwise Jekyll will try to parse it (and fail).

Doing so is easy, just add the following line to your _config.yml file:

exclude: [vendor]

3. Configure Travis

In order for Travis to be able to push data to your index on your behalf, you have to give it your write API Key. This is achieved by defining an ALGOLIA_API_KEY environment variable in Travis settings.

You should also uncheck the "Build pull requests" option, otherwise any pull request targeting gh-pages will trigger the reindexing.

Done

Commit all the changes to the files, and then push to gh-pages. Travis will catch the event and trigger your indexing for you. You can follow the Travis job execution directly on their website.

unity/algoliasearch-jekyll