docs: add note about maintenance status (#153)

* Update getting-started.md

* Update README.md

* Apply suggestions from code review

Co-authored-by: Sarah Dayan <sarah.dayan@algolia.com>

Co-authored-by: Sarah Dayan <sarah.dayan@algolia.com>

.github/ISSUE_TEMPLATE.md

@@ -14,18 +14,29 @@
 
 ## I want to report a bug:
 
-**What is the current behavior?**
+### What is the current behavior?
+
+### What is your expected behavior?
+
+### Git repository to reproduce the issue:
+<!-- 
+  This will greatly help us reproduce the issue and fix it quickly.
+  If you don't have one or can't share it, screenshots or terminal output will
+  be very helpful.
+--> 
+
+### Ruby version used:
+<!-- `ruby -v` should give you this information -->
+
+### Jekyll version used:
+<!-- `bundle exec jekyll -v` should give you this one -->
 
-**What is your expected behavior?**
 
-**Steps to reproduce the issue:**
-<!-- If you have a repo we can clone to try, or a screenshot, that is even
-better! --> 
 
 ## I want to suggest a feature:
 
-**What is your use case for such a feature?**
+### What is your use case for such a feature?
 <!-- The more you can tell us about WHY you want to do this, the easier is will be for us to tell you HOW to do it. -->
 
-**What is your proposed API? Is this a new option? A new behavior?**
+### What is your proposed API? Is this a new option? A new behavior?
 

.gitignore

@@ -1,10 +1,14 @@
 Gemfile.lock
+.envrc
 pkg/
 coverage/
 docs-dev/
 gemfiles/*.lock
-spec/fixtures/*/_site
+spec/site/_site
+spec/integration/site/_site
 
+spec/site/.jekyll-cache/
+.jekyll-cache/
 
 .DS_Store
 .*.sw[a-z]

.travis.yml

@@ -3,9 +3,9 @@ cache: bundler
 before_script: bundle update
 script: bundle exec rake test
 rvm:
+ - 2.6.2
  - 2.4.2
  - 2.3.5
- - 2.3.0
 notifications:
   email:
     on_success: never

CONTRIBUTING.md

@@ -38,6 +38,16 @@ group :jekyll_plugins do
 end
 ```
 
+## Running integration tests
+
+Integration tests will do a full jekyll run, and push data to an Algolia index,
+checking that records and settings are correctly saved. It is the slowest
+possible kind of tests, but also the one closest to a real implementation.
+
+Running those tests requires a real Algolia plan. You need to define
+`ALGOLIA_APPLICATION_ID`, `ALGOLIA_API_KEY` and `ALGOLIA_INDEX_NAME` (we suggest
+using `direnv` for that), and then run `./scripts/test_integration`.
+
 ## Linting
 
 Run `rake lint` to check the style of all ruby files. Run `rake

Guardfile

@@ -1,9 +1,14 @@
-# Launch tests whenever a file in ./lib or ./spec changes
+# frozen_string_literal: true
+
+# Live-reload unit tests
 guard :rspec, cmd: 'bundle exec rspec --color --format progress' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$}) do |match|
     "spec/#{match[1]}_spec.rb"
   end
+  watch(%r{^lib/jekyll/algolia/overwrites/jekyll-algolia-site\.rb$}) do
+    'spec/jekyll-algolia_spec.rb'
+  end
   watch('spec/spec_helper.rb') { 'spec' }
 end
 

Guardfile_integration

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Live-reload integration tests
+guard :rspec, cmd: 'bundle exec rspec --color --format progress' do
+  watch(%r{^spec/integration/.+_spec\.rb$})
+  watch('spec/integration/spec_helper.rb') { 'spec/integration' }
+end
+
+notification :off

MAINTAINERS

@@ -0,0 +1,4 @@
+# Maintainers list to contact for any security issue
+# You can find all contributors in the GitHub interface or the git log
+
+Tim Carry (@pixelastic)

README.md

@@ -1,13 +1,16 @@
 # Jekyll Algolia Plugin
 
-[![Gem Version][1]](http://badge.fury.io/rb/jekyll-algolia) [![Build
-Status][2]](https://travis-ci.org/algolia/jekyll-algolia) [![Coverage
-Status][3]](https://coveralls.io/github/algolia/jekyll-algolia?branch=master)
-[![Code Climate][4]](https://codeclimate.com/github/algolia/jekyll-algolia)
-![Jekyll >= 3.6.0][5] ![Ruby >= 2.3.0][6]
+[![gem version][1]][16]
+![ruby][2]
+![jekyll][3]
+[![build master][4]][17]
+[![build develop][6]][17]
+[![coverage master][5]][18]
 
 Add fast and relevant search to your Jekyll site.
 
+> While this plugin was created by Algolia, it is not an officially supported API client. It is possible that future major versions of Jekyll break compatibility, or require changes.
+
 ## Usage
 
 ```shell
@@ -19,7 +22,7 @@ This will push the content of your Jekyll website to your Algolia index.
 ## Documentation
 
 Full documentation can be found on
-[https://community.algolia.com/jekyll-algolia/](https://community.algolia.com/jekyll-algolia/getting-started.html)
+[https://community.algolia.com/jekyll-algolia/][20]
 
 ## Installation
 
@@ -40,48 +43,89 @@ Once this is done, download all dependencies with `bundle install`.
 
 ## Basic configuration
 
-You need to provide certain Algolia credentials for this plugin to *index* your
+You need to provide certain Algolia credentials for this plugin to _index_ your
 site.
 
-*If you don't yet have an Algolia account, you can open a free [Community plan
-here][7]. Once signed in, you can get your credentials from
-[your dashboard][8].*
+_If you don't yet have an Algolia account, we suggest that you open a free
+[Community plan here][8]. You can find more information about the Algolia plans
+[in our FAQ][10]._
 
-Once you have your credentials, you should define your `application_id` and
-`index_name` inside your `_config.yml` file like this:
+Once signed in, you should get your application ID from [your dashboard][9] and
+define it inside your `_config.yml` file like this:
 
 ```yaml
 # _config.yml
 
 algolia:
   application_id: 'your_application_id'
-  index_name:     'your_index_name'
 ```
 
 ## Run it
 
-Once your credentials are setup, you can run the indexing by running the
+Once your application ID is setup, you can run the indexing by running the
 following command:
 
 ```shell
-ALGOLIA_API_KEY='{your_admin_api_key}' bundle exec jekyll algolia
+ALGOLIA_API_KEY='your_admin_api_key' bundle exec jekyll algolia
 ```
 
 Note that `ALGOLIA_API_KEY` should be set to your admin API key.
 
+## More about the Community plan
+
+The Algolia [Community plan][11] lets you host up to 10k records and perform up
+to 100k add/edit/delete operations per month (search operations are free). The
+plan is entirely free, with no time limit.
+
+What we ask in exchange is that you display a "Search by Algolia" logo next to
+your search results. Our [InstantSearch libraries][12] have a simple boolean
+option to toggle that on an off. If you want more flexibility, you can find
+all versions of our logo [here][13].
+
+If you need more information about the other Algolia plans, you can [check our
+FAQ][10].
+
 # Thanks
 
-Thanks to [Anatoliy Yastreb][9] for a [great tutorial][10] on creating Jekyll
+Thanks to [Anatoliy Yastreb][14] for a [great tutorial][15] on creating Jekyll
 plugins.
 
-
 [1]: https://badge.fury.io/rb/jekyll-algolia.svg
-[2]: https://travis-ci.org/algolia/jekyll-algolia.svg?branch=master
-[3]: https://coveralls.io/repos/algolia/jekyll-algolia/badge.svg?branch=master&service=github
-[4]: https://codeclimate.com/github/algolia/jekyll-algolia/badges/gpa.svg
-[5]: https://img.shields.io/badge/jekyll-%3E%3D%203.6.0-green.svg
-[6]: https://img.shields.io/badge/ruby-%3E%3D%202.3.0-green.svg
-[7]: https://www.algolia.com/users/sign_up/hacker
-[8]: https://www.algolia.com/licensing
-[9]: https://github.com/ayastreb/
-[10]: https://ayastreb.me/writing-a-jekyll-plugin/
+
+[2]: https://img.shields.io/badge/ruby-%3E%3D%202.3.0-green.svg
+
+[3]: https://img.shields.io/badge/jekyll-%3E%3D%203.6.0-green.svg
+
+[4]: https://img.shields.io/badge/dynamic/json.svg?label=build%3Amaster&query=value&uri=https%3A%2F%2Fimg.shields.io%2Ftravis%2Falgolia%2Fjekyll-algolia.json%3Fbranch%3Dmaster
+
+[5]: https://coveralls.io/repos/github/algolia/jekyll-algolia/badge.svg?branch=master
+
+[6]: https://img.shields.io/badge/dynamic/json.svg?label=build%3Adevelop&query=value&uri=https%3A%2F%2Fimg.shields.io%2Ftravis%2Falgolia%2Fjekyll-algolia.json%3Fbranch%3Ddevelop
+
+[7]: https://coveralls.io/repos/github/algolia/jekyll-algolia/badge.svg?branch=develop
+
+[8]: #more-about-the-community-plan
+
+[9]: https://www.algolia.com/api-keys
+
+[10]: https://community.algolia.com/jekyll-algolia/faq.html#how-many-records-will-the-plugin-need
+
+[11]: https://www.algolia.com/users/sign_up/hacker
+
+[12]: https://community.algolia.com/instantsearch.js/
+
+[13]: https://www.algolia.com/press/?section=brand-guidelines
+
+[14]: https://github.com/ayastreb/
+
+[15]: https://ayastreb.me/writing-a-jekyll-plugin/
+
+[16]: https://rubygems.org/gems/jekyll-algolia
+
+[17]: https://travis-ci.org/algolia/jekyll-algolia
+
+[18]: https://coveralls.io/github/algolia/jekyll-algolia?branch=master
+
+[19]: https://coveralls.io/github/algolia/jekyll-algolia?branch=develop
+
+[20]: https://community.algolia.com/jekyll-algolia/getting-started.html

Rakefile

@@ -9,10 +9,14 @@ rescue Bundler::BundlerError => e
   warn 'Run `bundle install` to install missing gems'
   exit e.status_code
 end
+require 'algoliasearch'
 require 'rake'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
 # LINT
-require 'rubocop/rake_task'
+desc 'Check files for linting issues'
 RuboCop::RakeTask.new(:lint) do |task|
   task.patterns = [
     'lib/**/*.rb',
@@ -25,9 +29,7 @@ RuboCop::RakeTask.new(:lint) do |task|
 end
 
 # TEST
-require 'rspec/core'
-require 'rspec/core/rake_task'
-desc 'Run tests (with simple progress)'
+desc 'Run unit tests'
 RSpec::Core::RakeTask.new(:test) do |task|
   task.rspec_opts = '--color --format progress'
   task.pattern = [
@@ -35,35 +37,76 @@ RSpec::Core::RakeTask.new(:test) do |task|
     'spec/jekyll/**/*.rb'
   ]
 end
-desc 'Run tests (with full details)'
-RSpec::Core::RakeTask.new(:test_details) do |task|
-  task.rspec_opts = '--color --format documentation'
-  task.pattern = [
-    'spec/*.rb',
-    'spec/jekyll/**/*.rb'
-  ]
-end
-desc 'Run tests in all Ruby versions (with full details)'
-task :test_all_ruby_versions do
-  puts 'Please, run ./scripts/test_all_ruby_versions manually'
-end
+namespace 'test' do
+  desc 'Run tests in all Ruby versions'
+  task :all_ruby_versions do
+    puts 'Please, run ./scripts/test_all_ruby_versions manually'
+  end
 
-# COVERAGE
-desc 'Generate locally browsable coverage files'
-task :coverage do
-  ENV['COVERAGE'] = 'true'
-  Rake::Task['test'].execute
-end
+  # Generate locally browsable coverage files
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task['test'].execute
+  end
 
-# WATCH
-desc 'Watch for changes in files and reload tests'
-task :watch do
-  # We specifically watch for ./lib and ./spec and not the whole dir because:
-  # 1. It's the only directories we are interested in
-  # 2. Listening to the whole parent dir might throw Guard errors if we have
-  #    symlink
-  sh 'bundle exec guard --clear --watchdir lib spec'
+  desc 'Live-reload unit tests'
+  task :watch do
+    # We specifically watch for ./lib and ./spec and not the whole dir because:
+    # 1. It's the only directories we are interested in
+    # 2. Listening to the whole parent dir might throw Guard errors if we have
+    #    symlink
+    sh 'bundle exec guard --clear --watchdir lib spec'
+  end
+
+  # Integration tests need to run `bundle exec jekyll build/algolia`. Using
+  # bundle from inside a Rakefile does not seem to work, so the scripts have to
+  # be run manually. Each script run the needed commands to prepare the test
+  # site, then actually run the _run and _watch_run tasks below.
+  desc 'Run integration tests'
+  task :integration do
+    puts 'Please, run ./scripts/test_integration manually'
+  end
+  namespace 'integration' do
+    desc 'Live-reload integration tests'
+    task :watch do
+      puts 'Please, run ./scripts/test_integration_watch manually'
+    end
+    # Delete the test indices
+    task :_delete_indices do
+      Algolia.init(
+        application_id: ENV['ALGOLIA_APPLICATION_ID'],
+        api_key: ENV['ALGOLIA_API_KEY']
+      )
+      Algolia::Index.new(ENV['ALGOLIA_INDEX_NAME']).delete_index!
+      Algolia::Index
+        .new("#{ENV['ALGOLIA_INDEX_NAME']}_object_ids").delete_index!
+    end
+    # Run only the integration tests
+    desc ''
+    RSpec::Core::RakeTask.new(:_run) do |task|
+      task.rspec_opts = '--color --format progress'
+      task.pattern = [
+        # Check that the default build has the expected results
+        'spec/integration/main_spec.rb',
+        # Check various config and its impact on the settings
+        'spec/integration/settings_spec.rb',
+        # Check that object ids are stored in dedicated index
+        'spec/integration/object_ids_spec.rb'
+      ]
+    end
+    # Live-reloading integration tests
+    # It will reload the tests whenever they are changed. It will not
+    # live-rebuild everything, you still have to run rake
+    # ./scripts/test_integration_prepare for that
+    task :_watch_run do
+      sh 'bundle exec guard '\
+         '--clear '\
+         '--watchdir lib spec/integration '\
+         '--guardfile Guardfile_integration'
+    end
+  end
 end
+task watch: 'test:watch'
 
 # GEM RELEASE
 desc 'Release a new version of the gem'
@@ -75,14 +118,14 @@ task release: %i[lint test] do
   Rake::Task['release:update_master_from_develop'].invoke
 end
 namespace 'release' do
-  desc 'Getting up to date from master'
+  # Getting up to date from master
   task :update_develop_from_master do
     sh 'git checkout master --quiet'
     sh 'git pull --rebase origin master --quiet'
     sh 'git checkout develop --quiet'
     sh 'git rebase master --quiet'
   end
-  desc 'Update current version'
+  # Update current version
   task :update_version do
     version_file_path = 'lib/jekyll/algolia/version.rb'
     require_relative version_file_path
@@ -100,15 +143,24 @@ namespace 'release' do
 
     # Commit it in git
     sh "git commit -a -m 'release #{new_version}'"
+
     # Create the git tag
-    sh "git tag -am 'tag v#{new_version}' #{new_version}"
+    last_tag = `git describe --tags --abbrev=0`.strip
+    changelog = `git log #{last_tag}..HEAD --format=%B`.gsub("\n\n", "\n")
+    tag_name = new_version
+    sh 'git tag '\
+      "-a #{tag_name} "\
+      "-m \"#{changelog}\""\
+      ' 2>/dev/null'
+
+    sh "git tag #{tag_name} #{tag_name} -f -a"
   end
-  desc 'Build the gem'
+  # Build the gem
   task :build do
     sh 'bundle install'
     sh 'gem build jekyll-algolia.gemspec'
   end
-  desc 'Push the gem to rubygems'
+  # Push the gem to rubygems
   task :push do
     # This will throw a warning because we're redefining a constant. That's ok.
     load 'lib/jekyll/algolia/version.rb'
@@ -117,7 +169,7 @@ namespace 'release' do
     sh "rm jekyll-algolia-#{current_version}.gem"
     sh "git push origin #{current_version}"
   end
-  desc 'Update master'
+  # Update master
   task :update_master_from_develop do
     sh 'git checkout master --quiet'
     sh 'git rebase develop --quiet'
@@ -144,7 +196,7 @@ namespace 'docs' do
 
     Rake::Task['docs:build'].invoke
     sh 'git add ./docs'
-    sh "git commit -m 'Updating documentation website'"
+    sh "git commit -m 'Updating documentation website' || true"
 
     sh 'git checkout master --quiet'
     sh 'git rebase develop --quiet'

docs-src/config.js

@@ -27,6 +27,7 @@ const sidebarMenu = [
     items: [
       { title: 'Getting Started', url: 'getting-started.html' },
       { title: 'How it works', url: 'how-it-works.html' },
+      { title: 'FAQ', url: 'faq.html' },
     ],
   },
   {
@@ -42,6 +43,7 @@ const sidebarMenu = [
     items: [
       { title: 'Deploying on Netlify', url: 'netlify.html' },
       { title: 'Deploying on Github Pages', url: 'github-pages.html' },
+      { title: 'Themes', url: 'themes.html' },
       { title: 'Migration guide', url: 'migration-guide.html' },
     ],
   },

docs-src/package.json

@@ -35,7 +35,7 @@
     "hasha": "3.0.0",
     "http-server": "0.10.0",
     "jstransformer-markdown-it": "2.0.0",
-    "lodash": "4.17.4",
+    "lodash": "4.17.5",
     "markdown-it": "8.4.0",
     "markdown-it-anchor": "4.0.0",
     "metalsmith": "2.3.0",
@@ -45,7 +45,7 @@
     "metalsmith-sass": "1.4.0",
     "ms-webpack": "2.0.0",
     "node-sass": "4.7.2",
-    "nodemon": "1.12.5",
+    "nodemon": "1.18.7",
     "postcss": "6.0.14",
     "postcss-loader": "2.0.9",
     "postcss-scss": "1.0.2",
@@ -66,8 +66,8 @@
     "webpack-hot-middleware": "2.21.0"
   },
   "engines": {
-    "node": "^9.2.0",
-    "yarn": "^1.3.2"
+    "node": ">=9.2.0",
+    "yarn": ">=1.3.2"
   },
   "renovate": {
     "extends": [

docs-src/src/blog.md

@@ -15,6 +15,7 @@ already have pushed all your data, following our [getting started][2] guide.
 
 [![Search in the minima theme][3]](https://community.algolia.com/jekyll-algolia-example/)
 
+
 In this tutorial we'll add a search on the front page that will let you search
 into all your posts (both titles and content), in a fast and relevant manner.
 
@@ -73,11 +74,17 @@ exist yet.
 In that file, we'll add the following content. It's a lot of code in one go, but
 don't worry, we'll explain it all right after.
 
+_Note that for the sake of readability we will be using JavaScript features
+that might not be available in all browsers (namely [const][5], [template
+literals][6] and [arrow functions][7]). If you need compatibility with browsers
+that do not ship those features, we recommend you use [Babel][8] to
+automatically transpile your code._
+
 ```html
 <!-- 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 src="https://cdn.jsdelivr.net/npm/instantsearch.js@2.6.0/dist/instantsearch.min.js"></script>
+<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.6.0/dist/instantsearch.min.css">
+<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.6.0/dist/instantsearch-theme-algolia.min.css">
 
 <script>
 // Instanciating InstantSearch.js with Algolia credentials
@@ -91,7 +98,8 @@ const search = instantsearch({
 search.addWidget(
   instantsearch.widgets.searchBox({
     container: '#search-searchbar',
-    placeholder: 'Search into posts...'
+    placeholder: 'Search into posts...',
+    poweredBy: true // This is required if you're on the free Community plan
   })
 );
 search.addWidget(
@@ -107,9 +115,9 @@ search.start();
 
 ### Including the InstantSearch.js library
 
-The first lines will include the [InstantSearch.js][5] library as well as
+The first lines will include the [InstantSearch.js][9] library as well as
 minimal styling, directly from the jsDeliver CDN. Those files are also available
-through [Yarn][6]/[NPM][7] if you need them locally.
+through [Yarn][10]/[NPM][11] if you need them locally.
 
 ### Instanciating the library
 
@@ -121,7 +129,7 @@ Both `application_id` and `index_name` should already be in your `_config.yml`
 file. The `search_only_api_key` should be new, though.
 
 Add a new entry in your `_config.yml` file, under the `algolia` namespace with
-the value of your Search API Key (you can find it in your [Dashboard][8]):
+the value of your Search API Key (you can find it in your [Dashboard][12]):
 
 ```yml
 # _config.yml
@@ -151,7 +159,7 @@ InstantSearch loads, it will replace the list with its own results.
 This is what it should look like at this stage. We have a search bar, but
 results are displayed in a raw JSON format. Let's work on styling this.
 
-![Minimal InstantSearch.js styling][9]
+![Minimal InstantSearch.js styling][13]
 
 ## Templating
 
@@ -181,7 +189,7 @@ search.addWidget(
 );
 ```
 
-![InstantSearch.js styling][10]
+![InstantSearch.js styling][14]
 
 This looks much better already. By using a template, we managed to make the
 result look close to what the initial display was. In the next section, we'll
@@ -196,7 +204,7 @@ default we display it exactly as it was saved in the Algolia index: as a UNIX
 timestamp.
 
 Because our template is a JavaScript function, we can reformat data before
-rendering it. Here we will use the [moment.js][11] library to format our date.
+rendering it. Here we will use the [moment.js][15] library to format our date.
 
 Using `moment.unix(hit.date).format('MMM D, YYYY');` we'll transform
 `1513764761` into `Dec 20, 2017`.
@@ -226,42 +234,38 @@ All HTML nodes added by InstantSearch.js come with a custom `.ais-*` class added
 to them. This makes altering the styling of the elements to match your overall
 theme easy to achieve.
 
-### Edge-case handling
+### Headings
 
 With the current configuration, we will sometimes end up with results that look
 irrelevant: nothing is highlighted neither in the title or the content.
 
-This is because by default the plugin is searching into different fields
-(including `tags`, `categories` and the parent heading hierarchy of each
-paragraph). Because we chose to only display the title and content, it means that
-when a match in another attribute is occurring, we have no way to visually signal
-it to the user. It makes the result look irrelevant, while it is actually
-relevant (but we're not explaining why).
+This is because by default the plugin is searching not only in the content and
+the title, but also in the headings (`<h1>` to `<h6>` of the page). Because we
+currently only display the title and content, it make some perfectly relevant
+result look odd, because nothing is highlighted.
 
-One way to work around this issue is to manually tell the API in which field it
-should search, by using the [restrictSearchableAttributes][12] option.
+To fix that, we'll add the highlighted headings to the display when they are
+matching. We'll create a new variable called `breadcrumbs`, filled with the
+highlighted headings, and add it to our template only when not empty.
+
+We also update the url to include the `#` anchor that will point the link
+directly to the closest matching heading.
 
 ### Final code
 
 Here is the complete new version of the `_includes/algolia.html` file.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/instantsearch.js@2.3.3/dist/instantsearch.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/instantsearch.js@2.6.0/dist/instantsearch.min.js"></script>
 <script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.20.1/moment.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">
+<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.6.0/dist/instantsearch.min.css">
+<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.6.0/dist/instantsearch-theme-algolia.min.css">
 
 <script>
 const search = instantsearch({
   appId: '{{ site.algolia.application_id }}',
   apiKey: '{{ site.algolia.search_only_api_key }}',
-  indexName: '{{ site.algolia.index_name }}',
-  searchParameters: {
-    restrictSearchableAttributes: [
-      'title',
-      'content'
-    ]
-  }
+  indexName: '{{ site.algolia.index_name }}'
 });
 
 const hitTemplate = function(hit) {
@@ -269,14 +273,25 @@ const hitTemplate = function(hit) {
   if (hit.date) {
     date = moment.unix(hit.date).format('MMM D, YYYY');
   }
-  const url = hit.url;
+
+  let url = `{{ site.baseurl }}${hit.url}#${hit.anchor}`;
+
   const title = hit._highlightResult.title.value;
+
+  let breadcrumbs = '';
+  if (hit._highlightResult.headings) {
+    breadcrumbs = hit._highlightResult.headings.map(match => {
+      return `<span class="post-breadcrumb">${match.value}</span>`
+    }).join(' > ')
+  }
+
   const content = hit._highlightResult.html.value;
 
   return `
     <div class="post-item">
       <span class="post-meta">${date}</span>
       <h2><a class="post-link" href="${url}">${title}</a></h2>
+      {{#breadcrumbs}}<a href="${url}" class="post-breadcrumbs">${breadcrumbs}</a>{{/breadcrumbs}}
       <div class="post-snippet">${content}</div>
     </div>
   `;
@@ -286,7 +301,8 @@ const hitTemplate = function(hit) {
 search.addWidget(
   instantsearch.widgets.searchBox({
     container: '#search-searchbar',
-    placeholder: 'Search into posts...'
+    placeholder: 'Search into posts...',
+    poweredBy: true // This is required if you're on the free Community plan
   })
 );
 
@@ -315,31 +331,49 @@ search.start();
   font-style: normal;
   text-decoration: underline;
 }
+.post-breadcrumbs {
+  color: #424242;
+  display: block;
+}
+.post-breadcrumb {
+  font-size: 18px;
+  color: #424242;
+}
+.post-breadcrumb .ais-Highlight {
+  font-weight: bold;
+  font-style: normal;
+}
 .post-snippet .ais-Highlight {
   color: #2a7ae2;
   font-style: normal;
   font-weight: bold;
 }
+.post-snippet img {
+  display: none;
+}
 </style>
 ```
 
 ## Final result
 
-You can check the [final result live here][13], and have a look at all the code from
-the [GitHub repository][14].
+You can check the [final result live here][16], and have a look at all the code
+from the [GitHub repository][17].
 
 
 [1]: https://github.com/jekyll/minima
 [2]: ./getting-started.html
 [3]: ./assets/images/minima-search.gif
 [4]: https://raw.githubusercontent.com/jekyll/minima/master/_layouts/home.html
-[5]: https://community.algolia.com/instantsearch.js/
-[6]: https://yarnpkg.com/en/package/instantsearch.js
-[7]: https://www.npmjs.com/package/instantsearch.js
-[8]: https://www.algolia.com/api-keys
-[9]: ./assets/images/instantsearch-nostyling.png
-[10]: ./assets/images/instantsearch-styling.png
-[11]: https://momentjs.com/docs/
-[12]: https://www.algolia.com/doc/api-reference/api-parameters/restrictSearchableAttributes/
-[13]: https://community.algolia.com/jekyll-algolia-example/
-[14]: https://github.com/algolia/jekyll-algolia-example
+[5]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const
+[6]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
+[7]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
+[8]: https://babeljs.io/
+[9]: https://community.algolia.com/instantsearch.js/
+[10]: https://yarnpkg.com/en/package/instantsearch.js
+[11]: https://www.npmjs.com/package/instantsearch.js
+[12]: https://www.algolia.com/api-keys
+[13]: ./assets/images/instantsearch-nostyling.png
+[14]: ./assets/images/instantsearch-styling.png
+[15]: https://momentjs.com/docs/
+[16]: https://community.algolia.com/jekyll-algolia-example/
+[17]: https://github.com/algolia/jekyll-algolia-example

docs-src/src/commandline.md

@@ -17,11 +17,9 @@ Here is the list of command line options you can pass to the `jekyll algolia` co
 | 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            |
+| `--force-settings`       | Force update of the index settings                                    |
 
 
 ## Environment variables
@@ -32,10 +30,9 @@ to overwrite those values.
 
 key                    | value
 ---------------------- | ----------------------
-ALGOLIA_APPLICATION_ID | `your_application_id`
-ALGOLIA_INDEX_NAME     | `your_index_name`
-ALGOLIA_API_KEY        | `your_api_key`
-
+ALGOLIA_APPLICATION_ID | Your Application ID, available in [your dashboard](https://www.algolia.com/api-keys).
+ALGOLIA_INDEX_NAME     | Your Index name, any string will work
+ALGOLIA_API_KEY        | Your Admin API Key, available in [your dashboard](https://www.algolia.com/api-keys).
 
 ## `_algolia_api_key` file
 

docs-src/src/faq.md

@@ -0,0 +1,100 @@
+---
+title: Frequently Asked Questions
+layout: content-with-menu.pug
+---
+
+# Frequently Asked Questions
+
+## How many records will the plugin need?
+
+The plugin will not create an exact mapping of `1 page = 1 record`. Instead, it
+will split all pages into smaller chunks, and each chunk will be saved as a
+record. Splitting into small chunks is key to offer the best relevance of
+results.
+
+The default chunking mechanism is to create one chunk per paragraph of content.
+So, for a blog post that is made up of 10 paragraphs of text, it will create 10
+records.
+
+Estimating the number of records you will need can be tricky as it depends on
+both the number of pages you have, and on the average length of them. Some
+configuration options (such as [nodes_to_index][1]) can also influence the final
+result.
+
+The following table should give you a ballpark estimate of what to expect. All
+calculations were done with an average of **15 paragraphs per page**, on a
+timeline of **one year**.
+
+| update frequency            | # of new pages | # of records | Algolia plan   |
+| --------------------------- | -------------- | ------------ | -------------- |
+| ~1 new page per week        | ~50            | ~750         | [Community][2] |
+| ~1 new page per day         | ~400           | ~6.000       | [Community][3] |
+| ~2 new pages per day        | ~700           | ~10.500      | [Essential][4] |
+| ~1 new page per hour        | ~8800          | ~132.000     | [Essential][5] |
+| ~1 new page every 5 minutes | ~105.000       | ~1.575.000   | [Plus][6]      |
+| More?                       | More?          | More?        | [Business][7]  |
+
+## One of my records is too big. What can I do?
+
+If you get an error about one of your records being too big, be sure to update
+the plugin to the latest version. We keep improving the plugin with ways of
+making the records smaller.
+
+If you're still having an error, you should check the `.json` log file that has
+been created in your source directory. This will contain the content of the
+record that has been rejected. It might give you hints about what went wrong.
+
+A common cause for this issue often lies in the page HTML. Maybe the HTML is
+malformed (a tag is not closed for example), or instead of several small
+paragraphs there is only one large paragraph. This can cause the parser to take
+the whole page content (instead of small chunks of it) to create the records.
+
+If you don't find where the issue is coming from, feel free to open a [GitHub
+issue][8] with a copy of the log file and we'll be happy to help you.
+
+## How can I tweak the relevance ranking?
+
+The plugin default configuration will rank results based on their textual
+relevance. You can adapt the ranking to fit your needs by using a
+combination of front-matter and Algolia index settings.
+
+For example, if you know some of your blog posts are popular, you might want to
+give them a boost in their ranking. To do so, add a `popular: true` entry to the
+front-matter of such posts. Any custom key added to a front-matter is
+automatically pushed to their corresponding records.
+
+Then, you would have to edit your `_config.yml` file to pass a custom
+`settings.customRanking` value. The `customRanking` is one of the way ranking
+can be configured in an Algolia index and follows a tie-breaking algorithm. You
+can find more information about the way it works either in the [official
+documentation][9] or in [this video][10].
+
+The default `customRanking` used by the plugin is [defined here][11] and use the
+date, weight of the header and position in the page by default. You can
+overwrite it to also take the `popular` flag into account like:
+
+```yml
+algolia:
+  settings:
+    customRanking:
+      - desc(popular)
+      - desc(date)
+      - desc(custom_ranking.heading)
+      - asc(custom_ranking.position)
+```
+
+This will rank popular posts matching your keywords before other posts. You can
+use either boolean or numeric values for the `customRanking`.
+
+[1]: options.html#nodes-to-index
+[2]: https://www.algolia.com/pricing
+[3]: https://www.algolia.com/pricing
+[4]: https://www.algolia.com/pricing
+[5]: https://www.algolia.com/pricing
+[6]: https://www.algolia.com/pricing
+[7]: https://www.algolia.com/pricing
+[8]: https://github.com/algolia/jekyll-algolia/issues
+[9]: https://community.algolia.com/jekyll-algolia/options.html#settings
+[10]: https://www.youtube.com/watch?v=H6crAohtUBw
+[11]:
+  https://github.com/algolia/jekyll-algolia/blob/develop/lib/jekyll/algolia/configurator.rb#L27-L30

docs-src/src/getting-started.md

@@ -10,6 +10,8 @@ layout: content-with-menu.pug
 `jekyll-algolia` is a Jekyll plugin that lets you push all your content in an
 Algolia index.
 
+> While this plugin was created by Algolia, it is not an officially supported API client. It is possible that future major versions of Jekyll break compatibility, or require changes.
+
 ## Requirements
 
 You'll need:
@@ -55,8 +57,8 @@ Once you have your credentials, you should define your `application_id` and
 # _config.yml
 
 algolia:
-  application_id: 'your_application_id'
-  index_name:     'your_index_name'
+  application_id: your_application_id
+  index_name:     jekyll # You can replace that with whatever name you want
 ```
 
 ## Usage
@@ -65,7 +67,7 @@ Once your credentials are setup, you can run the indexing by running the
 following command:
 
 ```shell
-ALGOLIA_API_KEY='{your_admin_api_key}' bundle exec jekyll algolia
+ALGOLIA_API_KEY='your_admin_api_key' bundle exec jekyll algolia
 ```
 
 Note that `ALGOLIA_API_KEY` should be set to your admin API key. This key has
@@ -85,25 +87,26 @@ The plugin only takes care of extracting your data and pushing it to an Algolia
 index. Building the front-end that will allow your users to search into that
 data is not part of the plugin.
 
-As it would depend too much on the theming you applied to Jekyll, we could not
+As it would depend too much on the theme you applied to Jekyll, we could not
 create a one-size-fits-all solution. Instead, the best solution is to use our
-[InstantSearch.js][9] library (also available for [Vue.js][10] and [React][11]).
-It's an easy-to-use set of UI widgets you can use to build your own search in
-a matter of minutes.
+[InstantSearch.js][9] library (also available for [Vue.js][10], [React][11] and
+[Angular][12]). It's an easy-to-use set of UI widgets you can use to build your
+own search in a matter of minutes.
 
-You can follow [this tutorial][12] to see how to add search on the default blog
+You can follow [this tutorial][13] to see how to add search on the default blog
 theme.
 
-
 [1]: https://jekyllrb.com/
 [2]: https://www.ruby-lang.org/en/
 [3]: http://bundler.io/
 [4]: https://www.algolia.com/users/sign_up/hacker
-[5]: https://www.algolia.com/licensing
+[5]: https://www.algolia.com/api-keys
 [6]: ./assets/images/getting-started.gif
 [7]: ./commandline.html#algolia-api-key-file
 [8]: https://github.com/rvm/rubygems-bundler
 [9]: https://community.algolia.com/instantsearch.js/
 [10]: https://community.algolia.com/vue-instantsearch/
 [11]: https://community.algolia.com/react-instantsearch/
-[12]: ./blog.html
+[12]: https://community.algolia.com/angular-instantsearch/
+[13]: ./blog.html
+[14]: https://www.algolia.com/press#resources

docs-src/src/github-pages.md

@@ -30,11 +30,11 @@ your GitHub Pages is done.
 Here are the steps to follow to setup your Travis account for your project:
 
 - Go to [travis-ci.org][5] and open an account
-- Click on your avatar and "Accounts"
+- Click on your avatar and "Profile"
 - Find your GitHub repository in the list and activate it
 
 _You should also uncheck the "Build pull request updates" in the options.
-This will avoid re-indexing your date every time you receive a pull request._
+This will avoid re-indexing your data every time you receive a pull request._
 
 ![Travis configuration](./assets/images/travis-config.png)
 
@@ -50,6 +50,8 @@ keeping track of the configuration easier.
 # This file should be at the root of your project
 language: ruby
 cache: bundler
+before_install:
+  - gem install bundler
 script:
   - bundle exec jekyll algolia
 branches:
@@ -68,6 +70,16 @@ You might have to edit the `branches.only` value to either `master` or
 `gh-pages`, depending on which branch is configured to be deployed in your
 GitHub Pages configuration.
 
+### Ignoring vendors
+
+Travis bundles all gems in the `vendor` directory on its servers, which Jekyll
+will mistakenly read. This will likely make the process fail. To avoid this,
+add `vendor` to the `exclude` list in your `_config.yml` file.
+
+```yml
+exclude: [vendor]
+```
+
 ## Adding the API Key
 
 The plugin will need your Admin API key to push data. Because you don't want to

docs-src/src/hooks.md

@@ -67,20 +67,21 @@ 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.
+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 two arguments: `record` and `node`. `record` is the hash
-of the record, ready to be pushed to Algolia. `node` is a [Nokogiri][5]
-representation of the HTML node the record was extracted from (as specified in
-[nodes_to_index][6].
+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][5] representation of the HTML node the record was extracted from
+(as specified in [nodes_to_index][6]). `context` gives more information about
+the whole indexing process (check the following table for more details).
 
 | Key  | Value  |
 | ---- | ---- |
-| Signature | `before_indexing_each(record, node)` |
-| Arguments | <ul><li>`record`: A hash of the record that will be pushed</li><li>`node`: A [Nokogiri][7] representation of the HTML node it was extracted from</li></ul> |
+| Signature | `before_indexing_each(record, node, context)` |
+| Arguments | <ul><li>`record`: A hash of the record that will be pushed</li><li>`node`: A [Nokogiri][7] representation of the HTML node used to extract the content</li><li>`context`: More information about the whole website. <ul><li>`context.data`: Any data defined in the `_data` folder</li><li>`context.config`: Settings defined in  `_config.yml`</li><li>`data.collections`: Custom collections and posts</li></ul></li></ul> |
 | Expected returns | <ul><li>A hash of the record to be indexed</li><li>`nil` if the record should not be indexed</li></ul> |
 
 ### Example
@@ -89,9 +90,9 @@ representation of the HTML node the record was extracted from (as specified in
 module Jekyll
   module Algolia
     module Hooks
-      def self.before_indexing_each(record, node)
+      def self.before_indexing_each(record, node, context)
         # Do not index deprecation warnings
-        return nil if node.attr('class') =~ 'deprecation-notice'
+        return nil if node.matches?('.deprecation-notice')
         # Add my name as an author to each record
         record[:author] = 'Myself'
 
@@ -104,20 +105,22 @@ end
 
 ## `before_indexing_all`
 
-This hook is very similar to [before_index_each][8], but instead of being called
+This hook is similar to [before_index_each][8], 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 one argument, `records`, being the full list of records
-to be pushed, and expects a list of records to be returned.
+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.
 
 | Key  | Value  |
 | ---- | ---- |
-| Signature | `before_indexing_all(records)` |
-| Arguments | <ul><li>`records`: An array of hashes representing the records that are going to be pushed</li></ul> |
+| Signature | `before_indexing_all(records, context)` |
+| Arguments | <ul><li>`records`: An array of hashes representing the records that are going to be pushed</li><li>`context`: More information about the whole website. <ul><li>`context.data`: Any data defined in the `_data` folder</li><li>`context.config`: Settings defined in  `_config.yml`</li><li>`data.collections`: Custom collections and posts</li></ul></li></ul> |
 | Expected returns | <ul><li>An array of hashes to be pushed as records</li></ul> |
 
 ### Example
@@ -126,7 +129,7 @@ knowing the full context of what is going to be pushed.
 module Jekyll
   module Algolia
     module Hooks
-      def self.before_indexing_all(records)
+      def self.before_indexing_all(records, context)
         # Add a tags array to each record
         records.each do |record|
           record[:tags] = []
@@ -143,11 +146,12 @@ module Jekyll
 end
 ```
 
+
 [1]: ./options.html
 [2]: https://jekyllrb.com/docs/plugins/#installing-a-plugin
 [3]: ./options.html#extensions-to-index
 [4]: ./options.html#files-to-exclude
 [5]: http://www.nokogiri.org
 [6]: ./options.html#nodes-to-index
-[7]: http://www.nokogiri.org
+[7]: https://github.com/sparklemotion/nokogiri/wiki/Cheat-sheet
 [8]: hooks.html#hook-before-indexing-each

docs-src/src/how-it-works.md

@@ -6,8 +6,8 @@ layout: content-with-menu.pug
 # How does this work?
 
 This page will give you a bit more insight about how the internals of the plugin
-are working. This should give you more context to better understand the various
-options you can configure.
+are working. This should give you more context to better understand the options
+you can configure.
 
 ## Extracting data
 
@@ -28,9 +28,6 @@ Here is an example of what a record looks like:
   "title": "New experimental version of Hacker News Search built with Algolia",
   "type": "post",
   "url": "/2015/01/12/try-new-experimental-version-hn-search.html",
-  "draft": false,
-  "layout": "post",
-  "ext": ".md",
   "date": 1421017200,
   "excerpt_html": "<p>Exactly a year ago, we began to power […]</p>",
   "excerpt_text": "Exactly a year ago, we began to power […]",
@@ -38,14 +35,12 @@ Here is an example of what a record looks like:
 
   "html": "<p>We've learned a lot from your comments […]</p>",
   "content": "We've learned a lot from your comments […]",
-  "tag_name": "p",
-  "hierarchy": {
-    "lvl0": null,
-    "lvl1": "Applying more UI best practices",
-    "lvl2": "Focus on readability",
-  },
+  "headings": [
+    "Applying more UI best practices",
+    "Focus on readability"
+  ],
   "anchor": "focus-on-readability",
-  "weight": {
+  "custom_ranking": {
     "position": 8,
     "heading": 70
   }
@@ -55,30 +50,37 @@ Here is an example of what a record looks like:
 Each record created that way will contain a mix of shared data and specific
 data. Shared data is the metadata of the page it was extracted from (`title`,
 `slug`, `url`, `tags`, etc, as well as any custom field added to the
-front-matter). Specific data is the paragraph content, and information
-about its position in the page (where its situated in the hierarchy of headings
-in the page).
+front-matter). Specific data is the paragraph content and, if applicable, the
+list of parent headings (based on the `<h1>` and `<h6>` of the page).
 
-Using the [distinct setting][1] of the Algolia API, only the best matching
+Using the [distinct setting][1] of the Algolia API, the best matching
 paragraph of each page is returned for a specific query. This greatly improves
 the perceived relevance of the search results as you can highlight specifically
 the part that was matching.
 
+Also note that the response you'll get from the API might be enriched with
+[\_highlightResult][2] and [\_snippetResult][3] keys. Those keys are
+automatically added when performing a search and are not part of the saved
+record.
+
 ## Pushing data
 
 The plugin tries to be smart by using as less operations as possible, to be
-mindful of your Algolia quota. Whenever you run `jekyll algolia`, only records
+mindful of your Algolia quota. Whenever you run `jekyll algolia`, records
 that changed since your last push will be updated.
 
 This is made possible because each record is attributed a unique `objectID`,
 computed as a hash of the actual content of the record. Whenever the content of
-the record changes, its `objectID` will change as well. This allows us to compare
-what is current available in your index and what is about to be pushed, to only
-update what actually changed.
+the record changes, its `objectID` will change as well. This allows us to
+compare what is available in your index and what is about to be
+pushed, to update what actually changed.
 
 Previous outdated records will be deleted, and new updated records will be added
 instead. All those operations are grouped into a batch call, making sure that
 the changes are done atomically: your index will never be in an inconsistent
-state where records are only partially updated.
+state where records are partially updated.
+
 
 [1]: https://www.algolia.com/doc/guides/ranking/distinct/?language=ruby#distinct-to-index-large-records
+[2]: https://www.algolia.com/doc/api-reference/api-methods/search/?language=ruby#method-response-_highlightresult
+[3]: https://www.algolia.com/doc/api-reference/api-methods/search/?language=ruby#method-response-_snippetresult

docs-src/src/layouts/common/footer.pug

@@ -17,7 +17,7 @@ section.footer-new-cta.footer-new.h300.pos-rel
       .button-holder.h200.p-r-large
         .spacer16.hidden-md.hidden-sm
         span.inline.pos-rel
-          a.btn.btn-static-primary.btn-static-shadow-dark(href='https://algolia.com/users/sign_up')
+          a.btn.btn-static-primary.btn-static-shadow-dark(href='https://www.algolia.com/users/sign_up/hacker')
             | Get Started
             i.icon.icon-arrow-right.color-bunting.m-l-small
 

docs-src/src/layouts/index.pug

@@ -26,10 +26,10 @@ block body
         .flex-none.align-right.text-lg Demo
         .spacer16
         .flex-container.flex-dir-row.flex-row-align-right
-          a.flex-none.m-r-large.color-bunting.p-r-large.p-l-large.p-t-small.p-b-small.radius6.fill-athens-gray(href="")
+          a.flex-none.m-r-large.color-bunting.p-r-large.p-l-large.p-t-small.p-b-small.radius6.fill-athens-gray(href="https://github.com/algolia/jekyll-algolia")
             i.icon.icon-github.m-r-small
             | GitHub
-          a.flex-none.color-bunting.p-r-large.p-l-large.p-t-small.p-b-small.radius6.fill-athens-gray(href="")
+          a.flex-none.color-bunting.p-r-large.p-l-large.p-t-small.p-b-small.radius6.fill-athens-gray(href="https://community.algolia.com/jekyll-algolia-example/")
             i.icon.icon-play.m-r-small
             | Live Demo
 

docs-src/src/migration-guide.md

@@ -86,9 +86,6 @@ Here is an example of a record extracted by the plugin:
   "title": "New experimental version of Hacker News Search built with Algolia",
   "type": "post",
   "url": "/2015/01/12/try-new-experimental-version-hn-search.html",
-  "draft": false,
-  "layout": "post",
-  "ext": ".md",
   "date": 1421017200,
   "excerpt_html": "<p>Exactly a year ago, we began to power […]</p>",
   "excerpt_text": "Exactly a year ago, we began to power […]",
@@ -96,14 +93,12 @@ Here is an example of a record extracted by the plugin:
 
   "html": "<p>We've learned a lot from your comments […]</p>",
   "content": "We've learned a lot from your comments […]",
-  "tag_name": "p",
-  "hierarchy": {
-    "lvl0": null,
-    "lvl1": "Applying more UI best practices",
-    "lvl2": "Focus on readability",
-  },
+  "headings": [
+    "Applying more UI best practices",
+    "Focus on readability"
+  ],
   "anchor": "focus-on-readability",
-  "weight": {
+  "custom_ranking": {
     "position": 8,
     "heading": 70
   }

docs-src/src/options.md

@@ -26,16 +26,21 @@ you might want to update the value like this:
 ```yml
 algolia:
   # Also index AsciiDoc and Textile files
-  extensions_to_index: 'html,md,adoc,textile'
+  extensions_to_index:
+    - html
+    - md
+    - adoc
+    - textile
 ```
 
 ## `files_to_exclude`
 
-This option lets you define a blacklist of source files you don't want to index.
+This option lets you define a list of source files you don't want to index.
 
-By default it will exclude all the `index.html` and `index.md` files. Those
-files are usually not containing much text (landing pages) or containing
-redundant text (latest blog articles) so they are not included by default.
+By default it will exclude the `index.html` and `index.md` files found at the
+root. Those files are usually not containing much text (landing pages) or
+containing redundant text (latest blog articles) so they are not included by
+default.
 
 If you want to index those files, you should set the value to an empty array.
 
@@ -46,7 +51,7 @@ algolia:
 ```
 
 If you want to exclude more files, you should add them to the array. Note that
-you can use glob patterns to exclude several files at once.
+you can use glob patterns (`*` and `**`) to exclude several files at once.
 
 ```yml
 algolia:
@@ -57,6 +62,7 @@ algolia:
     - excluded-file.html
     - _posts/2017-01-20-date-to-forget.md
     - subdirectory/*.html
+    - **/*.tmp.html
 ```
 
 _Note that some files (pagination pages, static assets, etc) will **always** be
@@ -100,7 +106,17 @@ algolia:
 ```
 
 Settings defined here will take precedence over any setting you manually defined
-through the [Algolia dashboard][5] UI, though.
+through the [Algolia dashboard][5] UI, though. If you'd like this not to happen
+at all, and only take the dashboard settings in account, pass `false` to the
+settings configuration.
+
+```yml
+algolia:
+  settings: false
+```
+
+We suggest users to at least run with the default settings once, so that the default
+relevance settings are set, which you can override via the dashboard after.
 
 ## `indexing_batch_size`
 
@@ -120,6 +136,24 @@ algolia:
   indexing_batch_size: 500
 ```
 
+## `max_record_size`
+
+**This is an advanced option. It has no effect on Community plans.**
+
+If you're using a paid Algolia plan, you can push records that weight up to 20Kb
+(as opposed to 10Kb with the free Community plan). This option allows you to
+adjust the maximum size of one record (in bytes).
+
+```yml
+algolia:
+  # Recommended setting for paid plans
+  max_record_size: 20000
+```
+
+_Note that if you push a record that is larger than your allowed limit,
+the push will be rejected by the API. This might result in incomplete data being
+uploaded._
+
 
 [1]: ./how-it-works.html
 [2]: http://www.methods.co.nz/asciidoc/

docs-src/src/stylesheets/components/_documentation.scss

@@ -127,11 +127,7 @@ $offset-height: 64px;
         li {
           line-height: 26px;
 
-          &:before {
-            content: '-';
-            float: left;
-            margin-right: 6px;
-            color: $logan; } } } }
+           } } }
 
     .content {
       position: relative;