New Features, New Docs and a New Foundation for Algolia’s Jekyll Plugin

We’re proud to announce the new release of our Jekyll plugin, jekyll-algolia. Jekyll is the best-known static website generator, converting raw markdown content to beautiful HTML pages. This plugin helps developers make their Jekyll sites searchable.

The main strength of static websites like those built with Jekyll is that you don’t need any database or backend server to run them. Just deploy a bunch of HTML, JS, CSS and images to a hosting provider and you’re good to go.

The downside was that the only way you had to find content was to struggle with Ctrl-F or head back to Google and refine your query. With jekyll-algolia, that’s a thing of the past. You can now search all your content directly from the static website itself, using the Algolia API.

Integration into the Jekyll ecosystem

We released the first version of the plugin in 2015, but a lot has happened since then. Jekyll got a major version update. Static websites are blooming everywhere. On our side we also indexed a large number of blogs and documentation websites. Everything we learned with these projects has now been distilled into this new version.

The plugin has been renamed from algoliasearch-jekyll to jekyll-algolia. This is one of many small changes to better follow the Jekyll conventions. We wanted jekyll-algolia to be a good citizen of the ecosystem, and that comes by speaking the Jekyll language.

But plugins do not live in a vacuum. You will surely use this plugin with other plugins, and we had to make sure they were all playing along nicely with each other. For example, we tested it alongside the popular jekyll-tagging plugin because they both manipulate the same objects (tags), and made sure our plugin was not interfering with the other and vice-versa. We also ensured it was compatible with the de-facto static hosting platforms: Netlify and GitHub pages.

Using the plugin

To use the plugin, you need to first add it to your Gemfile, under the :jekyll_plugins group (like every other Jekyll plugin). You then need to define your Algolia credentials in the _config.yml file, and run the bundle exec jekyll algolia command.

This will read all your content (pages, posts and custom collections) and push them to your Algolia index. Each record pushed that way will contain metadata about the original page (url, date, slug, tags, categories and any custom data you defined in your front-matter). All this data will then be available to your front-end, allowing rendering of rich search results.

The documentation explains in great detail how to integrate search into minima, the default Jekyll theme. Applying the same principles to your own theme is straightforward using our InstantSearch.js front-end library and its UI widgets.

Smarter indexing

The previous version had a naive approach to indexing. It used to delete all records in the Algolia index, then push everything again. It meant that even the smallest typo fix could delete and recreate thousands of records.

In the new version, the implementation was replaced with a smarter diff algorithm, reducing the number of operations used by orders of magnitude. Everyone, including people on our forever-free Community plan, should be able to use the plugin without worrying about hitting their monthly quota limit.

Better documentation

One of our mottos at Algolia is that documentation is part of the code. If it’s not documented, it’s not usable. We worked hard on making the documentation clear and exhaustive, not only explaining the various options but also why, when and how they should be used.

With the Getting Started guide, you’ll be up and running in a matter of minutes. Configuration options will let you customize which files should be indexed or excluded, as well as add your own custom Algolia settings. For those of you who have more advanced implementations, a hook system will let you write your own Ruby methods to alter the records in any way you’d want before pushing them. If you’re coming from the previous plugin version, we also have a migration guide to help you transition.

But documentation also comes in the form of error messages. We all know that even with the best documentation and code, errors will still happen. Maybe it will come from a misconfiguration on your side or a bug in the plugin. Either way, this should not stop you. This is why we made sure the error messages explain clearly what failed, why, and more importantly, how to solve it.

Some errors are pretty common (badly copy-pasted credentials or malformed HTML) and can be easily identified and avoided before they ever happen. The plugin does both pre-emptive checks and smart error handling to catch those common errors and display a message explaining what happened and the steps required to fix the issue.

Hopefully you’ll never have to see those error messages. But if you do, I think you’ll be glad they explain what went wrong, and how to fix it.

Start your search journey

Easy to use, yet powerful and extensible — that’s our new jekyll-algolia plugin. Whether you have a large (or a small) blog, a documentation website or a custom display of your own collections, give it a try. You’ll have a fast and relevant search across all your content and your users will thank you for that.

Questions? Feedback? We’d love to hear it: @pixelastic, @algolia.