Add Algolia search provider (#1531)

* Support Lunr and Algolia search providers
* Document search providers and configuration
* Update CHANGELOG and history

close #1416

CHANGELOG.md

@@ -1,3 +1,9 @@
+## Unreleased
+
+### Enhancements
+
+* Add support for [Algolia](https://www.algolia.com/) search provider. [#1416](https://github.com/mmistakes/minimal-mistakes/issues/1416)
+
 ## [4.9.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.9.1)
 
 ### Enhancements

_config.yml

@@ -53,6 +53,12 @@ atom_feed:
   path                   : # blank (default) uses feed.xml
 search                   : # true, false (default)
 search_full_content      : # true, false (default)
+search_provider          : # lunr (default), algolia
+algolia:
+  application_id         : # YOUR_APPLICATION_ID
+  index_name             : # YOUR_INDEX_NAME
+  search_only_api_key    : # YOUR_SEARCH_ONLY_API_KEY
+  powered_by             : # true (default), false
 
 # SEO Related
 google_site_verification :

_includes/scripts.html

@@ -13,16 +13,13 @@
 {% endif %}
 
 {% if site.search == true or page.layout == "search" %}
-  {% assign lang = site.locale | slice: 0,2 | default: "en" %}
+  {%- assign search_provider = site.search_provider | default: "lunr" -%}
-  {% case lang %}
+  {%- case search_provider -%}
-  {% when "gr" %}
+    {%- when "lunr" -%}
-    {% assign lang = "gr" %}
+      {% include search/lunr-search-scripts.html %}
-  {% else %}
+    {%- when "algolia" -%}
-    {% assign lang = "en" %}
+      {% include search/algolia-search-scripts.html %}
-  {% endcase %}
+  {%- endcase -%}
-  <script src="{{ '/assets/js/lunr/lunr.min.js' | absolute_url }}"></script>
-  <script src="{{ '/assets/js/lunr/lunr-store.js' | absolute_url }}"></script>
-  <script src="{{ '/assets/js/lunr/lunr-' | append: lang | append: '.js' | absolute_url }}"></script>
 {% endif %}
 
 {% include analytics.html %}

_includes/search/algolia-search-scripts.html

@@ -0,0 +1,54 @@
+<!-- Including InstantSearch.js library and styling -->
+<script src="https://cdn.jsdelivr.net/npm/instantsearch.js@2.3.3/dist/instantsearch.min.js"></script>
+<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.3.3/dist/instantsearch.min.css">
+<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.3.3/dist/instantsearch-theme-algolia.min.css">
+
+<script>
+// Instanciating InstantSearch.js with Algolia credentials
+const search = instantsearch({
+  appId: '{{ site.algolia.application_id }}',
+  apiKey: '{{ site.algolia.search_only_api_key }}',
+  indexName: '{{ site.algolia.index_name }}',
+  searchParameters: {
+    restrictSearchableAttributes: [
+      'title',
+      'content'
+    ]
+  }
+});
+
+const hitTemplate = function(hit) {
+  const url = hit.url;
+  const title = hit._highlightResult.title.value;
+  const content = hit._highlightResult.html.value;
+
+  return `
+    <div class="list__item">
+      <article class="archive__item" itemscope itemtype="http://schema.org/CreativeWork">
+        <h2 class="archive__item-title" itemprop="headline"><a href="{{ site.baseurl }}${url}">${title}</a></h2>
+        <div class="archive__item-excerpt" itemprop="description">${content}</div>
+      </article>
+    </div>
+  `;
+}
+
+// Adding searchbar and results widgets
+search.addWidget(
+  instantsearch.widgets.searchBox({
+    container: '.search-searchbar',
+    {% unless site.algolia.powered_by == false %}poweredBy: true,{% endunless %}
+    placeholder: '{{ site.data.ui-text[site.locale].search_placeholder_text | default: "Enter your search term..." }}'
+  })
+);
+search.addWidget(
+  instantsearch.widgets.hits({
+    container: '.search-hits',
+    templates: {
+      item: hitTemplate
+    }
+  })
+);
+
+// Starting the search
+search.start();
+</script>

_includes/search/lunr-search-scripts.html

@@ -0,0 +1,10 @@
+{% assign lang = site.locale | slice: 0,2 | default: "en" %}
+{% case lang %}
+{% when "gr" %}
+  {% assign lang = "gr" %}
+{% else %}
+  {% assign lang = "en" %}
+{% endcase %}
+<script src="{{ '/assets/js/lunr/lunr.min.js' | absolute_url }}"></script>
+<script src="{{ '/assets/js/lunr/lunr-store.js' | absolute_url }}"></script>
+<script src="{{ '/assets/js/lunr/lunr-' | append: lang | append: '.js' | absolute_url }}"></script>

_includes/search/search_form.html

@@ -0,0 +1,11 @@
+<div class="search-content__inner-wrap">
+{%- assign search_provider = site.search_provider | default: "lunr" -%}
+{%- case search_provider -%}
+  {%- when "lunr" -%}
+    <input type="text" id="search" class="search-input" tabindex="-1" placeholder="{{ site.data.ui-text[site.locale].search_placeholder_text | default: 'Enter your search term...' }}" />
+    <div id="results" class="results"></div>
+  {%- when "algolia" -%}
+    <div class="search-searchbar"></div>
+    <div class="search-hits"></div>
+{%- endcase -%}
+</div>

_includes/search_form.html

@@ -1,4 +0,0 @@
-<div class="search-content__inner-wrap">
-  <input type="text" id="search" class="search-input" tabindex="-1" placeholder="{{ site.data.ui-text[site.locale].search_placeholder_text | default: 'Enter your search term...' }}" />
-  <div id="results" class="results"></div>
-</div>

_layouts/default.html

@@ -25,7 +25,7 @@
 
     {% if site.search == true %}
       <div class="search-content">
-        {% include search_form.html %}
+        {% include search/search_form.html %}
       </div>
     {% endif %}
 

_layouts/search.html

@@ -22,11 +22,14 @@ layout: default
 
     {{ content }}
 
-    <form>
+    {%- assign search_provider = site.search_provider | default: "lunr" -%}
-      <input type="input" id="search" class="search-input" placeholder="{{ site.data.ui-text[site.locale].search_placeholder_text | default: 'Enter your search term...' }}" />
+    {%- case search_provider -%}
-    </form>
+      {%- when "lunr" -%}
-
+        <input type="text" id="search" class="search-input" tabindex="-1" placeholder="{{ site.data.ui-text[site.locale].search_placeholder_text | default: 'Enter your search term...' }}" />
-    <div id="results"></div>
+        <div id="results" class="results"></div>
-
+      {%- when "algolia" -%}
+        <div class="search-searchbar"></div>
+        <div class="search-hits"></div>
+    {%- endcase -%}
   </div>
 </div>

_sass/minimal-mistakes/_search.scss

@@ -105,3 +105,21 @@
     margin-bottom: 0;
   }
 }
+
+/* Algolia search */
+
+.ais-search-box {
+  max-width: 100% !important;
+  margin-bottom: 2em;
+}
+
+.archive__item-title .ais-Highlight {
+  color: $link-color;
+  font-style: normal;
+  text-decoration: underline;
+}
+.archive__item-excerpt .ais-Highlight {
+  color: $link-color;
+  font-style: normal;
+  font-weight: bold;
+}

docs/_config.yml

@@ -57,6 +57,12 @@ atom_feed:
 
 search                   : true # true, false (default)
 search_full_content      : true # true, false (default)
+search_provider          : lunr # lunr (default), algolia
+algolia:
+  application_id         : # YOUR_APPLICATION_ID
+  index_name             : # YOUR_INDEX_NAME
+  search_only_api_key    : # YOUR_SEARCH_ONLY_API_KEY
+  powered_by             : # true (default), false
 
 # SEO Related
 google_site_verification : "UQj93ERU9zgECodaaXgVpkjrFn9UrDMEzVamacSoQ8Y" # Replace this with your ID, or delete

docs/_docs/05-configuration.md

@@ -2,7 +2,7 @@
 title: "Configuration"
 permalink: /docs/configuration/
 excerpt: "Settings for configuring and customizing the theme."
-last_modified_at: 2018-02-01T14:40:00-05:00
+last_modified_at: 2018-02-16T12:49:45-05:00
 toc: true
 ---
 
@@ -468,23 +468,68 @@ atom_feed:
 
 ### Site Search
 
-Enable basic site search powered by [Lunr](https://lunrjs.com/) by adding the following to `_config.yml`:
+To enable site-wide search add `search: true` to your `_config.yml`.
-
-```yaml
-search: true
-```
 
 ![masthead search example]({{ "/assets/images/masthead-search.gif" | absolute_url }})
 
-To index the full content of your documents set `search_full_content` to `true` in `_config.yml`:
+#### Lunr (default)
 
-```yaml
+The default search uses [**Lunr**](https://lunrjs.com/) to build a search index of all your documents. This method is 100% compatible with sites hosted on GitHub Pages.
-search_full_content: true
-```
 
-**Note:** Large amounts of posts will increase the size of the search index, impacting page load performance. Setting `search_full_content` to `false` (the default) restricts indexing to the first 50 words of body content.
+**Note:** Only the first 50 words of a post or page's body content is added to the Lunr search index. Setting `search_full_content` to `true` in your `_config.yml` will override this and could impact page load performance.
 {: .notice--warning}
 
+#### Algolia
+
+For faster and more relevant search ([see demo](https://mmistakes.github.io/jekyll-theme-basically-basic-algolia-search/)):
+
+1. Add the [`jekyll-algolia`](https://github.com/algolia/jekyll-algolia) gem to your `Gemfile`, in the `:jekyll_plugins` section.
+
+   ```ruby
+   group :jekyll_plugins do
+     gem "jekyll-feed"
+     gem "jekyll-seo-tag"
+     gem "jekyll-sitemap"
+     gem "jekyll-paginate"
+     gem "jekyll-algolia"
+   end
+   ```
+
+   Once this is done, download all dependencies by running `bundle install`.
+
+2. Switch search providers from `lunr` to `algolia` in your `_config.yml` file:
+
+   ```yaml
+   search_provider: algolia
+   ```
+
+3. Add the following Algolia credentials to your `_config.yml` file. *If you don't have an Algolia account, you can open a free [Community plan](https://www.algolia.com/users/sign_up/hacker). Once signed in, you can grab your credentials from [your dashboard](https://www.algolia.com/licensing).*
+
+   ```yaml
+   algolia:
+     application_id: # YOUR_APPLICATION_ID
+     index_name: # YOUR_INDEX_NAME
+     search_only_api_key: # YOUR_SEARCH_ONLY_API_KEY
+     powered_by: # true (default), false
+   ```
+
+4. Once your credentials are setup, you can run the indexing with the following command:
+
+   ```
+   ALGOLIA_API_KEY=your_admin_api_key bundle exec jekyll algolia
+   ```
+
+   For Windows users you will have to use `set` to assigned the `ALGOLIA_API_KEY` environment variable.
+
+   ```
+   set ALGOLIA_API_KEY=your_admin_api_key
+   bundle exec jekyll algolia
+   ```
+
+   Note that `ALGOLIA_API_KEY` should be set to your admin API key.
+
+To use the Algolia search with GitHub Pages hosted sites follow [this deployment guide](https://community.algolia.com/jekyll-algolia/github-pages.html). Or this guide for [deploying on Netlify](https://community.algolia.com/jekyll-algolia/netlify.html).
+
 ### SEO, Social Sharing, and Analytics Settings
 
 All optional, but a good idea to take the time setting up to improve SEO and links shared from the site.

docs/_docs/18-history.md

@@ -4,10 +4,16 @@ permalink: /docs/history/
 excerpt: "Change log of enhancements and bug fixes made to the theme."
 sidebar:
   nav: docs
-last_modified_at: 2018-02-05T14:38:43-05:00
+last_modified_at: 2018-02-16T12:45:12-05:00
 toc: true
 ---
 
+## Unreleased
+
+### Enhancements
+
+* Add support for [Algolia](https://www.algolia.com/) search provider. [#1416](https://github.com/mmistakes/minimal-mistakes/issues/1416)
+
 ## [4.9.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.9.1)
 
 ### Enhancements

test/Gemfile

@@ -3,4 +3,8 @@ source "https://rubygems.org"
 # use local theme gem for testing
 gem "minimal-mistakes-jekyll", path: "../"
 
+group :jekyll_plugins do
+  gem 'jekyll-algolia', '~> 1.0'
+end
+
 gem "wdm", "~> 0.1.0" if Gem.win_platform?

test/_config.yml

@@ -51,6 +51,12 @@ atom_feed:
   path                   : # blank (default) uses feed.xml
 search                   : true # true, false (default)
 search_full_content      : true # true, false (default)
+search_provider          : "algolia"
+algolia:
+  application_id         : "QB6HVGBSBA"
+  index_name             : "dev_minimal-mistakes"
+  search_only_api_key    : "9d5014e5bbc77372547bce778dfa5663"
+  powered_by             : true
 
 # SEO Related
 google_site_verification :

test/_pages/search.md

@@ -0,0 +1,5 @@
+---
+title: Search
+layout: search
+permalink: /search/
+---