Hooks

The plugin gives you access to hooks in its lifecycle. Those hooks can be used to add your own custom Ruby logic to have more control on the way records are being extracted and indexed.

Using hooks are a more advanced feature than using regular configuration options but they will also give you much more flexibility.

Usage

You’ll have to extend the Jekyll::Algolia::Hooks class to overwrite the method definition of the hooks. The best way to do so is to add a custom plugin to your Jekyll site.

Create a _plugins directory in your Jekyll source folder if you don’t have one already. Inside this folder, create an algolia_hooks.rb file.

The file should have the following structure:

module Jekyll
  module Algolia
    module Hooks
      # Add your hooks here
    end
  end
end

should_be_excluded?

This hook will give you more control on which file should be indexed or not. It will be called for every indexable file, with the source filepath as an argument. The file will be excluded if the hook returns true, and will be indexed if it returns false.

Note that the hook will not be called on files already excluded by extensions_to_index or files_to_exclude.

Example

module Jekyll
  module Algolia
    module Hooks
      def self.should_be_excluded?(filepath)
        # Do not index blog posts from 2015
        return true if filepath =~ %r{_posts/2015-}
        false
      end
    end
  end
end

before_indexing_each

This hook will be called on every single record before indexing them. It gives you a way to edit the record before pushing it. You can use this hook to add, edit or delete keys from the record. If the hook returns nil, the record will not be indexed.

The hook will receive three arguments: record, node and context. record is the hash of the record, ready to be pushed to Algolia. node is a Nokogiri representation of the HTML node the record was extracted from (as specified in nodes_to_index). context gives more information about the whole indexing process (check the following table for more details).

Example

module Jekyll
  module Algolia
    module Hooks
      def self.before_indexing_each(record, node, context)
        # Do not index deprecation warnings
        return nil if node.matches?('.deprecation-notice')
        # Add my name as an author to each record
        record[:author] = 'Myself'

        record
      end
    end
  end
end

before_indexing_all

This hook is similar to before_index_each, but instead of being called on every record, it is called only once, on the full list of record, right before pushing them.

It will be called with two arguments: records will be the full list of records to be pushed, and context will contain more information about the current indexing (check the following table for more details). The method expects a list of records to be returned.

You can use this hook to add, edit or delete complete records from the list, knowing the full context of what is going to be pushed.

Example

module Jekyll
  module Algolia
    module Hooks
      def self.before_indexing_all(records, context)
        # Add a tags array to each record
        records.each do |record|
          record[:tags] = []
          # Add 'blog' as a tag if it's a post
          record[:tags] << 'blog' if record[:type] == 'post'
          # Add js as a tag if it's about javascript
          record[:tags] << 'js' if record[:title].include?('js')
        end

        records
      end
    end
  end
end