From cd46aa71aace96a5c27a407940deb2ca1564d0ec Mon Sep 17 00:00:00 2001 From: Sylvain Pace Date: Mon, 10 Sep 2018 18:32:14 +0200 Subject: [PATCH] Doc/update content (#448) * fixing extra link * adding mention * adding redundant problem * fixing link issue * styling fix --- docs/src/behavior.md | 19 +++++----- docs/src/config-file.md | 69 ++++++++++++++++++++++++++++++++++++ docs/src/crawler-overview.md | 8 ++--- docs/src/faq.md | 19 ++++++++-- 4 files changed, 99 insertions(+), 16 deletions(-) diff --git a/docs/src/behavior.md b/docs/src/behavior.md index f54e496b..45296699 100644 --- a/docs/src/behavior.md +++ b/docs/src/behavior.md @@ -11,9 +11,9 @@ even further. ## `appId` -If you're running the DocSearch crawler on your own, you'll need to define your -application ID using the `appId` key. If you're using the free hosted version, -you don't need to add anything. +If you're [running the DocSearch crawler on your own][2], you'll need to define +your application ID using the `appId` key. If you're using the free hosted +version, you don't need to add anything. ```javascript docsearch({ @@ -79,7 +79,7 @@ docsearch({ You can pass any option to the underlying `autocomplete.js` instance by using the `autocompleteOptions` parameter. You will find the list of all available -values in [the official documentation][2]. +values in [the official documentation][3]. You can also listen to `autocomplete` events through the `.autocomplete` property of the `docsearch` instance. @@ -100,10 +100,10 @@ search.autocomplete.on('autocomplete:opened', event => { ## `algoliaOptions` You can pass options to the Algolia API by using the `algoliaOptions` key. You -will find all Algolia API options in their [own documentation][3]. +will find all Algolia API options in their [own documentation][4]. For example, you might want to increase the number of results displayed in the -dropdown. [`hitsPerPage` set the number of shown hits][4]. +dropdown. [`hitsPerPage` set the number of shown hits][5]. ```javascript docsearch({ @@ -115,6 +115,7 @@ docsearch({ ``` [1]: https://github.com/algolia/autocomplete.js -[2]: https://github.com/algolia/autocomplete.js#options -[3]: https://www.algolia.com/doc/api-reference/api-parameters/ -[4]: https://www.algolia.com/doc/api-reference/api-parameters/hitsPerPage/ +[2]: ./run-your-own.html +[3]: https://github.com/algolia/autocomplete.js#options +[4]: https://www.algolia.com/doc/api-reference/api-parameters/ +[5]: https://www.algolia.com/doc/api-reference/api-parameters/hitsPerPage/ diff --git a/docs/src/config-file.md b/docs/src/config-file.md index 358e2c02..75db60ba 100644 --- a/docs/src/config-file.md +++ b/docs/src/config-file.md @@ -53,6 +53,72 @@ not follow links that are on another domain and never follow links defined in } ``` +### `selectors_key`, tailor your selectors + +You can define finer sets of selectors depending on the URL. This is done thanks +to the parameter `selectors_key` from your `start_urls` item. + +```json +{ + "start_urls": [ + { + "url": "http://www.example.com/docs/faq/", + "selectors_key": "faq" + }, + { + "url": "http://www.example.com/docs/" + } + ], + […], + "selectors": { + "default": { + "lvl0": ".docs h1", + "lvl1": ".docs h2", + "lvl2": ".docs h3", + "lvl3": ".docs h4", + "lvl4": ".docs h5", + "text": ".docs p, .docs li" + }, + "faq": { + "lvl0": ".faq h1", + "lvl1": ".faq h2", + "lvl2": ".faq h3", + "lvl3": ".faq h4", + "lvl4": ".faq h5", + "text": ".faq p, .faq li" + } + } +} +``` + +To find the right subset to use based on the URL, we iterate over these +`start_urls` items. The first one matching is applied. + +Considering the URL `http://www.example.com/en/api/` with the configuration: + +```json +{ + "start_urls": [ + { + "url": "http://www.example.com/doc/", + "selectors_key": "doc" + }, + { + "url": "http://www.example.com/doc/faq/", + "selectors_key": "faq" + }, + […], + ] +} +``` + +Only the set of selector related to `doc` will be applied to the URL. The +correct configuration should be build the other way around (as primarily +described). + +If one `start_urls` item has no `selectors_key` defined, the `default` set will +be used. Do not forget to precise this fallback. + ### Using regular expressions The `start_urls` option also allows for passing an object in place of a string, @@ -90,6 +156,7 @@ docsearch({ algoliaOptions: { 'facetFilters': ["lang:en", "version:latest"] }, + […], }); ``` @@ -111,6 +178,8 @@ filter based on their values as well. } ``` +From your JS snippet: + ```js docsearch({ […], diff --git a/docs/src/crawler-overview.md b/docs/src/crawler-overview.md index 2767f9aa..25ba4954 100644 --- a/docs/src/crawler-overview.md +++ b/docs/src/crawler-overview.md @@ -25,10 +25,10 @@ infrastructure, meaning that you don't need to install anything on your side. We run this service entirely free of charge, but we're asking that you keep the "powered by Algolia" logo next to the search results. -That being said, if you'd like to run DocSearch on your own, [all the code is -open source][3] and even packaged as a Docker image. Download it, and run it -with your own credentials. +That being said, if you'd like to [run DocSearch on your own][3], all the code +is open source and even packaged as a Docker image. Download it, and run it with +your own credentials. [1]: https://scrapy.org/ [2]: ./crawler-config.html -[3]: https://github.com/algolia/docsearch-scraper +[3]: ./run-your-own.html diff --git a/docs/src/faq.md b/docs/src/faq.md index 56e5d5a1..ed872e46 100644 --- a/docs/src/faq.md +++ b/docs/src/faq.md @@ -97,14 +97,26 @@ as those starting with `http://`. } ``` +### Why are the custom changes from the Algolia dashboard ineffective? + +Changing your setting from the dashboard might be something you want to do for +some reasons . + +Please be aware that your DocSearch settings are set at every time the crawler +is successful. These settings will be overridden at the next crawl. We **do not +recommend to edit anything from the dashboard**. These changes have be made from +the JSON configuration itself. + +You can use the [custom_settings parameter][9] in such purpose. + ### A documentation website I like does not use DocSearch. What can I do? We'd love to help! If one of your favorite tool documentation websites is missing DocSearch, we encourage you to file an issue in their repository explaining how DocSearch -could help. Feel free to ping `@docsearch` on GitHub in the issue as well, and -we'll provide all the help we can. +could help. Feel free to [send us an email][1] as well, and we'll provide all +the help we can. [1]: mailto:docsearch@algolia.com [2]: https://www.algolia.com/ @@ -112,5 +124,6 @@ we'll provide all the help we can. [4]: https://www.algolia.com/pricing#community [5]: https://www.algolia.com/doc/guides/infrastructure/servers/ [6]: https://www.algolia.com/policies/privacy -[7]: ./crawler-overview.html +[7]: ./run-your-own.html [8]: https://www.algolia.com/doc/api-reference/ +[9]: ./config-file.html#custom_settings-optional