nikon/docsearch
1
0
Fork 0
Code Activity Actions

Merge branch 'master' into doc/update_content

Browse source
This commit is contained in:
Sylvain Pace 2018-08-22 16:54:38 +02:00
commit 6ea62426a6
6 changed files with 168 additions and 87 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
docs/src/_layouts/homepage.pug
View file

@ -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/')

12
docs/src/dropdown.md
View file

@ -30,3 +30,15 @@ created your config.
});
</script>
```
## 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',
});
```

44
docs/src/faq.md
View file

@ -27,20 +27,20 @@ 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.
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?
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,28 +48,30 @@ 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
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?
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:
- 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. 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
@ -107,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/

13
docs/src/how-does-it-work.md
View file

@ -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.
<img src="./assets/docsearch-how-it-works.png" alt="How it works" class="mt-2"/>
@ -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

2
docs/src/run-your-own.md
View file

@ -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

88
docs/src/styling.md
View file

@ -3,46 +3,66 @@ 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)
![Default colorscheme][1]
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
default theme.
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:
```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
});
@ -58,25 +78,29 @@ 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.
## 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.
[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