jekyll-algolia 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8760fc38d0bbef9d96d721d8a4a3434f6e92c90e
+  data.tar.gz: '026308472f72a208686432580d17d592a19cbbd1'
+SHA512:
+  metadata.gz: 9c795d6962ddf9e0dcd5f7b323506272f5af0d26cc170a588de5f01183fad3cf5628b54be0c3dfe842b6c20d14de39fb903b28754c75d1541bae0b62126c07ae
+  data.tar.gz: db570e83b0874e0dc8652ef8411b62b36f932cb1678e933a01dd60ca8a92abf7ecc1d3d881d36f54cf4875ee823474306488818520c624957938de66454f646e

data/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+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.
+
+We use [pull requests](https://github.com/algolia/jekyll-algolia/pulls)
+for collaboration. The workflow is as follow:
+
+- Create a local branch, starting from `develop`
+- Submit the PR on `develop`
+- Wait for review
+- Do the changes requested (if any)
+- We may ask you to rebase the branch to latest `develop` if it gets out of sync
+- Receive the thanks of the Algolia team :)
+
+# Development workflow
+
+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.
+
+## 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.
+
+## 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
+
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-algolia", :path => "/path/to/local/gem/folder"
+end
+```
+
+# Git Hooks
+
+If you plan on submitting a PR, I suggest you install the git hooks located in
+`./scripts/git_hook`.
+
+The easiest way is to create a symlink from your `.git/hooks` folder:
+
+```sh
+$ git root
+$ rm ./.git/hooks
+$ ln -s ./scripts/git_hooks/ ./.git/hooks
+```
+
+# Tagging and releasing
+
+If you need to release a new version of the gem, run `rake release` from the
+`develop` branch. It will ask you for the new version and automatically create
+the git tags, create the gem and push it to Rubygems.
+
+# Documentation
+
+## Requirements
+
+To run this project, you will 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)
+
+## Development
+
+```sh
+yarn
+yarn start
+```
+
+Go to <http://localhost:3000>.
+
+## Update docs
+
+```sh
+yarn docs:update
+git push
+```
+
+
+# Project owner
+
+[@pixelastic](https://github.com/pixelastic)

data/README.md

@@ -0,0 +1,99 @@
+# 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]
+
+Jekyll plugin to automatically index your content on Algolia.
+
+## Usage
+
+```shell
+$ bundle exec jekyll algolia
+```
+
+This will push the content of your Jekyll website to your Algolia index.
+
+## Documentation
+
+Official documentation can be found on
+[https://community.algolia.com/jekyll-algolia/](https://community.algolia.com/jekyll-algolia/)
+
+## Installation
+
+The plugin requires at least Jekyll 3.6.0 and Ruby 2.3.0.
+
+First, add the `jekyll-algolia` gem to your `Gemfile`, in the `:jekyll_plugins`
+section.
+
+```ruby
+# Gemfile
+
+group :jekyll_plugins do
+  gem 'jekyll-algolia'
+end
+```
+
+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
+site.
+
+*If you don't yet have an Algolia account, you can open a free [Community plan
+here][9]. Once signed in, you can get your credentials from
+[your dashboard][10].*
+
+Once you have your credentials, you should define your `application_id` and
+`index_name` 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
+following command:
+
+```shell
+ALGOLIA_API_KEY='{your_admin_api_key}' bundle exec jekyll algolia
+```
+
+Note that `ALGOLIA_API_KEY` should be set to your admin API key.
+
+# Thanks
+
+Thanks to [Anatoliy Yastreb][21] for a [great tutorial][22] 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://pages.github.com/versions.json
+[8]: http://bundler.io/
+[9]: https://www.algolia.com/users/sign_up/hacker
+[10]: https://www.algolia.com/licensing
+[11]: http://www.methods.co.nz/asciidoc/
+[12]: https://github.com/textile
+[13]: https://www.algolia.com/doc/api-reference/api-methods/set-settings/?language=ruby#set-settings
+[14]: https://www.algolia.com/doc/javascript
+[15]: https://github.com/algolia/hyde
+[16]: https://travis-ci.org/
+[17]: https://travis-ci.org/
+[18]: http://docs.travis-ci.com/user/environment-variables/
+[19]: /docs/travis-settings.png
+[20]: https://travis-ci.org
+[21]: https://github.com/ayastreb/
+[22]: https://ayastreb.me/writing-a-jekyll-plugin/

data/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:

data/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:

data/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:

data/errors/missing_api_key.txt

@@ -0,0 +1,17 @@
+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
+W:    versionning system.
+I:
+I: You can find your API key in your Algolia dashboard here:
+I:    https://www.algolia.com/licensing
+I:
+I:

data/errors/missing_application_id.txt

@@ -0,0 +1,12 @@
+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 
+I: Algolia dashboard here:
+I:    https://www.algolia.com/licensing

data/errors/missing_index_name.txt

@@ -0,0 +1,19 @@
+E: [✗ Error] No index name defined
+E:
+E: The jekyll-algolia plugin could not find the name of the Algolia index you 
+E: 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/errors/no_records_found.txt

@@ -0,0 +1,20 @@
+E: [✗ Error] No records found
+E:
+E: The jekyll-algolia plugin could find any records to index
+W:
+W: The plugin tried to extract records from the pages, posts and collections of
+W: your site but could not find anything to index.
+I:
+I: Make sure you did not exclude too many files from indexing using the
+I: `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
+I: match something in the page. 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 
+I: during extraction. Only the page content can be accessed. So if you defined
+I: a layout markup that is used only for one page, you should move it to the 
+I: page instead.
+I:

data/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

data/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:

data/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:

data/lib/jekyll-algolia.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'jekyll/commands/algolia'
+
+module Jekyll
+  # Requirable file, loading all dependencies.
+  # Methods here are called by the main `jekyll algolia` command
+  module Algolia
+    require 'jekyll/algolia/version'
+    require 'jekyll/algolia/utils'
+    require 'jekyll/algolia/hooks'
+    require 'jekyll/algolia/configurator'
+    require 'jekyll/algolia/logger'
+    require 'jekyll/algolia/error_handler'
+    require 'jekyll/algolia/file_browser'
+    require 'jekyll/algolia/extractor'
+    require 'jekyll/algolia/indexer'
+
+    @config = {}
+
+    # Public: Init the Algolia module
+    #
+    # config - A hash of Jekyll config option (merge of _config.yml options and
+    # options passed on the command line)
+    #
+    # The gist of the plugin works by instanciating a Jekyll site,
+    # monkey-patching its `write` method and building it.
+    def self.init(config = {})
+      @config = config
+      @site = Jekyll::Algolia::Site.new(@config)
+
+      exit 1 unless Configurator.assert_valid_credentials
+
+      self
+    end
+
+    # Public: Run the main Algolia module
+    #
+    # Actually "process" the site, which will acts just like a regular `jekyll
+    # build` except that our monkey patched `write` method will be called
+    # instead.
+    #
+    # Note: The internal list of files to be processed will only be created when
+    # calling .process
+    def self.run
+      @site.process
+    end
+
+    # Public: Get access to the Jekyll config
+    #
+    # All other classes will need access to this config, so we make it publicly
+    # accessible
+    def self.config
+      @config
+    end
+
+    # Public: Get access to the Jekyll site
+    #
+    # Tests will need access to the inner Jekyll website so we expose it here
+    def self.site
+      @site
+    end
+
+    # A Jekyll::Site subclass that overrides #write from the parent class to
+    # create JSON records out of rendered documents and push those records
+    # to Algolia instead of writing files to disk.
+    class Site < Jekyll::Site
+      def write
+        if Configurator.dry_run?
+          Logger.log('W:==== THIS IS A DRY RUN ====')
+          Logger.log('W:  - No records will be pushed to your index')
+          Logger.log('W:  - No settings will be updated on your index')
+        end
+
+        records = []
+        files = []
+        each_site_file do |file|
+          # Skip files that should not be indexed
+          is_indexable = FileBrowser.indexable?(file)
+          unless is_indexable
+            Logger.verbose("W:Skipping #{file.path}")
+            next
+          end
+
+          path = FileBrowser.path_from_root(file)
+          Logger.verbose("I:Extracting records from #{path}")
+          file_records = Extractor.run(file)
+
+          files << file
+          records += file_records
+        end
+
+        # Applying the user hook on the whole list of records
+        records = Hooks.apply_all(records)
+
+        # Adding a unique objectID to each record
+        records.map! do |record|
+          Extractor.add_unique_object_id(record)
+        end
+
+        Logger.verbose("I:Found #{files.length} files")
+
+        Indexer.run(records)
+      end
+    end
+  end
+end