Update GitHub pages doc

docs-src/src/github-pages.md

@@ -5,76 +5,86 @@ layout: content-with-menu.pug
 
 # Deploying on GitHub Pages
 
-Explain how to deploy on add search on GitHub Pages. Imagine that they already
-have a GitHub pages website.
+GitHub offers free hosting for static websites through its [GitHub Pages][1] feature.
+It also has builtin support for Jekyll website. Once [properly configured][2],
+every time you push your Jekyll website to GitHub, it will be deployed on
+a `username.github.io/reponame` url.
 
-Then based on if they push to master or gh-pages, should create a Travis account
-and put all the info so it builds automatically each time.
+But GitHub will only build your website (`jekyll build`), it will not run other
+commands (`jekyll algolia`), so if you want to update your search results on
+each push, you'll have to find another way.
 
+We recommend using [Netlify][3], but if you want to stay hosted on GitHub pages,
+this page will explain how to keep your search records in sync with your
+deployed website.
 
+## Enabling Travis
 
-## GitHub Pages
+[Travis CI][4] is an hosted continuous integration
+service, and it's free for open-source projects. It can listen to any changes in
+your GitHub repository and run a specific command in response.
 
-The initial goal of the plugin was to allow anyone to have access to great
-search, even on a static website hosted on GitHub pages.
+We will use it to automatically run `jekyll algolia` every time a new push to
+your GitHub Pages is done.
 
-But GitHub does not allow custom plugins to be run on GitHub Pages.
-This means that you'll either have to run `bundle exec jekyll algolia push`
-manually, or configure a CI environment (like [Travis][16] to do it for you.
+Here are the steps to follow to setup your Travis account for your project:
 
-[Travis CI][17] is an hosted continuous integration
-service, and it's free for open-source projects. Properly configured, it can
-automatically reindex your data whenever you push to `gh-pages`.
+- Go to [travis-ci.org][5] and open an account
+- Click on your avatar and "Accounts"
+- Find your GitHub repository in the list and activate it
 
-For it to work, you'll have 3 steps to perform.
+_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._
 
-### 1. Create a `.travis.yml` file
+![Travis configuration](./assets/images/travis-config.png)
 
-Create a file named `.travis.yml` at the root of your project, with the
-following content:
+## Configuring Travis
 
-```yml
+Now that Travis is enabled, we have to configure it to tell it what to do on
+every new push to your repo. This can be done through the Travis UI, but we
+recommend doing it through a `.travis.yml` file in your repository. It makes
+keeping track of the configuration easier.
+
+```yaml
+# .travis.yml
+# This file should be at the root of your project
 language: ruby
 cache: bundler
+script:
+  - bundle exec jekyll algolia
 branches:
   only:
-    - gh-pages
-script:
-  - bundle exec jekyll algolia push
+    # Change this to gh-pages if you're deploying using the gh-pages branch
+    - master
 rvm:
- - 2.2
+ - 2.4
 ```
 
-This file will be read by Travis and instruct it to fetch all dependencies
-defined in the `Gemfile`, then run `jekyll algolia push`. This will be
-triggered when data is pushed to the `gh-pages` branch.
+This file will be read by Travis and instruct it to fetch all the dependencies
+defined in the `Gemfile` through Bundler. It will then run `bundle exec jekyll
+algolia` which will actually index your data.
 
-### 2. Update your `_config.yml` file to exclude `vendor`
+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.
 
-Travis will download all you `Gemfile` dependencies into a directory named
-`vendor`. You have to tell Jekyll to ignore this directory, otherwise Jekyll
-will try to parse it (and fail).
+## Adding the API Key
 
-Doing so is easy, add the following line to your `_config.yml` file:
+The plugin will need your Admin API key to push data. Because you don't want to
+expose this key in your repository, you'll have to add `ALGOLIA_API_KEY` as an
+environment variable to Travis. You can do that through the UI, in your Travis
+Settings page.
 
-```yml
-exclude: [vendor]
-```
+![Travis environment variables](./assets/images/travis-env.png)
 
-### 3. Configure Travis
+## Done
 
-In order for Travis to be able to push data to your index on your behalf, you
-have to give it your write API Key. This is achieved by defining an
-`ALGOLIA_API_KEY` [environment variable][18] in Travis settings.
-
-You should also uncheck the "Build pull requests" option, otherwise any pull
-request targeting `gh-pages` will trigger the reindexing.
-
-![Travis Configuration][19]
-
-### Done
-
-Commit all the changes to the files, and then push to `gh-pages`. Travis will
+Commit all the changes you made, and then push your repository. Travis will
 catch the event and trigger your indexing for you. You can follow the Travis job
-execution directly on [their website][20].
+execution directly on your Travis dashboard, with a full log.
 
+[1]: https://pages.github.com/
+[2]: https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/
+[3]: ./netlify.html
+[4]: https://travis-ci.org/
+[5]: https://travis-ci.org/

docs-src/src/netlify.md

@@ -5,8 +5,16 @@ layout: content-with-menu.pug
 
 # Deploying on Netlify
 
+Go on Netlify, add site.
+
+Add a netlify.toml (or update through UI). Add jekyll build && jekyll algolia
+Netlify takes care of using bundle if detects a Gemfile
+But runs with ruby 2.1.2, not compatible with the plugin.
+Add a .ruby-version containing 2.4 to change the version
+
 Showing how to deploy on Netlify easily
 
 
 
 
+