From 559b5429808648025985ff17af1e88c036ce0fa6 Mon Sep 17 00:00:00 2001 From: Pixelastic Date: Tue, 21 Aug 2018 10:55:21 +0200 Subject: [PATCH 1/5] docs(git): Remove old mark --- docs/src/config-file.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/src/config-file.md b/docs/src/config-file.md index 4cb29bd4..294ba9f2 100644 --- a/docs/src/config-file.md +++ b/docs/src/config-file.md @@ -79,15 +79,6 @@ The following example will make it clearer: } ``` -<<<<<<< HEAD -We mostly attribute it on our own regarding plenty of underlying factors. The `apiKey` that we provide is generated with a restriction on the `index_name`. Changing the `index_name` would require to ask for a new key. Thus if you want to **change the name**, please **submit a new configuration**, we will generate a new key accordingly. -### `start_urls` _Mandatory_ -You can pass either a string or an array of urls. The crawler will go to each -page in order, following every link it finds on the page. It will only stop if -the domain is outside of the `allowed_domains` or if the link is blacklisted from the `stop_urls`. - -Note that we currently do not follow *301* redirects. -======= The beneficial side effect of using this syntax is that all records that will then be extracted from crawling `http://www.example.com/docs/en/latest` will have `lang: en` and `version: latest` added to it, allowing you to then filter based on From b073c0cc1ade87e4fcc22298c4537a03ff4e1b3c Mon Sep 17 00:00:00 2001 From: Pixelastic Date: Tue, 21 Aug 2018 11:49:15 +0200 Subject: [PATCH 2/5] docs(logo): Add more mentions of using the Algolia logo --- docs/src/faq.md | 18 ++++++++++-------- docs/src/how-does-it-work.md | 13 +++++++------ docs/src/styling.md | 20 ++++++++++---------- 3 files changed, 27 insertions(+), 24 deletions(-) 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 From 98b66bde05cf847ae5d588e27012de3028efb71f Mon Sep 17 00:00:00 2001 From: Pixelastic Date: Tue, 21 Aug 2018 12:11:32 +0200 Subject: [PATCH 3/5] docs(account): Add link to community account --- docs/src/faq.md | 26 ++++++++++++++------------ docs/src/run-your-own.md | 2 +- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/src/faq.md b/docs/src/faq.md index 5905ad93..21894713 100644 --- a/docs/src/faq.md +++ b/docs/src/faq.md @@ -32,10 +32,10 @@ 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. -If this is not possible for you, you're totally free to open your own Algolia -account and run DocSearch on your own without this limitation. In that case +If this is not possible for you, you're totally free to [open your own Algolia +account][3] and run DocSearch on your own without this limitation. In that case though, depending on the size of your documentation, you might need a paid -account (free accounts can hold as much as 10k records). +account ([free accounts][4] can hold as much as 10k records). ### What data are you collecting? @@ -53,8 +53,8 @@ _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 -globe. You can find more details about the actual [server specs here][3], and more -complete information in our [privacy policy][4]. +globe. You can find more details about the actual [server specs here][5], and more +complete information in our [privacy policy][6]. ### Can I use DocSearch on non-doc pages? @@ -62,12 +62,12 @@ 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: -- Run the [DocSearch crawler][5] on your own -- Use one of our other [framework integrations or API clients][6] +- Run the [DocSearch crawler][7] on your own +- Use one of our other [framework integrations or API clients][8] ### Can you index code samples? -Yes, but we do not recommend it. +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. It often requires boilerplate code though, repeated @@ -109,7 +109,9 @@ well, and we'll provide all the help we can. [1]: mailto:docsearch@algolia.com [2]: https://www.algolia.com/ -[3]: https://www.algolia.com/doc/guides/infrastructure/servers/ -[4]: https://www.algolia.com/policies/privacy -[5]: ./crawler-overview.html -[6]: https://www.algolia.com/doc/api-reference/ +[3]: https://www.algolia.com/pricing +[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 +[8]: https://www.algolia.com/doc/api-reference/ diff --git a/docs/src/run-your-own.md b/docs/src/run-your-own.md index 1a10a712..5fedb319 100644 --- a/docs/src/run-your-own.md +++ b/docs/src/run-your-own.md @@ -124,7 +124,7 @@ Note that we use this CLI tool internally at Algolia to run the free hosted version, so you might not need all the listed commands. [1]: https://github.com/algolia/docsearch-scraper -[2]: https://www.algolia.com/users/sign_up +[2]: https://www.algolia.com/pricing#community [3]: ./config-file.html [4]: https://github.com/algolia/docsearch-configs/tree/master/configs [5]: ./dropdown.html From 694534efd05ba7c6e0a3be4e392742e8d87ff6bb Mon Sep 17 00:00:00 2001 From: Pixelastic Date: Tue, 21 Aug 2018 13:48:49 +0200 Subject: [PATCH 4/5] docs(homepage): Rewriting --- docs/src/_layouts/homepage.pug | 96 ++++++++++++++++++++++++---------- 1 file changed, 68 insertions(+), 28 deletions(-) diff --git a/docs/src/_layouts/homepage.pug b/docs/src/_layouts/homepage.pug index 8150daae..34cfa980 100644 --- a/docs/src/_layouts/homepage.pug +++ b/docs/src/_layouts/homepage.pug @@ -98,9 +98,16 @@ block content .glide__caption Yarn .max-w-md.m-auto.text-center - h2.text-solstice.text-5.normal.pb-2 State-of-the-art search for technical documentation - p.text-3.pb-1.text-telluric We're kind of 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. - p.text-3.pb-2.text-telluric No one's to blame, building a good search is a complex challenge. We just happen to have a lot of experience doing that, and we want to share it with the developer community. + h2.text-solstice.text-5.normal.pb-2 + |State-of-the-art search for technical documentation + p.text-3.pb-1.text-telluric + |We're kind of 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. + p.text-3.pb-2.text-telluric + |No one's to blame, building a good search is a complex challenge. We + |just happen to have a lot of experience doing that, and we want to + |share it with the developer community. .max-w-xl.m-auto.pt-3.mb-2 .demo-header-wrapper @@ -111,9 +118,17 @@ block content .px-2.bg-analytics .max-w-xl.m-auto.text-center.mb-2 .max-w-md.m-auto.mb-3 - .text-solstice.text-5.normal.pb-2 Learn-as-you-type experience - .pb-1.text-3.leading-2 Documentation speaks to your users. Ideally, this conversation will be pleasant and efficient. Everyone visiting your documentation page has a different need: Some are exploring your product, some are trying to get started, and some are stuck and need help. - .text-3.leading-2 DocSearch is designed to provide relevant search results at every level. Its strutured layout give the users more context to understand the product. + .text-solstice.text-5.normal.pb-2 + |Learn-as-you-type experience + .pb-1.text-3.leading-2 + |Documentation speaks to your users. Ideally, this conversation will + |be pleasant and efficient. Everyone visiting your documentation page + |has a different need: Some are exploring your product, some are + |trying to get started, and some are stuck and need help. + .text-3.leading-2 + |DocSearch is designed to provide relevant search results at every + |level. Its strutured layout give the users more context to understand + |the product. .max-w-xl.m-auto img.hidden.md_block(src="assets/docsearch-UI-anatomy.png", alt="Anatomy of DocSearch UI") @@ -122,31 +137,56 @@ block content .fln.w-100.md_w-40.text-center img(src="assets/illus-analytics.svg", alt="DocSearch Analytics", width=400) .fln.w-100.md_w-50.px-1.md_pt-3.mb-3 - .text-solstice.text-5.normal.pb-2.text-center.md_text-left Powerful Analytics with Algolia - .text-3.leading-2.text-center.md_text-left.pb-1 Search usage of your documentation gives you unvaluable insights about what your users need to ramp up their knowledge of your product. - .text-3.leading-2.text-center.md_text-left Follow metrics of popular queries, no results or click position to better optimize your content. + .text-solstice.text-5.normal.pb-2.text-center.md_text-left + |Powerful Analytics with Algolia + .text-3.leading-2.text-center.md_text-left.pb-1 + |Follow your users' search behavior to get invaluable insights into + |what they are doing and to improve their experience - and to help + |them learn more about your product. + .text-3.leading-2.text-center.md_text-left + |Use metrics such as Popular Queries, No Results, and Click Position + |to better optimize your content. - .max-w-xl.m-auto - h2.text-solstice.text-5.normal.pb-2.text-center.mb-1 How it works - img(src="assets/docsearch-how-it-works.png", alt="how DocSearch works") - .max-w-lg.m-auto - .flex.flrw - .fln.w-100.md_w-33.px-2.p-2 - h3.pb-1.text-3.leading-2 We crawl your documentation pages - p.text-1.leading-2 We built a website crawler designed to index every section of your documentation. - p.text-1.leading-2 Just send us the URL of your documentation, and we’ll run the crawler every 24h so you’re always up-to-date. - .fln.w-100.md_w-33.px-2.p-2 - h3.pb-1.text-3.leading-2 We configure your search experience - p.text-1.leading-2 You don’t need to configure any settings or even have an Algolia account. - p.text-1.leading-2 We take care of all of this automatically to ensure the best documentation search experience. - .fln.w-100.md_w-33.px-2.p-2 - h3.pb-1.text-3.leading-2 You add the search autocomplete to your UI - p.text-1.leading-2 We’ll send you the script so you can integrate Algolia autocomplete to power your search. - p.text-1.leading-2 You will receive the same speed, relevance and best-in-class UX as our paying customers. + .max-w-xl.m-auto + h2.text-solstice.text-5.normal.pb-2.text-center.mb-1 + | How it works + img(src="assets/docsearch-how-it-works.png", alt="how DocSearch works") + .max-w-lg.m-auto + .flex.flrw + .fln.w-100.md_w-33.px-2.p-2 + h3.pb-1.text-3.leading-2 + |We crawl your documentation pages + p.text-1.leading-2 + |We built a website crawler designed to index every section of your + |documentation. + p.text-1.leading-2 + |Just send us the URL of your documentation, and we’ll run the + |crawler every 24h so you’re always up-to-date. + .fln.w-100.md_w-33.px-2.p-2 + h3.pb-1.text-3.leading-2 + |We configure your search experience + p.text-1.leading-2 + |You don’t need to configure any settings or even have an Algolia + |account. + p.text-1.leading-2 + |We take care of all of this automatically to ensure the best + |documentation search experience. + .fln.w-100.md_w-33.px-2.p-2 + h3.pb-1.text-3.leading-2 + |You add the search autocomplete to your UI + p.text-1.leading-2 + | We'll send you a script that integrates Algolia's autocomplete to + | power your search. + p.text-1.leading-2 + |You will receive the same speed, relevance, and best-in-class UX as + |our paying customers. .max-w-xl.m-auto.mt-3.px-1.pb-3 - .text-solstice.text-5.normal.pb-2.text-center Try it live - .pb-2.text-3.leading-2.text-center We helped integrate DocSearch into several open source projects. Have a look. + .text-solstice.text-5.normal.pb-2.text-center + |Try it live + .pb-2.text-3.leading-2.text-center + |We helped integrate DocSearch into several open source projects. Have + |a look. .flex.flrw .fln.w-100.sm_w-50.md_w-25.p-1.flex.flrnw a.c-card.custom-demo.fla.flex.flcnw.p-05(href='http://getbootstrap.com/docs/4.1/getting-started/introduction/') From 6330a469fc701c2749e256fb40eebdfecaa6d2fb Mon Sep 17 00:00:00 2001 From: Pixelastic Date: Wed, 22 Aug 2018 12:55:33 +0200 Subject: [PATCH 5/5] docs(styling): Update styling documentations to add better selectors --- docs/src/dropdown.md | 12 +++++++ docs/src/styling.md | 74 +++++++++++++++++++++++++++++--------------- 2 files changed, 61 insertions(+), 25 deletions(-) diff --git a/docs/src/dropdown.md b/docs/src/dropdown.md index b8758af6..cb58093d 100644 --- a/docs/src/dropdown.md +++ b/docs/src/dropdown.md @@ -30,3 +30,15 @@ created your config. }); ``` + +## Testing + +If you're eager to test DocSearch but don't have credentials of your own yet, +you can use the one we use on this own website: + +```javascript + docsearch({ + apiKey: '25626fae796133dc1e734c6bcaaeac3c', + indexName: 'docsearch', + }); +``` diff --git a/docs/src/styling.md b/docs/src/styling.md index f42bdfc8..da121d2a 100644 --- a/docs/src/styling.md +++ b/docs/src/styling.md @@ -3,46 +3,66 @@ layout: two-columns title: Styling DocSearch --- -DocSearch default colorscheme comes in a grey theme with blue highlight. +DocSearch default colorscheme comes in a grey theme with blue highlight. -![Default colorscheme](./assets/default-colorscheme.png) +![Default colorscheme][1] This theme works well with most websites, but we encourage you to style it to your own theme. This can be achieved by overriding the CSS classes used by the -default theme. +default theme. The following annotated example will help you style each part: ```css -/* Match title (eg. Bootstrap CDN) */ -.algolia-docsearch-suggestion--title { - font-weight: bold; - color: black; +/* Main dropdown wrapper */ +.algolia-autocomplete .ds-dropdown-menu { + width: 500px; } -/* Match description (eg. Bootstrap currently works...) */ -.algolia-docsearch-suggestion--text { - font-size: .8rem; - color: gray; -} - -/* Match category (eg. Downloads) */ -.algolia-docsearch-suggestion--subcategory-column { - color: gray; -} - -/* Match main category (eg. Getting Started) */ -.algolia-docsearch-suggestion--category-header { +/* Main category (eg. Getting Started) */ +.algolia-autocomplete .algolia-docsearch-suggestion--category-header { color: darkgray; border: 1px solid gray; } +/* Category (eg. Downloads) */ +.algolia-autocomplete .algolia-docsearch-suggestion--subcategory-column { + color: gray; +} + +/* Title (eg. Bootstrap CDN) */ +.algolia-autocomplete .algolia-docsearch-suggestion--title { + font-weight: bold; + color: black; +} + +/* Description description (eg. Bootstrap currently works...) */ +.algolia-autocomplete .algolia-docsearch-suggestion--text { + font-size: .8rem; + color: gray; +} + /* Highlighted text */ -.algolia-docsearch-suggestion--highlight { +.algolia-autocomplete .algolia-docsearch-suggestion--highlight { color: blue; } ``` +## Attribution + +We're happy to provide DocSearch free of charge for any documentation website, +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 +ok to 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 do, and how they could also have from 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. + ## Debugging If you want to inspect the dropdown markup with your browser tools, you should @@ -50,7 +70,7 @@ add `debug: true` to your `docsearch` call to prevent it from closing on inspection. ```javascript -docsearch({ +docsearch({ […], debug: true }); @@ -67,16 +87,20 @@ 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.** ## 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). +[SCSS source code][4]. `_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 used instead of the default one. + + +[1]: ./assets/default-colorscheme.png +[2]: https://www.algolia.com/pricing +[3]: ./crawler-overview.html +[4]: https://github.com/algolia/docsearch/tree/master/src/styles