jekyll-algolia 1.0.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3612f58d87d7a769325fb89b2e76ea707278083a
-  data.tar.gz: 3a9e7d91f9183086831d2b276b7fd9e980fcd55a
+  metadata.gz: acb6baac7733e9ffea20049f4da7ce780fc1a8f6
+  data.tar.gz: aca94cb6fdbc4cfc64ce8517d634fc27e390b69b
 SHA512:
-  metadata.gz: ac705f398e1afc3db83611145a1070f713fffa6b5b51c34ef1dd8d257aad4aa3004dd2bc012234cbe88012cbe3cb594a32ceec1e108803c2566d8341cef536ac
-  data.tar.gz: 3b2728420b29fbef3e8cbf258c355e84760f46657b7cdcf76d9c1f48eec48cd2192e373f23b9fcdd5206747e3262c5c9a5adbae9b8c58b80ee08efc2522317e4
+  metadata.gz: 7da14579642014799a3e8a159b09aa7862007af435b60cbaab3fa891df9d1e8da7c711296ff45ece7cd4e47fbc55bea8a52a4237205005ba1936b2dd99ed8ec1
+  data.tar.gz: 55cbe18cf38a8a0adb103599dff92bf21207eeda2504e4c6bdf4b9a9ae6d65da51ddcf1688199ae49b97b0a36b41c093dd3604e41eed35d5cfbb0288cfc4beca

data/CONTRIBUTING.md

@@ -1,10 +1,9 @@
 Hi collaborator!
 
-If you have a fix or a new feature, please start by checking in the
-[issues](https://github.com/algolia/jekyll-algolia/issues) if it is
-already referenced. If not, feel free to open one.
+If you have a fix or a new feature, please start by checking in the [issues][1]
+if it is already referenced. If not, feel free to open one.
 
-We use [pull requests](https://github.com/algolia/jekyll-algolia/pulls)
+We use [pull requests][2]
 for collaboration. The workflow is as follow:
 
 - Create a local branch, starting from `develop`
@@ -20,23 +19,18 @@ Start by running `bundle install` to get all the dependencies up to date.
 
 ## Testing
 
-Run `rake test` to launch all tests. You can run `rake test_details` to get an
-output with more details about the tests.
+Run `rake test` to launch the test suite. Run `./scripts/test_all_ruby_versions`
+to run the test on all the supported ruby versions (requires `rvm`).
 
 ## TDD
 
-// TODO
-
-## Testing different ruby versions
-
-You can test the gem across all the supported Ruby versions by running
-`./scripts/test_all_ruby_versions`. Note that you will need to have RVM
-installed for this to work.
+Run `rake watch` to start a watcher on the code and test files. Whenever you
+update the code, the relevant tests will be run. Incredibly useful for TDD.
 
 ## Testing local changes on an existing Jekyll website
 
 If you want to test the plugin on an existing Jekyll website while developping,
-I suggest updating the website `Gemfile` to point to the correct local directory
+we suggest updating the website `Gemfile` to point to the correct local directory
 
 ```ruby
 group :jekyll_plugins do
@@ -44,10 +38,29 @@ 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
+lint:auto_correct` to try to automatically correct the potential violations.
+It's always a good practice to double check the modification after an
+auto-correct.
+
 # Git Hooks
 
-If you plan on submitting a PR, I suggest you install the git hooks located in
-`./scripts/git_hook`.
+If you plan on submitting a PR, we suggest you install the git hooks located in
+`./scripts/git_hook`. Those hooks will run the linter on each commit, and the
+tests before each push. This greatly help reduce the chances of breaking the
+build on Travis.
 
 The easiest way is to create a symlink from your `.git/hooks` folder:
 
@@ -67,28 +80,36 @@ the git tags, create the gem and push it to Rubygems.
 
 ## Requirements
 
-To run this project, you will need:
+The documentation website uses Metalsmith (and not Jekyll), so you'll need:
 
-- Node.js >= v9.2.0, use nvm - [install instructions](https://github.com/creationix/nvm#install-script)
-- Yarn >= v1.3.2 - [install instructions](https://yarnpkg.com/en/docs/install#alternatives-tab)
+- Node.js >= v9.2.0, use nvm - [install instructions][3]
+- Yarn >= v1.3.2 - [install instructions][4]
 
 ## Development
 
-```sh
-yarn
-yarn start
-```
+All the documentation source files live in the `./docs-src` folder.
 
-Go to <http://localhost:3000>.
+To serve a local version of the documentation (including livereload), run `rake
+docs:serve`. The documentation will be available on
+[localhost:3000](http://localhost:3000/).
 
-## Update docs
+This will create a `./docs-dev` folder and serve files from there. This folder
+is ignored by git.
 
-```sh
-yarn docs:update
-git push
-```
+## Deploying docs
 
+To update the documentation website, you should run `rake docs:deploy` from the
+`develop` branch. This will merge `develop` into master, build the documentation
+into `docs` and push it. The content of the `./docs` folder will then be server
+by GitHub pages.
 
 # Project owner
 
-[@pixelastic](https://github.com/pixelastic)
+[@pixelastic][5]
+
+
+[1]: https://github.com/algolia/jekyll-algolia/issues
+[2]: https://github.com/algolia/jekyll-algolia/pulls
+[3]: https://github.com/creationix/nvm#install-script
+[4]: https://yarnpkg.com/en/docs/install#alternatives-tab
+[5]: https://github.com/pixelastic

data/README.md

@@ -1,12 +1,13 @@
 # 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]
 
-Jekyll plugin to automatically index your content on Algolia.
+Add fast and relevant search to your Jekyll site.
 
 ## Usage
 
@@ -19,7 +20,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/)
+[https://community.algolia.com/jekyll-algolia/][20]
 
 ## Installation
 
@@ -40,48 +41,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

data/lib/errors/invalid_credentials.txt

@@ -0,0 +1,12 @@
+E:[✗ Error] Invalid credentials
+E:
+E:The jekyll-algolia plugin could not connect to your application ID using the API key your provided.
+W:
+W:Make sure your API key has access to your {application_id} application.
+W:It should also have the rights to push to the following indices:
+W:   - {index_name}
+W:   - {index_object_ids_name}
+I:
+I:You can find your API key in your Algolia dashboard here:
+I:   https://www.algolia.com/licensing
+I:

data/lib/errors/invalid_index_name.txt

@@ -0,0 +1,9 @@
+E:[✗ Error] Invalid index name
+E:
+E:The jekyll-algolia plugin could push records to your index as its name contains invalid characters.
+W:
+W:Some special characters are not allowed in the naming of indices and your index {index_name} contains some of them.
+I:
+I:Please, check our FAQ for more details:
+I:  https://www.algolia.com/doc/faq/index-configuration/what-can-i-name-my-indices/
+I:

data/lib/errors/missing_api_key.txt

@@ -0,0 +1,15 @@
+E:[✗ Error] Missing API key
+E:
+E:The jekyll-algolia plugin could not find your API key.
+W:
+W:Please, define your API key either by:
+W:
+W:1/ Defining an ENV variable when calling `jekyll algolia`
+W:   $ ALGOLIA_API_KEY='your_api_key' jekyll algolia
+W:
+W:2/ Save your API key in a named `_algolia_api_key` in your source directory.
+W:   If you do this, we strongly recommend you to NOT track this file in your versionning system.
+I:
+I:You can find your API key in your Algolia dashboard here:
+I:   https://www.algolia.com/api-keys
+I:

data/lib/errors/missing_application_id.txt

@@ -0,0 +1,11 @@
+E:[✗ Error] No application ID defined
+E:
+E:The jekyll-algolia plugin could not find your Algolia application ID.
+W:
+W:Please, define it in your Jekyll _config.yml file like this:
+W:
+W:  algolia:
+W:    application_id: {your_application_id}
+I:
+I:You can find your application ID along with all your credentials in your Algolia dashboard here:
+I:   https://www.algolia.com/api-keys

data/lib/errors/missing_index_name.txt

@@ -0,0 +1,18 @@
+E:[✗ Error] No index name defined
+E:
+E:The jekyll-algolia plugin could not find the name of the Algolia index you want to push your records to.
+W:
+W:Please, define it in your Jekyll _config.yml file like this:
+W:
+W:  algolia:
+W:   index_name: your_index_name
+W:
+W:Alternatively, you can also define it as an ENV variable, like this:
+W:
+W:  $ ALGOLIA_INDEX_NAME='{your_index_name}' jekyll algolia 
+W:
+I:You can see all your indices from your Algolia dashboard here:
+I:  https://www.algolia.com/explorer
+I:
+I:Note that you don't have to create an index before pushing records.
+I:It will be created automatically if it does not exist yet.

data/lib/errors/no_records_found.txt

@@ -0,0 +1,14 @@
+E:[✗ Error] No records found
+E:
+E:The jekyll-algolia plugin could not find any records to index.
+W:
+W:The plugin tried to extract records from the pages, posts and collections of your site but could not find anything to index.
+I:
+I:Make sure you did not exclude too many files from indexing using the `files_to_exclude` option. You are currently excluding the following files:
+I:    {files_to_exclude}
+I:
+I:Also double check that your current value for `nodes_to_index` can actually match something in the pages. You are current indexing the following nodes:
+I:    {nodes_to_index}
+I:
+I:Note that all the markup that is defined in the layouts won't be available during extraction. Only the page content can be accessed. So if you defined a layout markup that is used only for one page, you should move it to the page instead.
+I:

data/lib/errors/record_too_big.txt

@@ -0,0 +1,27 @@
+E:[✗ Error] Record is too big
+E:
+E:The jekyll-algolia plugin detected that one of your records exceeds the {max_record_size} record size limit.
+W:
+W:title:    {object_title}
+W:url:      {object_url}
+W:size:     {record_size}
+W:
+W:Most probable keys causing the issue:
+W:   {probable_wrong_keys}
+W:
+W:Complete log of the record has been extracted to:
+W:   {record_log_path}
+W:
+I:This issue can be caused by malformed HTML preventing the parser to correctly grab the content of the nodes. Double check that the page actually renders correctly with a regular `jekyll build`.
+I:
+I:You can also exclude the page generating this error from the indexing by editing the `files_to_exclude` key of your config.
+I:
+I:If you think this is an error and your current Algolia plan should allow you to push records bigger than {max_record_size}, you can change the `max_record_size` config option to increase the limit. Paid plans have a limit set to 20Kb, while free Community plans have it set to 10Kb.
+I:
+I:The following documentation might help you:
+I:   - https://community.algolia.com/jekyll-algolia/options.html#files-to-exclude
+I:   - https://community.algolia.com/jekyll-algolia/options.html#nodes-to-index
+I:   - https://community.algolia.com/jekyll-algolia/options.html#max-record-size
+I:
+I:If you're still having trouble solving this issue, feel free to file a bug on GitHub, ideally with a link to a repository where we can reproduce the issue.
+I:  https://github.com/algolia/jekyll-algolia/issues

data/lib/errors/record_too_big_api.txt

@@ -0,0 +1,10 @@
+E:[✗ Error] Record is too big
+E:
+E:The API rejected one of your records because it is too big ({record_size}).
+W:
+W:Make sure the value of `max_record_size` (currently set to "{max_record_size}") matches the maximum size allowed by your current Algolia plan.
+W:
+I:Free Community plans can push records up to 10Kb (`max_record_size: 10000`, this is the default value), while paid plans can go up to 20Kb (`max_record_size: 20000`).
+I:
+I:If you're still having trouble solving this issue, feel free to file a bug on GitHub, ideally with a link to a repository where we can reproduce the issue.
+I:  https://github.com/algolia/jekyll-algolia/issues

data/lib/errors/settings_manually_edited.txt

@@ -0,0 +1,17 @@
+I:
+W:[jekyll-algolia] Configuration mismatch:
+W:It seems that your index settings have been edited from outside of the jekyll-algolia plugin.
+I:
+I:This can happen if you manually edited them from the Algolia dashboard, for example. Don't worry, they will still be honored (for now).
+I:
+I:Still, we strongly encourage you to save any custom config inside the algolia.settings key of your _config.yml instead. Any value set there will always take precedence over anything you manually set in your dashboard.
+I:This is the best way to be sure your settings won't be lost in the future.
+I:
+W:To keep your current custom config, here is what you should add to your _config.yml file:
+W:
+W:algolia:
+W:  settings:
+{settings}
+I:
+I:If you'd like to revert to the default settings, the easiest way is to delete the {index_name} index from your dashboard and run `jekyll algolia` again.
+I:

data/lib/errors/too_many_records.txt

@@ -0,0 +1,14 @@
+E:[✗ Error] Too many records
+E:
+E:The jekyll-algolia plugin could not push your records because it exceeds the maximum number of records allowed in your current plan.
+W:
+W:Community plans can host up to 10k records and Essential plans starts at 50k.
+W:
+W:Check our pricing page for more details:
+W:   https://www.algolia.com/pricing
+W:
+I:You might want to upgrade your plan or exclude records from indexing using the `files_to_exclude` option:
+I:   https://community.algolia.com/jekyll-algolia/options.html#files-to-exclude
+I:
+I:If you're having trouble solving this issue, feel free to file a bug on GitHub, ideally with a link to a repository where we can reproduce the issue as well as the APPID you're trying to push to.
+I:  https://github.com/algolia/jekyll-algolia/issues

data/lib/errors/unknown_application_id.txt

@@ -0,0 +1,16 @@
+E:[✗ Error] Unreachable server
+E:
+E:The jekyll-algolia plugin could not contact the server hosting your application.
+W:
+W:Make sure you correctly typed your application ID. As we are using the application ID as part of the server url, any typo in the application ID will prevent us from reaching your server.
+W:
+I:Here is the application ID you defined: {application_id}
+I:
+I:Make sure it's the same as the one displayed in your dashboard:
+I:   https://www.algolia.com/api-keys
+I:
+I:Then, define it in your Jekyll _config.yml file like this:
+I:
+I:  algolia:
+I:    application_id: your_application_id
+I: