diff --git a/docs/src/behavior.md b/docs/src/behavior.md index e95a50ba..81b71c0e 100644 --- a/docs/src/behavior.md +++ b/docs/src/behavior.md @@ -3,11 +3,11 @@ layout: two-columns title: Dropdown Behavior --- -Our [JS library `docsearch.js`] is a wrapper of the [autocomplete.js][1] library. This -library will listen to keystrokes in the search input, query Algolia and display -the results in a dropdown. Everything is already configured for you to work with -DocSearch, but it also exposes configuration options you can use to go even -further. +Our [JS library `docsearch.js`] is a wrapper of the [autocomplete.js][1] +library. This library will listen to keystrokes in the search input, query +Algolia and display the results in a dropdown. Everything is already configured +for you to work with DocSearch, but it also exposes configuration options you +can use to go even further. ## `appId` @@ -25,8 +25,8 @@ docsearch({ ## `handleSelected` This method is called when a suggestion is selected. By default, DocSearch will -redirect the browser to the result's page at the related anchor, but you can override -it to add your own behavior. +redirect the browser to the result's page at the related anchor, but you can +override it to add your own behavior. The method is called with three arguments: diff --git a/docs/src/config-file.md b/docs/src/config-file.md index 95a95229..d6bb17bb 100644 --- a/docs/src/config-file.md +++ b/docs/src/config-file.md @@ -240,8 +240,8 @@ Other special keys can be set, as documented below. The default way of extracting content through selectors is to read the HTML markup from top to bottom. This works well with semi-structured content, like a -hierarchy of headers. This breaks when the relevant information is not part of the -same flow. For example when the title is apart in a header or a sidebar. +hierarchy of headers. This breaks when the relevant information is not part of +the same flow. For example when the title is apart in a header or a sidebar. For that reason, you can set a selector as global, meaning that it will match on the whole page, and will be the same for all records extracted on this page. diff --git a/docs/src/crawler-overview.md b/docs/src/crawler-overview.md index a3260e75..c787f1a4 100644 --- a/docs/src/crawler-overview.md +++ b/docs/src/crawler-overview.md @@ -11,8 +11,8 @@ HTML structure to populate an Algolia index. It will automatically follow every internal link to make sure we are not missing any content, and will use the semantics of your HTML structure to construct its -records. This means that `h1`...`h6` (`selectors`) titles will be used for the hierarchy, and -each `p` of text will be used as a potential result. +records. This means that `h1`...`h6` (`selectors`) titles will be used for the +hierarchy, and each `p` of text will be used as a potential result. Those CSS selectors can be overwritten, and each website actually has its own JSON configuration file that describe in more details how the crawling should diff --git a/docs/src/dropdown.md b/docs/src/dropdown.md index 53fbcddc..4c8b1e5c 100644 --- a/docs/src/dropdown.md +++ b/docs/src/dropdown.md @@ -3,11 +3,12 @@ layout: two-columns title: Dropdown --- -Once your algolia DocSearch index is ready, correctly set up and filled with the right data, you will need to integrate our dedicated Search-UI. -To add the dropdown of results below your search input, you'll have to include -the docsearch library into your website as per the following example. Your -`apiKey` and `indexName` credentials will be given to you as soon as we've -created your config. +Once your algolia DocSearch index is ready, correctly set up and filled with the +right data, you will need to integrate our dedicated Search-UI. To add the +dropdown of results below your search input, you'll have to include the +docsearch library into your website as per the following example. Your `apiKey` +and `indexName` credentials will be given to you as soon as we've created your +config. ```html @@ -28,7 +29,7 @@ created your config. // matching your search input inputSelector: '', // Set debug to true if you want to inspect the dropdown - debug: false + debug: false }); ``` diff --git a/docs/src/faq.md b/docs/src/faq.md index 004127dd..47768f70 100644 --- a/docs/src/faq.md +++ b/docs/src/faq.md @@ -21,7 +21,8 @@ Nothing. The DocSearch crawler is running on our own infra. It will read the HTML content from your website and populate an Algolia index with it every day. All you need -to do is keep your website online, and we take care of the rest. If you wante to edit your configuration; please submit a pull request. +to do is keep your website online, and we take care of the rest. If you wante to +edit your configuration; please submit a pull request. ### How much does it cost? diff --git a/docs/src/how-do-we-build-an-index.md b/docs/src/how-do-we-build-an-index.md index b5813d7c..83210e70 100644 --- a/docs/src/how-do-we-build-an-index.md +++ b/docs/src/how-do-we-build-an-index.md @@ -5,45 +5,56 @@ title: How do we build a DocSearch index? In this section you will learn how do we build a DocSearch index from your page. - ### Everything start from your page 1st step -_Note: We would rather avoid useless js rendering. Every used information should be avaible without any client side rendering. You can use `curl` in order to have a better idea of how does it look._ +_Note: We would rather avoid useless js rendering. Every used information should +be avaible without any client side rendering. You can use `curl` in order to +have a better idea of how does it look._ + +### We extract the payload thank to your set of `selectors` -### We extract the payload thank to your set of `selectors ` 2nd step We will only focus on the information highlted thank to your selectors. ### We iterate though the HTML flow and build the payload + 3rd step This payload will be the only considered data from your page. ### We iterate though the payload and start pushing record -4th step -We index the temporary record at every time we agregate an element int it (if `min_indexed_level` is set to `0` ). +4th step + +We index the temporary record at every time we agregate an element int it (if +`min_indexed_level` is set to `0` ). ### We pile them up based on the current temporary record + 5th step -Base on the position withitn the flow, we nest elements as much as possble to keep the contextual relevancy. +Base on the position withitn the flow, we nest elements as much as possble to +keep the contextual relevancy. ### We iterate until we match a `text` element + 6th step - ### We override text element when we find a newer one + 7th step ### We flush deeper element than the newest one + 7th step -Contextual information and hierarchy must be updated once we encouter a new level since it highlights a new sub section not related to the previous one. +Contextual information and hierarchy must be updated once we encouter a new +level since it highlights a new sub section not related to the previous one. -If you need any further onformation, please [do not hesitate and send us your feedback][1]. +If you need any further onformation, please [do not hesitate and send us your +feedback][1]. [1]: mailto:docsearch@algolia.com diff --git a/docs/src/how-does-it-work.md b/docs/src/how-does-it-work.md index 0ce800e7..0612d932 100644 --- a/docs/src/how-does-it-work.md +++ b/docs/src/how-does-it-work.md @@ -4,8 +4,8 @@ title: How does it work? --- Getting up and ready with DocSearch is a straightforward process that requires a -three steps: you apply, we configure the crawler for you, and you integrate our Search-UI in your -frontend. It is as simple as copying and pasting a snippet. +three steps: you apply, we configure the crawler for you, and you integrate our +Search-UI in your frontend. It is as simple as copying and pasting a snippet. How it works @@ -21,11 +21,11 @@ applications, so please give us a couple of days to get back to you :) ### We create a configuration -Once we receive [your application][2], we'll have a look at your website and create a -custom configuration file for it. This file defines which URLs we should crawl -or ignore, as well as the specific CSS selectors to be used for selecting -headers, subheaders, etc. All configs are publicly available in our [config -repository][1]. +Once we receive [your application][2], we'll have a look at your website and +create a custom configuration file for it. This file defines which URLs we +should crawl or ignore, as well as the specific CSS selectors to be used for +selecting headers, subheaders, etc. All configs are publicly available in our +[config repository][1]. This step still requires some manual work, but thanks to the 1 000+ configs we already created, we're able to automate most of it. Once done, we'll run a first @@ -39,8 +39,8 @@ your Algolia index on each keystroke in a dropdown menu. The default styling of the dropdown uses a grey theme to fit in most designs. The dropdown itself is made of HTML with custom CSS classes and we recommend -that [you overwrite those classes][3] to provide a theming more inline with the rest -of your website. +that [you overwrite those classes][3] to provide a theming more inline with the +rest of your website. Now that DocSearch is set, you don't have anything else to do. We'll keep crawling your website every day and update your search results automatically. diff --git a/docs/src/inside-the-engine.md b/docs/src/inside-the-engine.md index 3c9787f5..b44b7fc2 100644 --- a/docs/src/inside-the-engine.md +++ b/docs/src/inside-the-engine.md @@ -12,25 +12,29 @@ Each crawl will begin its journey by the value of the `start_urls` you have in your config. It will read those pages and recursively extract and follow every links in those pages until it has browsed every compliant pages. -If you have explictly defined a `sitemap.xml`, our crawler will scrap every -provided and compliant pages. We do recommend to use [a sitemap][1] since it -clearly exposes URLs to crawl and avoid missing page that aren't linked from +If you have explictly defined a `sitemap.xml`, our crawler will scrap every +provided and compliant pages. We do recommend to use [a sitemap][1] since it +clearly exposes URLs to crawl and avoid missing page that aren't linked from another one. ## Extracting content -Building records using the scraper is pretty intuitive. According to your settings, -we extract the payload of your webpage and index it, preserving your data's structure. -This is achieved in a simple way: -* We **read top down** your web page following your HTML flow and pick out your -matching elements according their **levels** based on the `selectors_level` defined. -* We create a record for each paragraph along with its hierarchical path. -This construction is based on their **time of appearance** along the flow. -* We **index** these records with the appropriate global settings (e.g. metadata, tags, etc.) +Building records using the scraper is pretty intuitive. According to your +settings, we extract the payload of your webpage and index it, preserving your +data's structure. This is achieved in a simple way: -_**Note:** The above process performs sanity tests as it scrapes, in order to detect errors. -If indeed there are any serious warnings, it will abort and therefore not overwrite your current index. -These checks ensure that your dedicated index isn't flushed._ +- We **read top down** your web page following your HTML flow and pick out your + matching elements according their **levels** based on the `selectors_level` + defined. +- We create a record for each paragraph along with its hierarchical path. This + construction is based on their **time of appearance** along the flow. +- We **index** these records with the appropriate global settings (e.g. + metadata, tags, etc.) + +_**Note:** The above process performs sanity tests as it scrapes, in order to +detect errors. If indeed there are any serious warnings, it will abort and +therefore not overwrite your current index. These checks ensure that your +dedicated index isn't flushed._ ## Ranking records @@ -39,22 +43,27 @@ approach][2]. DocSearch will first search for exact matches in your keywords then fallback to partial matches. Those results will then be ordered based, once again, on the page hierarchy, as extracted from the `selectors`. -The default strategy is to promote records having matching words in the highetst level fist. -Thus if two results have the same matching words, the one having them in the highest level -(lvl0) will be reanked higher. We also use the position of the matching words. The sooner -they appear within the HTML flow, the higher the record will be ranked. +The default strategy is to promote records having matching words in the highetst +level fist. Thus if two results have the same matching words, the one having +them in the highest level (lvl0) will be reanked higher. We also use the +position of the matching words. The sooner they appear within the HTML flow, the +higher the record will be ranked. The relevancy is based on several factors and can be customised according to the algolia tie-breaking method. -You can boost pages depending ont their URLs. This is done from the `start_urls` and its -`page_rank` attributes. It is a numeric value, default to 0. The bigger it is, the higher results from the matching pages will be ranked. -For example all pages with a `page_rank` of 5 will be returned before pages with a `page_rank` of 1. +You can boost pages depending ont their URLs. This is done from the `start_urls` +and its `page_rank` attributes. It is a numeric value, default to 0. The bigger +it is, the higher results from the matching pages will be ranked. For example +all pages with a `page_rank` of 5 will be returned before pages with a +`page_rank` of 1. -You could even change the relevancy strategy by [overwriting the default `customRanking`][3] used by the index by using -the `custom_settings` option of your config. +You could even change the relevancy strategy by [overwriting the default +`customRanking`][3] used by the index by using the `custom_settings` option of +your config. -[1]:https://www.sitemaps.org/ +[1]: https://www.sitemaps.org/ [2]: https://www.algolia.com/doc/guides/ranking/ranking-formula/#tie-breaking-approach + [3]:[https://www.algolia.com/doc/guides/ranking/custom-ranking/] diff --git a/docs/src/integrations.md b/docs/src/integrations.md index a229211d..ade3e04c 100644 --- a/docs/src/integrations.md +++ b/docs/src/integrations.md @@ -13,8 +13,8 @@ DocSearch on your website: - [GitBook][5] - [pkgdown][6] - [DocSearch indexing][7] -If you're a maintaining a similar tool and would like to be added to the list, get -[in touch with us][8], we would be happy to help. +If you're a maintaining a similar tool and would like to be added to the list, +get [in touch with us][8], we would be happy to help. [1]: https://docusaurus.io/ [2]: https://docusaurus.io/docs/en/search#docsNav diff --git a/docs/src/styling.md b/docs/src/styling.md index 404e5332..fc34e19b 100644 --- a/docs/src/styling.md +++ b/docs/src/styling.md @@ -55,10 +55,10 @@ and you're encouraged to style it to fit your own theming. All we ask is that you keep the `search by Algolia` logo and link next to your search results. The logo is automatically added in the dropdown with the default styling. It's -fine if you hide it through CSS, as long as you re-add it somewhere else on your page -close to the search input or search results. It's our way to let more people -know about what we do, and how they could also have a fast and relevant search -on their website. +fine if you hide it through CSS, as long as you re-add it somewhere else on your +page close to the search input or search results. It's our way to let more +people know about what we do, and how they could also have a fast and relevant +search on their website. If you're using your own [paid Algolia account][2] and [run the crawler yourself][3], you don't have to keep the logo. @@ -88,8 +88,8 @@ other display. ## Advanced styling -If you want to do more heavy styling, feel free to have a look at the [SCSS source -code][4]. `_variables.scss` contains all the default theming, sizing and +If you want to do more heavy styling, feel free to have a look at the [SCSS +source code][4]. `_variables.scss` contains all the default theming, sizing and breakpoints. You can generate your own CSS file by cloning the repository and running diff --git a/docs/src/tips.md b/docs/src/tips.md index ec1534a1..ca47602b 100644 --- a/docs/src/tips.md +++ b/docs/src/tips.md @@ -9,8 +9,9 @@ share some tips on how you can make the most out of DocSearch. ### Use a `sitemap.xml` -If you provide a sitemap from your configuration, DocSearch will use it to diretly browse the pages to -index. Pages are still crawled which means we extract every compliant link. +If you provide a sitemap from your configuration, DocSearch will use it to +diretly browse the pages to index. Pages are still crawled which means we +extract every compliant link. We highly recommend you add a `sitemap.xml` to your website if you don't have one already. This will make the indexing faster, but will also give you more @@ -29,18 +30,21 @@ information. This hierarchy brings contextual information to your records. Documentation starts by explaining generic concepts first and then goes deeper into specifics. This is represented in your HTML markup by the hierarchy of headings you're using. For example, concepts discussed under a `

` are more -specific than concepts discussed under a `

` in the same page. The sooner the information comes up within the page, the higher it is ranked. +specific than concepts discussed under a `

` in the same page. The sooner the +information comes up within the page, the higher it is ranked. DocSearch uses this structure to fine-tune the relevance of results as well as to provide potential filtering. Documentation that follow this pattern often have better relevance of search results. -Finding the right depth of your documentation tree and how to split-up your content is one of the most complex tasks. -For large documents, we usually recommend having 4 levels (from lvl0 until lvl3). -Three different levels should be the minimum. +Finding the right depth of your documentation tree and how to split-up your +content is one of the most complex tasks. For large documents, we usually +recommend having 4 levels (from lvl0 until lvl3). Three different levels should +be the minimum. -_Note that you don't have to use `` tags and can use -`` for example instead. Your will need to update your set of `selectors` +\_Note that you don't have to use `` tags and can use +`` for example instead. Your will need to update your set +of `selectors` ### Set a unique class to the element holding the content @@ -79,46 +83,50 @@ used as part of a CSS selector. ## Consistency of your content Consistency is a pillar of a meaningful documentation. In addition to increasing -the **intelligibility** of a document it also shortens the time required for a user -to find the coveted information. The document's **topic** should be easily **identifiable** -and its **outline** sharply demarcated. +the **intelligibility** of a document it also shortens the time required for a +user to find the coveted information. The document's **topic** should be easily +**identifiable** and its **outline** sharply demarcated. The hierarchy should always have the same size. Try to **avoid orphan records** such like the implicit introduction/conclusion or asides. The selectors must be -efficient for **every document** and highlight the proper hierarchy. -They need to match only the coveted elements depending on their level. -Be careful to avoid the **edge effect** by matching unexpected **superfluous elements**. +efficient for **every document** and highlight the proper hierarchy. They need +to match only the coveted elements depending on their level. Be careful to avoid +the **edge effect** by matching unexpected **superfluous elements**. -Selectors should only match information from **real document webpage** -and remain ineffective for others ones (e.g., landing page, table of content, etc.). -We urge the maintainer to define a **dedicated class** for the **main DOM container** -that includes the actual document content such as `.docSearch-content` - -Since documentation should be **interactive**, it is a key point to -**verbalize concepts with standardized words**. -This **redundancy**, empowered with the **search experience** (dropdown), -will even enable the **learn-as-you-type experience**. -The **way to find the information** plays a key role in **leading** the user to the -**retrieved knowledge itself**. You can also use the **synonym feature**. +Selectors should only match information from **real document webpage** and +remain ineffective for others ones (e.g., landing page, table of content, etc.). +We urge the maintainer to define a **dedicated class** for the **main DOM +container** that includes the actual document content such as +`.docSearch-content` +Since documentation should be **interactive**, it is a key point to **verbalize +concepts with standardized words**. This **redundancy**, empowered with the +**search experience** (dropdown), will even enable the **learn-as-you-type +experience**. The **way to find the information** plays a key role in +**leading** the user to the **retrieved knowledge itself**. You can also use the +**synonym feature**. ## Avoid duplicates by promoting unicity -The more time-consuming reading documentation is, the more painful and reluctant its use will be. -You must avoid hazy points or catch-all. In addition to it being unhelpful, -the catch-all document may be **confusing** and **counterproductive**. +The more time-consuming reading documentation is, the more painful and reluctant +its use will be. You must avoid hazy points or catch-all. In addition to it +being unhelpful, the catch-all document may be **confusing** and +**counterproductive**. -Last but not least duplicates introduce noise and mislead users. This is why -you should always focus on the relevant content and avoid duplicating content -within your site (e.g. landing page which contains all of the information, summing up, etc.). -In cases where the duplicates's existence is expected since it belongs to another -dataset (e.g. a different version), you should use [facets](https://www.algolia.com/doc/guides/searching/faceting/). +Last but not least duplicates introduce noise and mislead users. This is why you +should always focus on the relevant content and avoid duplicating content within +your site (e.g. landing page which contains all of the information, summing up, +etc.). In cases where the duplicates's existence is expected since it belongs to +another dataset (e.g. a different version), you should use +[facets](https://www.algolia.com/doc/guides/searching/faceting/). ## Conciseness What is clearly thought out is clearly and concisely expressed. -We really recommend you to read this blog post about [how to build a helpful search for techniacal documentation][2]. +We really recommend you to read this blog post about [how to build a helpful +search for techniacal documentation][2]. [1]: https://www.sitemaps.org/index.html -[2]: https://blog.algolia.com/how-to-build-a-helpful-search-for-technical-documentation-the-laravel-example/ \ No newline at end of file +[2]: + https://blog.algolia.com/how-to-build-a-helpful-search-for-technical-documentation-the-laravel-example/ diff --git a/docs/src/who-can-apply.md b/docs/src/who-can-apply.md index e4eea217..2bfd0de0 100644 --- a/docs/src/who-can-apply.md +++ b/docs/src/who-can-apply.md @@ -8,8 +8,8 @@ large technical documentation. For that reason, we offering our free hosting version to all technical documentations. We're always sad to have to turn down applications, but with the number of -requests we received everyday, we had to focus on several criteria. We -hope you understand. +requests we received everyday, we had to focus on several criteria. We hope you +understand. ### The checklist @@ -25,16 +25,17 @@ points. - Your website must be a **documentation website**. We do not index blogs and commercial content. -- Your website must **have some final content**. We won't index empty websites nor - those filled with lorem ipsum placeholder content. Please, wait until you have - written some documentation before applying. We would be happy to help you as soon as you have a steady design. +- Your website must **have some final content**. We won't index empty websites + nor those filled with lorem ipsum placeholder content. Please, wait until you + have written some documentation before applying. We would be happy to help you + as soon as you have a steady design. If in doubt, don't hesitate to [apply][1] and we'll figure it out together. Even if we cannot accept your request, this does not mean that you cannot enjoy great search on your website. DocSearch is entirely open source and [you can run -it yourself][2], or use any of [our other API clients][3] to take advantage of the -Algolia's features. +it yourself][2], or use any of [our other API clients][3] to take advantage of +the Algolia's features. ### Priority @@ -50,11 +51,10 @@ following criteria: - ☹️ If your website is rendered in the browser through JavaScript, it means that we'll have to crawl it through a much slower browser emulation. We highly - recommend that you put in place server-side rendering for the useful textual content. + recommend that you put in place server-side rendering for the useful textual + content. [1]: ./apply.html [2]: ./run-your-own.html [3]: https://www.algolia.com/doc/api-reference/ [4]: ./integrations.html - -