diff --git a/docs/src/faq.md b/docs/src/faq.md index 9c1a1e12..5905ad93 100644 --- a/docs/src/faq.md +++ b/docs/src/faq.md @@ -27,7 +27,7 @@ you need to do is keep your website online, and we take care of the rest. Nothing. -We know that paying for search infrastructure is a cost not many Open Source +We know that paying for search infrastructure is a cost not all Open Source projects can afford. That's why we decided to keep DocSearch free for everyone. All we ask in exchange is that you keep the _powered by [Algolia][2]_ logo displayed next to the search results. @@ -40,7 +40,7 @@ account (free accounts can hold as much as 10k records). ### What data are you collecting? The data we save in the index is the data we extract from your website -markup, in a custom JSON format instead of HTML. Exactly which part of the +markup, in a custom JSON format instead of HTML. Which part of the page is defined in your custom config. As the website owner, we also give you access to the Algolia Analytics @@ -48,6 +48,8 @@ dashboard, that will let you have more data about the anonymized searches that were done on your website. You'll be able to see the most searched terms, or those with no results. +_If you don't have Analytics access, send us an email and we'll enable it._ + ### Where is my data hosted? All DocSearch data is hosted on Algolia's servers, with replication around the @@ -56,7 +58,7 @@ complete information in our [privacy policy][4]. ### Can I use DocSearch on non-doc pages? -The free DocSearch we provide will only crawl documentation pages. If you want +The free DocSearch we provide will crawl documentation pages. If you want to use it on other parts of your website, you'll need to create your own Algolia account and either: @@ -68,8 +70,8 @@ account and either: Yes, but we do not recommend it. Code samples are a great way for humans to understand how a specific pattern -/ method should be used. Unfortunately, it often requires boilerplate code, -repeated into several examples, which will only add noise to the results. +/ method should be used. It often requires boilerplate code though, repeated +across examples, which will add noise to the results. What we recommend instead is to exclude the code blocks from the indexing (by using the `selectors_exclude` option in your config), and instead structure your @@ -77,9 +79,9 @@ content so the method names are actual headers. ### Why do I have duplicate content in my results? -This can happen when you have several urls pointing to the same content, for -example with `./docs`, `./docs/` and `./docs/index.html` or even both `http` and -`https` in place. +This can happen when you have more than one urls pointing to the same content, +for example with `./docs`, `./docs/` and `./docs/index.html` or even both `http` +and `https` in place. This can be fixed by `stop_urls` to all the patterns you want to exclude. The following example will exclude all urls ending with `/` or `index.html` as well diff --git a/docs/src/how-does-it-work.md b/docs/src/how-does-it-work.md index 7b7014d7..45081f27 100644 --- a/docs/src/how-does-it-work.md +++ b/docs/src/how-does-it-work.md @@ -4,7 +4,7 @@ title: How does it work? --- Getting up and ready with DocSearch is a straightforward process that requires -a few steps: you apply, we configure the crawler for you, and you update your +a three steps: you apply, we configure the crawler for you, and you update your front-end. How it works @@ -38,14 +38,15 @@ We'll then get back to you with the JavaScript snippet you'll need to add to your website. This will bind your search `input` field to display results from your Algolia index on each keystroke in a dropdown menu. -The default styling of the dropdown uses grey colors to fit in most designs. The -dropdown itself is made of HTML with custom CSS classes and we recommend that -you overwrite those classes to provide a theming more inline with the rest of -your website. +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 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. - +All we ask is that you keep the "search by Algolia" logo next to your search +results. [1]: https://github.com/algolia/docsearch-configs/tree/master/configs [2]: https://github.com/algolia/docsearch-scraper diff --git a/docs/src/styling.md b/docs/src/styling.md index ae78f3f2..f42bdfc8 100644 --- a/docs/src/styling.md +++ b/docs/src/styling.md @@ -3,12 +3,12 @@ layout: two-columns title: Styling DocSearch --- -DocSearch default colorscheme comes in grey colors with blue highlight. +DocSearch default colorscheme comes in a grey theme with blue highlight. ![Default colorscheme](./assets/default-colorscheme.png) This theme works well with most websites, but we encourage you to style it to -your own colors. This can be achieved by overriding the CSS classes used by the +your own theme. This can be achieved by overriding the CSS classes used by the default theme. The following annotated example will help you style each part: @@ -58,24 +58,24 @@ docsearch({ ## Other considerations -Currently selected suggestion are wrapped in a `.ds-cursor` class. This means +Selected suggestion are wrapped in a `.ds-cursor` class. This means that you can use `.ds-cursor .algolia-docsearch-suggestion--content` to style -the currently selected suggestion for example. +the selected suggestion for example. On small screens, DocSearch reverts to a single column layout, while the -two-column layout shown in the screenshot is only used on larger screens. You -can media queries (for example `@media (min-width: 768px) {}`) to target one or -the other display. +two-column layout shown in the screenshot is used on larger screens. You can +media queries (for example `@media (min-width: 768px) {}`) to target one or the +other display. -We ask you not to try to hide the _search by Algolia_ logo through CSS, as its -display is mandatory if you're using the free hosted version of DocSearch. +**We ask you not to try to hide the _search by Algolia_ logo through CSS, as its +display is mandatory if you're using the free hosted version of DocSearch.** ## Advanced styling If you want to more heavily style the results, feel free to have a look at the [SCSS source code](https://github.com/algolia/docsearch/tree/master/src/styles). -`_variables.scss` contains all the default colors, sizing and breakpoints. +`_variables.scss` contains all the default theming, sizing and breakpoints. You can generate your own CSS file by cloning the repo and running `yarn run build:css`. The resulting file will be generated in `./dist/cdn`, and should be