Add helpful error messages for each known error

errors/invalid_credentials.txt

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

errors/invalid_credentials_for_tmp_index.txt

@@ -0,0 +1,17 @@
+E: [✗ Error] Invalid credentials for temporary index
+E:
+E: The jekyll-algolia plugin could not access your index with the API key you
+E: provided.
+W:
+W: When using the `atomic` indexing mode, we will push all your content to a 
+W: temporary index, then overwrite the actual index with it. The API key you
+W: defined should have access rights on both.
+I: 
+I: Make sure your API key has access:
+I: - {index_name}
+I: - {index_name_tmp}
+I:
+I: You can configure API keys from your dashboard:
+I:    https://www.algolia.com/apps/{application_id}/api-keys/restricted
+I:
+I:

errors/invalid_index_name.txt

@@ -0,0 +1,11 @@
+E: [✗ Error] Invalid index name
+E:
+E: The jekyll-algolia plugin could push records to your index as its name
+E: contains invalid characters.
+W:
+W: Some special characters are not allowed in the naming of indices and your
+W: 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:

errors/missing_api_key.txt

@@ -1,13 +1,17 @@
-
-E: [✗ Error] No application ID defined
+E: [✗ Error] Missing API key
 E:
-E: The jekyll-algolia plugin could not find your Algolia application ID.
+E: The jekyll-algolia plugin could not find your API key.
 W:
-W: Please, define it in your Jekyll _config.yml file like this:
+W: Please, define your API key either by:
 W:
-W:   algolia:
-W:    application_id: {your_application_id}
+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` at the root of your Jekyll 
+W:    project (where your `_config.yml` file is). If you do this, we strongly
+W:    recommend you to NOT track this file in your versionning system.
 I:
-I: You can find your application ID along with all your credentials in your 
-I: Algolia dashboard here:
+I: You can find your API key in your Algolia dashboard here:
 I:    https://www.algolia.com/licensing
+I:
+I:

errors/record_too_big.txt

@@ -0,0 +1,25 @@
+E: [✗ Error] Record is too big
+E:
+E: The jekyll-algolia plugin could not push one of your records as it exceeds 
+E: the {size_limit} size limit.
+W:
+W: The plugin will create one record for each element matching your
+W: `nodes_to_index` value (currently set to "{nodes_to_index}"). Each record
+W: should not weight more than {size_limit}. One of your records weights {size} 
+W: and has been rejected.
+W:
+W: Here are more information about the rejected record:
+W: {
+W:   "objectID": "{object_id}",
+W:   "title": "{object_title}",
+W:   "url": "{object_url}",
+W:   "text": "{object_hint}…",
+W:   […]
+W: }
+W: 
+I: This issue is sometimes caused by malformed HTML preventing the parser to
+I: correctly grab the content of the nodes.
+I:
+I: If you're having trouble solving this issue, feel free to file a bug on
+I: GitHub, ideally with a link to a repository where we can reproduce the issue.
+I:    https://github.com/algolia/jekyll-algolia/issues

errors/unknown_application_id.txt

@@ -0,0 +1,20 @@
+E: [✗ Error] Unreachable server
+E:
+E: The jekyll-algolia plugin could not contact the server hosting your 
+E: application.
+W:
+W: Make sure you correctly typed your application ID. As we are using the
+W: application ID as part of the server url, any typo in the application ID will
+W: 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/licensing
+I:
+I: Then, define it in your Jekyll _config.yml file like this:
+I:
+I:   algolia:
+I:    application_id: {your_application_id}
+I:
+I:

errors/unknown_settings.txt

@@ -0,0 +1,15 @@
+E: [✗ Error] Unknown setting
+E:
+E: The jekyll-algolia plugin could not correctly configure your index as some of
+E: the settings passed are not recognized.
+W:
+W: It seems that one of the custom index settings you defined was not recognized
+W: by the API and was rejected:
+W:   {setting_name}: {setting_value}
+I:
+I: Make sure the setting name and value are correct. You can find a list of all
+I: the available settings with their documentation in our API reference:
+I:   https://www.algolia.com/doc/api-reference/api-parameters/
+I: Or specifically for this setting:
+I:  https://www.algolia.com/doc/api-reference/api-parameters/{setting_name}/
+I:

lib/jekyll/algolia/error_handler.rb

@@ -15,7 +15,7 @@ module Jekyll
           Logger.log('E:[jekyll-algolia] Error:')
           Logger.log("E:#{error}")
         else
-          Logger.known_error(
+          Logger.known_message(
             identified_error[:name],
             identified_error[:details]
           )
@@ -136,7 +136,7 @@ module Jekyll
         message = error.message
         return false if message !~ /^Cannot reach any host/
 
-        matches = /.*\((.*)\.algolia.net.*/.match(message)
+        matches = /.*\((.*)-dsn\.algolia.net.*/.match(message)
 
         { 'application_id' => matches[1] }
       end
@@ -149,16 +149,18 @@ module Jekyll
       # not have access to the _tmp indices and the error message will reflect
       # that.
       def self.invalid_credentials_for_tmp_index?(error, _context = {})
-        return false unless invalid_credentials?(error)
-
         details = error_hash(error.message)
 
-        return false if details['index_name'] !~ /_tmp$/
+        index_name_tmp = details['index_name']
+        if details['message'] != 'Index not allowed with this API key' ||
+           index_name_tmp !~ /_tmp$/
+          return false
+        end
 
         {
-          'application_id' => details['application_id'],
+          'application_id' => Configurator.application_id,
           'index_name' => Configurator.index_name,
-          'index_name_tmp' => details['index_name']
+          'index_name_tmp' => index_name_tmp
         }
       end
 
@@ -175,8 +177,7 @@ module Jekyll
         end
 
         {
-          'application_id' => details['application_id'],
-          'index_name' => Configurator.index_name
+          'application_id' => details['application_id']
         }
       end
 
@@ -206,6 +207,7 @@ module Jekyll
           'object_title' => record[:title],
           'object_url' => record[:url],
           'object_hint' => record[:text][0..100],
+          'nodes_to_index' => Configurator.algolia('nodes_to_index'),
           'size' => size,
           'size_limit' => '10 Kb'
         }

spec/jekyll/algolia/error_handler_spec.rb

@@ -71,7 +71,7 @@ describe(Jekyll::Algolia::ErrorHandler) do
     context 'with unknown application_id' do
       let(:message) do
         'Cannot reach any host: '\
-        'getaddrinfo: Name or service not known (MY_APP_ID.algolia.net:443), '\
+        'getaddrinfo: Name or service not known (MY_APP_ID-dsn.algolia.net:443), '\
         'getaddrinfo: No address associated with hostname (MY_APP_ID-3.algolianet.com:443), '\
         'getaddrinfo: No address associated with hostname (MY_APP_ID-1.algolianet.com:443), '\
         'getaddrinfo: No address associated with hostname (MY_APP_ID-2.algolianet.com:443)'
@@ -86,20 +86,22 @@ describe(Jekyll::Algolia::ErrorHandler) do
         allow(configurator)
           .to receive(:index_name)
           .and_return('my_index')
+        allow(configurator)
+          .to receive(:application_id)
+          .and_return('MY_APP_ID')
       end
       let(:message) do
-        'Cannot POST to '\
-        'https://MY_APP_ID.algolia.net/1/indexes/my_index_tmp/batch: '\
-        '{"message":"Invalid Application-ID or API key","status":403}'\
-        "\n (403)"
+        '403: Cannot PUT to '\
+        'https://My_APP_ID.algolia.net/1/indexes/my_index_tmp/settings: '\
+        '{"message":"Index not allowed with this API key","status":403} (403)'
       end
 
       it { should include(name: 'invalid_credentials_for_tmp_index') }
       it do
         should include(details: {
-                         'application_id' => 'MY_APP_ID',
                          'index_name' => 'my_index',
-                         'index_name_tmp' => 'my_index_tmp'
+                         'index_name_tmp' => 'my_index_tmp',
+                         'application_id' => 'MY_APP_ID'
                        })
       end
     end
@@ -120,8 +122,7 @@ describe(Jekyll::Algolia::ErrorHandler) do
       it { should include(name: 'invalid_credentials') }
       it do
         should include(details: {
-                         'application_id' => 'MY_APP_ID',
-                         'index_name' => 'my_index'
+                         'application_id' => 'MY_APP_ID'
                        })
       end
     end
@@ -146,6 +147,12 @@ describe(Jekyll::Algolia::ErrorHandler) do
           { objectID: 'foo' }
         ] }
       end
+      before do
+        allow(configurator)
+          .to receive(:algolia)
+          .with('nodes_to_index')
+          .and_return('p,li,foo')
+      end
 
       it { should include(name: 'record_too_big') }
       it do
@@ -157,6 +164,7 @@ describe(Jekyll::Algolia::ErrorHandler) do
         expect(details['object_hint']).to match(/.{0,100}/)
         expect(details).to include('size' => '1.04 MiB')
         expect(details).to include('size_limit' => '10 Kb')
+        expect(details).to include('nodes_to_index' => 'p,li,foo')
       end
     end