From 9752f14527fc91eddfd6c401d3b0a7da8d1da244 Mon Sep 17 00:00:00 2001 From: Pixelastic Date: Wed, 20 Jan 2016 15:51:46 +0100 Subject: [PATCH] docs(options): Add documentation about custom options --- README.md | 163 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 125 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 79ae023f..8c169f41 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The easiest way to add search to your documentation. For free. -Check out our [website][3] to add an outstanding search to your documentation. +Check out our [website][1] to add an outstanding search to your documentation. [![Version][version-svg]][package-url] [![Build Status][travis-svg]][travis-url] [![Coverage Status][coveralls-svg]][coveralls-url] [![License][license-image]][license-url] [![Downloads][downloads-image]][downloads-url] @@ -19,20 +19,20 @@ Check out our [website][3] to add an outstanding search to your documentation. [docsearch-website]: https://community.algolia.com/docsearch/?utm_medium=social-owned&utm_source=GitHub&utm_campaign=docsearch%20repository [docsearch-website-docs]: https://community.algolia.com/docsearch/documentation/?utm_medium=social-owned&utm_source=GitHub&utm_campaign=docsearch%20repository -![Eslint][4] +![Eslint][7] ## Table of Contents -- [Introduction](#introduction) -- [Setup](#setup) -- [Customization](#customization) -- [Development workflow](#development-workflow) - - [Local example](#local-example) - - [Local build](#local-build) - - [Documentation website](#documentation-website) - - [MacOS](#macos) +- [Introduction][8] +- [Setup][9] +- [Customization][10] +- [Development workflow][11] + - [Local example][12] + - [Local build][13] + - [Documentation website][14] + - [MacOS][15] @@ -40,11 +40,15 @@ Check out our [website][3] to add an outstanding search to your documentation. ## Introduction -We're scratching our own itch here. As developers, we spend a lot of time reading documentation, and it isn't always easy to find the information we need. +We're scratching our own itch here. As developers, we spend a lot of time +reading documentation, and it isn't always easy to find the information we need. -Not blaming anyone here. Building a good search for a documentation is a complex challenge. We happen to have a lot of experience doing that, and we want to share it with the world. For free. +Not blaming anyone here. Building a good search for a documentation is a complex +challenge. We happen to have a lot of experience doing that, and we want to +share it with the world. For free. -Just submit the form on the [website](https://community.algolia.com/docsearch/) and we'll get back to you with what you need to integrate your new search into your website. +Just submit the form on the [website][16] and we'll get back to you with what +you need to integrate your new search into your website. 1. We'll crawl your documentation pages, 2. We'll configure your search experience, @@ -52,7 +56,8 @@ Just submit the form on the [website](https://community.algolia.com/docsearch/) ## Setup -Once we've crawled your documentation website we'll send you the credentials you need to add the following code snippet to your website: +Once we've crawled your documentation website we'll send you the credentials you +need to add the following code snippet to your website: ```html @@ -70,7 +75,7 @@ docsearch({ The default colorscheme is blue and gray: -![Default colorscheme](https://community.algolia.com/docsearch/img/default-colorscheme.png) +![Default colorscheme][17] To update the colors to suit your website, you just need to override a few colors. Here is an example of a CSS file that you can use as a basis and that @@ -116,7 +121,74 @@ sets white and purples colors. } ``` -Advanced users can also clone the repository, edit the [_variables.scss](https://github.com/algolia/docsearch/blob/master/src/styles/_variables.scss) file and re-build the CSS file using `npm run build:css`. +### Advanced styling + +If you want to do heavily change the way results are displayed, you might find +it easier to directly edit the `scss` files in this repository. + +`[_variables.scss][18]` +contains all the color, breakpoints and size definitions while +`[_main.scss][19]` +holds the structure of the display. + +You can regenerate the whole final `css` file from those `scss` files by running +`npm run build:css`. The resulting files will be found in `./dist/cdn/`. + +All you have to do now is change the `link` tag that was loading the default +styling from our CDN, to one that is loading your newly compiled file. + +## Custom options + +DocSearch is a wrapper around the [autocomplete.js][20] library that gets its +results from the Algolia API. As such, you can use any options provided by +[autocomplete.js][21] and by the Algolia API. + +### Autocomplete options + +You can pass any options to the underlying `autocomplete` instance through +the`autocompleteOptions` parameter. You will find all `autocomplete` options in +its [own documentation][22]. + +You can also listen to `autocomplete` events through the `.autocomplete` +property of the `docsearch` instance. + +```javascript +var search = docsearch({ + apiKey: '', + indexName: '', + inputSelector: '', + autocompleteOptions: { + // See https://github.com/algolia/autocomplete.js#options + // For full list of options + debug: true + } +}); + +// See https://github.com/algolia/autocomplete.js#custom-events +// For full list of events +search.autocomplete.on('autocomplete:opened', function(e) { + // Do something when the dropdown menu is opened +}); +``` + +### Algolia options + +You can also pass any specific option to the Algolia API to change the way +records are returned. You can pass any options to the Algolia API through +the `algoliaOptions` parameter. + +```javascript +docsearch({ + apiKey: '', + indexName: '', + inputSelector: '', + algoliaOptions: { + hitsPerPage: 10 + } +}); +``` + +You will find all Algolia API options in its [own documentation][23] @@ -124,10 +196,11 @@ Advanced users can also clone the repository, edit the [_variables.scss](https:/ ### Local example -We use a simple documentation example website as a way to develop the docsearch library. +We use a simple documentation example website as a way to develop the docsearch +library. Requirements: -- [Node.js][12] +- [Node.js][24] - npm@2 ```sh @@ -148,40 +221,54 @@ npm run dev ### Documentation website -This is the [Jekyll][13] instance running at [https://community.algolia.com/docsearch](https://community.algolia.com/docsearch). +This is the [Jekyll][25] instance running at +[https://community.algolia.com/docsearch](https://community.algolia.com/docsearch). Requirements: -- [Ruby][14] -- [Bundler][15] +- [Ruby][26] +- [Bundler][27] ```sh npm run dev:docs # open http://localhost:4000/docsearch/ # Note that it also implicitly starts another server on localhost:8080, to load -the bundled JavaScript from +# the bundled JavaScript from ``` ### MacOS -If you are using `brew` and you had `brew install openssl`, you may need to configure the build path of eventmachine with +If you are using `brew` and you had `brew install openssl`, you may need to +configure the build path of eventmachine with ```sh bundle config build.eventmachine --with-cppflags=-I$(brew --prefix openssl)/include ``` -[1]: https://travis-ci.org/algolia/docsearch.svg?branch=master -[2]: https://badge.fury.io/js/docsearch.js.svg -[3]: https://community.algolia.com/docsearch/ -[4]: ./docs/img/showcase/example-eslint.gif -[5]: #introduction -[6]: #setup -[7]: #customization -[8]: #development-workflow -[9]: #local-example -[10]: #documentation-website -[11]: #macos -[12]: https://nodejs.org/en/ -[13]: https://jekyllrb.com/ -[14]: https://www.ruby-lang.org/en/ -[15]: http://bundler.io/ +[1]: https://community.algolia.com/docsearch/ +[2]: https://img.shields.io/npm/v/docsearch.js.svg?style=flat-square +[3]: https://img.shields.io/travis/algolia/docsearch/master.svg?style=flat-square +[4]: https://img.shields.io/coveralls/algolia/docsearch/master.svg?style=flat-square +[5]: http://img.shields.io/badge/license-MIT-green.svg?style=flat-square +[6]: https://img.shields.io/npm/dm/docsearch.js.svg?style=flat-square +[7]: ./docs/img/showcase/example-eslint.gif +[8]: #introduction +[9]: #setup +[10]: #customization +[11]: #development-workflow +[12]: #local-example +[13]: #local-build +[14]: #documentation-website +[15]: #macos +[16]: https://community.algolia.com/docsearch/ +[17]: https://community.algolia.com/docsearch/img/default-colorscheme.png +[18]: https://github.com/algolia/docsearch/blob/master/src/styles/_variables.scss +[19]: https://github.com/algolia/docsearch/blob/master/src/styles/_main.scss +[20]: https://github.com/algolia/autocomplete.js +[21]: https://github.com/algolia/autocomplete.js +[22]: https://github.com/algolia/autocomplete.js#options +[23]: https://www.algolia.com/doc/ruby#full-text-search-parameters +[24]: https://nodejs.org/en/ +[25]: https://jekyllrb.com/ +[26]: https://www.ruby-lang.org/en/ +[27]: http://bundler.io/