# hexo-algolia [![Build Status][]][pkg-build] ![][pkg-downloads] ![][pkg-version] > Index content of your [hexo][] website in [Algolia][] and add search within minutes. `hexo-algolia` is an [hexo][] plugin provided by the community. This is what you get when you install it: 1. a **new command**, `hexo algolia`, to index the content of your website 2. a **theme helper** to include Algolia search client 3. another **theme helper** to configure the Algolia search client 👌 The `hexo algolia` command can be run manually on your computer and on a continuous integration system like [Travis CI][-ci-node]. 📜 Browse the [CHANGELOG][] to learn what has changed between versions. ⬢ Compatible with `node>=4.0.0`. [hexo theme][] ## Install ```bash $ npm install --save hexo-algolia ``` ## Public Facing Search Options You can configure Algolia integration to your hexo website with the `_config.yml` file: ``` yaml algolia: applicationID: 'applicationID' apiKey: 'apiKey' indexName: '...' ``` | Config Key | | | --- | --- | | `applicationID` | Your Algolia Application ID | | `apiKey` | A **Search-Only** API key | | `indexName` | The name of the Algolia index to use | These configuration values are **accessible from your hexo theme**, to be used with [Algolia JavaScript client](https://www.algolia.com/doc/guides/search/auto-complete/#user-interface). ## Hexo Theme Setup Helpers are provided to make your life easier. ### Include Algolia JavaScript Client The `algolia_search` theme helper adds the [Algolia search client][js-client] to your pages. ```html <%- algolia_search() %> ``` Renders as: ```html ``` ### Configure Algolia JavaScript Client You can make your index configuration available to your page and client-side scripts by adding the `algolia_config()` hexo helper in the `` of your document. ```html <%- algolia_search_config() %> ``` Once done, you can retrieve Algolia configuration by querying the [`data attribute`](dataset) of the `algolia:search` meta tag. ```js const algoliaConfig = document.querySelector('meta[property="algolia:search"]').dataset; const client = algoliasearch(algoliaConfig.applicationId, algoliaConfig.apiKey); const index = client.initIndex(algoliaConfig.indexName); ``` ### Display Search Results It is now up to you to use the aforementioned example to trigger a search and display the results in your page. If you need some help, have a look at the [search client doc][js-client] and [the tutorials][Algolia tutorials]. ## Indexing Content Content is indexed with the help of the `hexo algolia` command. ```bash $ ./node_modules/.bin/hexo algolia ``` ### API Key A separate _API Key_ must be provided as an **environment variable** named `HEXO_ALGOLIA_INDEXING_KEY`. Create it with **these limited write access** permissions: `Add records`, `Delete records`, `List indices`, `Delete index`. ```bash $ export HEXO_ALGOLIA_INDEXING_KEY=… $ ./node_modules/.bin/hexo algolia ``` ![](algolia-write-key.png) ### Usage ``` $ ./node_modules/.bin/hexo help algolia Usage: ./node_modules/.bin/hexo algolia Description: Index your content in Algolia Search API Options: --dry-run Does not push content to Algolia (default: false). --flush Resets the Algolia index before starting the indexation (default: false). --indexing-key An algolia API key with add/delete records permissions. It should be different than the search-only API key configured in _config.yml. --layouts A comma-separated list of page layouts to index (default: "page"). ``` ### Security Concerns **Never store your _Admin API Key_** as `apiKey` in the `_config.yml` file: **it would give full control of your Algolia index to others** and [you don't want to face the consequences][daily-mirror-bonanza]. [Please read Algolia Security guide thoroughly][security] if you need some more informations about this. # License [MIT](LICENSE) [Build Status]: https://travis-ci.org/oncletom/hexo-algolia.svg?branch=master [pkg-build]: https://travis-ci.org/oncletom/hexo-algolia [pkg-downloads]: https://img.shields.io/npm/dm/hexo-algolia.svg [pkg-version]: https://img.shields.io/npm/v/hexo-algolia.svg [hexo]: https://hexo.io/ [Algolia]: https://www.algolia.com/ [hexo theme]: https://hexo.io/docs/themes.html [travis-ci-node]: https://docs.travis-ci.com/user/languages/javascript-with-nodejs/ [Algolia Tutorials]: https://www.algolia.com/doc/tutorials/ [CHANGELOG]: https://github.com/oncletom/hexo-algolia/blob/master/CHANGELOG.md [js-client]: https://www.algolia.com/doc/api-client/javascript/ [batching]: https://www.algolia.com/doc/guides/indexing/import-synchronize-data/#batching [security]: https://www.algolia.com/doc/guides/security/api-keys/ [dataset]: https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes [daily-mirror-bonanza]: http://www.mirror.co.uk/all-about/cybersecurity