Add instant search to your blog or documentation using our Jekyll plugin

Our goal at Algolia is to provide the fastest and the most relevant search experience everywhere around the world. In order to reach this scale, making the life of developers easier had to be one of our founding values. That’s why you can find clients for our API for many languages and frameworks.

Today we are proud to announce the new born in our family of integrations: the Jekyll plugin.

What is Jekyll

Jekyll is a static website generator. You write your content as markdown files, create a few layout templates and it generates the whole HTML website for you. You can then easily deploy it on any web server as it does not need any backend language or database to operate.

Jekyll itself is written in Ruby and is mostly used for blogs or documentation websites. GitHub actually provides a feature called GitHub pages that will automatically build and host a Jekyll website for you if you push it to a branch named gh-pages.

How to use the plugin

As a Jekyll website is only static HTML files, it also means that you cannot have any search capabilities. Or at least you couldn’t until now. With Algolia’s plugin, you now have access to the jekyll algolia push command. It will scan your Jekyll website and push every paragraph of text as a new record to an Algolia index so that you can search it from your website.

 

This fully tested plugin is available from rubygems and you can easily install it by adding just one line to your Gemfile. Once installed, you only need to edit your _config.yml to add your credentials. All information regarding installation and configuration are available in the readme.

How it works

The plugin looks at the HTML files generated by the jekyll build command and extracts every <p> paragraphs of text from them. It then adds a bit of metadata context to each of them and pushes them to your index.

By reading the final HTML pages that are generated, we do not rely on any specific markdown parser and you can even use any custom plugin you’d like.

For each extracted paragraph, we index its raw HTML value as well as its sanitized text. We also include the page url, the full hierarchy of headings (h1 to h6) where the paragraph was found and a few other informations (like a unique CSS selector for the <p> as well as its closest parent heading).

All this information will let you display nice search results and even point the user to the exact matched <p> in the results page. By default, results are grouped by urls, meaning that only the most relevant paragraph of each page will be returned, but this can be changed from the settings (as we’ll see in the next section).

Note that by itself, the plugin only imports your data to your index. For rendering the results, you can follow our tutorials or use our forked version of the popular Hyde theme.

Advanced usage

The default settings are perfectly tuned for a blog, but if you have a different kind of content, you might want to tweak the plugin configuration to fit your needs.

Fortunately, the plugin is highly configurable. First of all, if you want to index more than just <p> paragraphs (maybe you would like headings and block quotes as well), you can define your own CSS selectors.

Next, all the Algolia index settings are overridable directly from the _config.yml file, allowing you to group results based on another attribute, add snippeting to your fields or define your own custom ranking rules.

Finally, we also provide custom hooks that let you write custom code to add your own attributes to your records or add/remove records right before pushing them.

Our goal is to give you as much freedom as possible when using this plugin. We can’t wait to see what you’re going to build with it.