diff --git a/README.md b/README.md index 89500394..3c5ce3a4 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,25 @@ # DocSearch -[![build status](https://travis-ci.org/algolia/docsearch.svg?branch=master)](http://travis-ci.org/algolia/docsearch) -[![NPM version](https://badge.fury.io/js/docsearch.js.svg)](http://badge.fury.io/js/docsearch.js) +The easiest way to add search to your documentation. For free. -We've created the fastest, easiest way to search within documentation. Check out our [website](https://community.algolia.com/docsearch/) to add an outstanding search to your documentation. +[![build status][1]](http://travis-ci.org/algolia/docsearch) +[![NPM version][2]](http://badge.fury.io/js/docsearch.js) + +Check out our [website][3] to add an outstanding search to your documentation. + +![Eslint][4] ## Table of Contents -- [Introduction](#introduction) -- [Setup](#setup) -- [Customization](#customization) -- [Development workflow](#development-workflow) - - [Local example](#local-example) - - [Documentation website](#documentation-website) - - [MacOS](#macos) +- [Introduction][5] +- [Setup][6] +- [Customization][7] +- [Development workflow][8] + - [Local example][9] + - [Documentation website][10] + - [MacOS][11] @@ -27,7 +31,7 @@ We're scratching our own itch here. As developers, we spend a lot of time readin 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][12] 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, @@ -51,20 +55,67 @@ docSearch({ ## Customization -To customize the look & feel of the dropdown menu, you can either: +The default colorscheme is blue and gray: - * edit the color [variables](https://github.com/algolia/docsearch/blob/master/src/styles/_variables.scss) and rebuild this project CSS (`npm run build:css`), - * or override the colors like we did in [dev/docsearch-styling.css](https://github.com/algolia/docsearch/blob/master/dev/docsearch-styling.css). +![Default colorscheme][13] + +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 +sets white and purples colors. + +```css +/* Bottom border of each suggestion */ +.algolia-docsearch-suggestion { + border-bottom-color: #3A3DD1; +} +/* Main category headers */ +.algolia-docsearch-suggestion--category-header { + background-color: #4B54DE; +} +/* Highlighted search terms */ +.algolia-docsearch-suggestion--highlight { + color: #3A33D1; +} +/* Highligted search terms in the main category headers */ +.algolia-docsearch-suggestion--category-header .algolia-docsearch-suggestion--highlight { + background-color: #4D47D5; +} +/* Currently selected suggestion */ +.aa-cursor .algolia-docsearch-suggestion--content { + color: #272296; +} +.aa-cursor .algolia-docsearch-suggestion { + background: #EBEBFB; +} + +/* For bigger screens, when displaying results in two columns */ +@media (min-width: 768px) { + /* Bottom border of each suggestion */ + .algolia-docsearch-suggestion { + border-bottom-color: #7671df; + } + /* Left column, with secondary category header */ + .algolia-docsearch-suggestion--subcategory-column { + border-right-color: #7671df; + background-color: #F2F2FF; + color: #4E4726; + } +} +``` + +Advanced users can also clone the repository, edit the [_variables.scss][14] +file and re-build the CSS file using `npm run build:css`. + ## Development workflow ### Local example -We use a simple documentation example website as a way to develop the docsearch.js library. +We use a simple documentation example website as a way to develop the docsearch library. Requirements: -- [Node.js](https://nodejs.org/en/) +- [Node.js][17] - npm@2 ```sh @@ -72,17 +123,30 @@ npm run dev # open http://localhost:8080 ``` +### Local build + +- `npm run build:js:` will transpile all the JavaScript files inside `./dist`. + We build a bundled (and bundled + minified) version for CDNs and another one + for npm +- `npm run build:css` will convert the SCSS to CSS, along with sourcemaps and + minified versions +- `npm run build:docs` will create the `./docs/documentation.md` file from the + `README.md` file, to be displayed on the website. +- `npm run build` will run all three previous commands + ### Documentation website -This is the [Jekyll](https://jekyllrb.com/) instance running at [https://community.algolia.com/docsearch](https://community.algolia.com/docsearch). +This is the [Jekyll][18] instance running at [https://community.algolia.com/docsearch](https://community.algolia.com/docsearch). Requirements: -- [Ruby](https://www.ruby-lang.org/en/) -- [Bundler](http://bundler.io/) +- [Ruby][19] +- [Bundler][20] ```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 ``` ### MacOS @@ -92,3 +156,25 @@ If you are using `brew` and you had `brew install openssl`, you may need to conf ```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://community.algolia.com/docsearch/ +[13]: ./docs/img/default-colorscheme.png +[14]: https://github.com/algolia/docsearch/blob/master/src/styles/_variables.scss +[15]: https://github.com/algolia/docsearch/blob/master/dev/docsearch-styling.css +[16]: https://github.com/algolia/docsearch/blob/master/src/styles/_variables.scss +[17]: https://nodejs.org/en/ +[18]: https://jekyllrb.com/ +[19]: https://www.ruby-lang.org/en/ +[20]: http://bundler.io/ diff --git a/docs/img/default-colorscheme.png b/docs/img/default-colorscheme.png new file mode 100644 index 00000000..5bac04fd Binary files /dev/null and b/docs/img/default-colorscheme.png differ