Prettify the markdown
This commit is contained in:
Pixelastic
parent
1908d81854
commit
ae520266f9
16 changed files with 188 additions and 243 deletions
|
|
@ -4,10 +4,11 @@ module.exports = {
|
|||
{
|
||||
files: '*.md',
|
||||
options: {
|
||||
parser: 'markdown',
|
||||
printWidth: 80,
|
||||
proseWrap: 'always',
|
||||
singleQuote: true,
|
||||
trailingComma: 'es5',
|
||||
parser: 'markdown',
|
||||
},
|
||||
},
|
||||
],
|
||||
|
|
|
|||
|
|
@ -15,9 +15,9 @@ It will read all source files in `./src` and build the final static website in
|
|||
|
||||
### Local development
|
||||
|
||||
You can run a local copy of the documentation website by running `yarn run
|
||||
serve`. This is an alias for running `yarn run docs:serve` at the repository
|
||||
root.
|
||||
You can run a local copy of the documentation website by running
|
||||
`yarn run serve`. This is an alias for running `yarn run docs:serve` at the
|
||||
repository root.
|
||||
|
||||
This will build the website in `./dist` and expose it on `localhost`, along with
|
||||
live-reload.
|
||||
|
|
@ -43,8 +43,8 @@ second one adds a webserver with live-reload on top of the first one.
|
|||
All Markdown files situated in `./src` will be transformed into `.html` files in
|
||||
`./dist`. They will be wrapped into the layout defined in their front-matter.
|
||||
|
||||
All the headers will be converted to their respective `<hX>` tag, along with
|
||||
a unique `#id` to allow for easy anchoring.
|
||||
All the headers will be converted to their respective `<hX>` tag, along with a
|
||||
unique `#id` to allow for easy anchoring.
|
||||
|
||||
You can also use plain HTML inside those Markdown files if you need more
|
||||
advanced styling.
|
||||
|
|
@ -63,8 +63,7 @@ recursive cases, but should be enough for simple cases._
|
|||
|
||||
### CSS
|
||||
|
||||
CSS is processed through PostCSS. It expects an entry file in
|
||||
`./src/style.css`.
|
||||
CSS is processed through PostCSS. It expects an entry file in `./src/style.css`.
|
||||
|
||||
We are using `postcss-import`, allowing you to `@import` files from the
|
||||
`./src/_styles/` directory to better split your CSS code in logical chunks.
|
||||
|
|
@ -73,8 +72,8 @@ Most of the styling based on tailwind.css, with the config file behing
|
|||
`tailwind.config.js`. It contains default sizing and coloring to follow the
|
||||
Algolia brand guidelines.
|
||||
|
||||
The final CSS files is then compressed through PurgeCSS (to keep CSS
|
||||
classes that are actually used) and CleanCSS (to minify it).
|
||||
The final CSS files is then compressed through PurgeCSS (to keep CSS classes
|
||||
that are actually used) and CleanCSS (to minify it).
|
||||
|
||||
### JavaScript
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
#!/usr/bin/env sh
|
||||
set -e
|
||||
|
||||
# Check markdown styling (links, spacing, etc)
|
||||
remark \
|
||||
|
|
|
|||
|
|
@ -30,8 +30,8 @@ it to add your own behavior.
|
|||
|
||||
The method is called with three arguments:
|
||||
|
||||
- `input`, a reference to the search `input` element. It comes with the `.open()`,
|
||||
`.close()`, `.getVal()` and `.setVal()` methods.
|
||||
- `input`, a reference to the search `input` element. It comes with the
|
||||
`.open()`, `.close()`, `.getVal()` and `.setVal()` methods.
|
||||
|
||||
- `event`, the actual event triggering the selection. This can come from a click
|
||||
or a keyboard navigation.
|
||||
|
|
@ -63,9 +63,8 @@ docsearch({
|
|||
|
||||
## `transformData`
|
||||
|
||||
This method will be called on all suggestions before displaying them. It
|
||||
doesn't do anything by default, but we provide this hook for you to add your
|
||||
own logic.
|
||||
This method will be called on all suggestions before displaying them. It doesn't
|
||||
do anything by default, but we provide this hook for you to add your own logic.
|
||||
|
||||
```javascript
|
||||
docsearch({
|
||||
|
|
@ -100,25 +99,22 @@ 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].
|
||||
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].
|
||||
|
||||
For example, you might want to increase the number of results displayed in the dropdown.
|
||||
[`hitsPerPage` set the number of shown hits][4].
|
||||
For example, you might want to increase the number of results displayed in the
|
||||
dropdown. [`hitsPerPage` set the number of shown hits][4].
|
||||
|
||||
```javascript
|
||||
docsearch({
|
||||
algoliaOptions: {
|
||||
hitsPerPage: 10,
|
||||
// See https://www.algolia.com/doc/api-reference/api-parameters/
|
||||
}
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
[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/
|
||||
|
|
|
|||
|
|
@ -12,9 +12,7 @@ A DocSearch looks like this:
|
|||
```json
|
||||
{
|
||||
"index_name": "example",
|
||||
"start_urls": [
|
||||
"https://www.example.com/docs"
|
||||
],
|
||||
"start_urls": ["https://www.example.com/docs"],
|
||||
"selectors": {
|
||||
"lvl0": "#content header h1",
|
||||
"lvl1": "#content article h1",
|
||||
|
|
@ -23,7 +21,7 @@ A DocSearch looks like this:
|
|||
"lvl4": "#content section h5",
|
||||
"lvl5": "#content section h6",
|
||||
"text": "#content header p,#content section p,#content section ol"
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -46,13 +44,12 @@ like.
|
|||
|
||||
This array contains the list of URLs that will be used to start crawling your
|
||||
website. The crawler will recursively follow any links on those pages. It will
|
||||
not follow links that are on another domain and never follow links defined in `stop_urls`.
|
||||
not follow links that are on another domain and never follow links defined in
|
||||
`stop_urls`.
|
||||
|
||||
```json
|
||||
{
|
||||
"start_urls": [
|
||||
"https://www.example.com/docs"
|
||||
]
|
||||
"start_urls": ["https://www.example.com/docs"]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -68,14 +65,14 @@ The following example will make it clearer:
|
|||
```json
|
||||
{
|
||||
"start_urls": [
|
||||
{
|
||||
"url": "http://www.example.com/docs/(?P<lang>.*?)/(?P<version>.*?)/",
|
||||
"variables": {
|
||||
"lang": ["en", "fr"],
|
||||
"version": ["latest", "3.3", "3.2"]
|
||||
}
|
||||
}
|
||||
]
|
||||
{
|
||||
"url": "http://www.example.com/docs/(?P<lang>.*?)/(?P<version>.*?)/",
|
||||
"variables": {
|
||||
"lang": ["en", "fr"],
|
||||
"version": ["latest", "3.3", "3.2"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -99,18 +96,18 @@ docsearch({
|
|||
### Using custom tags
|
||||
|
||||
You can also apply custom tags to some pages without the need to use regular
|
||||
expressions. In that case, add the list of tags to the `tags` key. Note
|
||||
that those tags will be automatically added as facets in Algolia, allowing you
|
||||
to filter based on their values as well.
|
||||
expressions. In that case, add the list of tags to the `tags` key. Note that
|
||||
those tags will be automatically added as facets in Algolia, allowing you to
|
||||
filter based on their values as well.
|
||||
|
||||
```json
|
||||
{
|
||||
"start_urls": [
|
||||
{
|
||||
"url": "http://www.example.com/docs/concepts/",
|
||||
"tags": ['concepts', 'terminology']
|
||||
"tags": ["concepts", "terminology"]
|
||||
}
|
||||
]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -125,21 +122,21 @@ docsearch({
|
|||
|
||||
### Using Page Rank
|
||||
|
||||
To give more weight to some pages to boost their ranking in the
|
||||
results, you can attribute a custom `page_rank` to specific URLs. Pages with
|
||||
highest `page_rank` will be returned before pages with a lower `page_rank`. Note
|
||||
that you can pass any numeric value, including negative values.
|
||||
To give more weight to some pages to boost their ranking in the results, you can
|
||||
attribute a custom `page_rank` to specific URLs. Pages with highest `page_rank`
|
||||
will be returned before pages with a lower `page_rank`. Note that you can pass
|
||||
any numeric value, including negative values.
|
||||
|
||||
```json
|
||||
{
|
||||
"start_urls": [
|
||||
{
|
||||
"url": "http://www.example.com/docs/concepts/",
|
||||
"page_rank": 5,
|
||||
"page_rank": 5
|
||||
},
|
||||
{
|
||||
"url": "http://www.example.com/docs/contributors/",
|
||||
"page_rank": 1,
|
||||
"page_rank": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -206,7 +203,7 @@ record hierarchy. It can contains up to 6 levels (`lvl0`, `lvl1`, `lvl2`,
|
|||
`lvl3`, `lvl4`, `lvl5`) and `text`.
|
||||
|
||||
A default config would be to target the page `title` or `h1` as `lvl0`, the `h2`
|
||||
as `lvl1` and `h3` as `lvl2` and `p` as `text`, but this is highly dependent on
|
||||
as `lvl1` and `h3` as `lvl2` and `p` as `text`, but this is highly dependent on
|
||||
the markup.
|
||||
|
||||
The `text` key is mandatory, but we highly recommend setting also `lvl0`, `lvl1`
|
||||
|
|
@ -222,7 +219,7 @@ and `lvl2` to have a decent level of relevance.
|
|||
"lvl4": "#content section h5",
|
||||
"lvl5": "#content section h6",
|
||||
"text": "#content header p,#content section p,#content section ol"
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -233,7 +230,7 @@ Other special keys can be set, as documented below.
|
|||
{
|
||||
"selectors": {
|
||||
"lvl0": {
|
||||
"selector": "#content header h1",
|
||||
"selector": "#content header h1"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -242,8 +239,8 @@ Other special keys can be set, as documented below.
|
|||
### Using global selectors
|
||||
|
||||
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 relevant information is not part of the
|
||||
markup from top to bottom. This works well with semi-structured content, like a
|
||||
hierarchy of headers. This breaks when relevant information is not part of the
|
||||
same node flow. For example when the title is in a header or a sidebar.
|
||||
|
||||
For that reason, you can set a selector as global, meaning that it will match on
|
||||
|
|
@ -262,8 +259,8 @@ the whole page, and will be the same for all records extracted on this page.
|
|||
|
||||
### Setting a default value
|
||||
|
||||
If your selector might not match a valid element on the page, you can define
|
||||
a `default_value` to fallback to.
|
||||
If your selector might not match a valid element on the page, you can define a
|
||||
`default_value` to fallback to.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -359,9 +356,9 @@ Check the [Algolia documentation][2] for more information on the settings.
|
|||
### `min_indexed_level` _Optional_
|
||||
|
||||
The default value is `0`. By increasing it, you can chose to not index some
|
||||
records if they don't have enough `lvlX` matching. For example, with
|
||||
a `min_indexed_level: 2`, records that have at least `lvl0`, `lvl1` and
|
||||
`lvl2` matching something will be indexed.
|
||||
records if they don't have enough `lvlX` matching. For example, with a
|
||||
`min_indexed_level: 2`, records that have at least `lvl0`, `lvl1` and `lvl2`
|
||||
matching something will be indexed.
|
||||
|
||||
This is useful when your documentation has pages that share the same `lvl0` and
|
||||
`lvl1` for example. In that case, you don't want to index all the shared
|
||||
|
|
@ -377,11 +374,11 @@ records, but want to keep the content different across pages.
|
|||
|
||||
`nb_hits` automatically updated by DocSearch every time it runs your config. It
|
||||
is set to the number of records that were extracted and indexed. We check this
|
||||
key internally to keep track of any unintended spike or drop that could reveal
|
||||
a misconfiguration.
|
||||
key internally to keep track of any unintended spike or drop that could reveal a
|
||||
misconfiguration.
|
||||
|
||||
You don't have to touch it, we're documenting it here in case you were
|
||||
wondering what this was about.
|
||||
You don't have to touch it, we're documenting it here in case you were wondering
|
||||
what this was about.
|
||||
|
||||
### `only_content_level` _Optional_
|
||||
|
||||
|
|
@ -413,15 +410,12 @@ if it's a duplicate of another page, you should set this to `false`.
|
|||
This expects an array of CSS selectors. Any element matching one of those
|
||||
selectors will be removed from the page before any data is extracted from it.
|
||||
|
||||
This can be used to remove a table of content, a sidebar or a footer, to
|
||||
make other selectors easier to write.
|
||||
This can be used to remove a table of content, a sidebar or a footer, to make
|
||||
other selectors easier to write.
|
||||
|
||||
```json
|
||||
{
|
||||
"selectors_exclude": [
|
||||
".footer",
|
||||
"ul.deprecated"
|
||||
],
|
||||
"selectors_exclude": [".footer", "ul.deprecated"]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -438,10 +432,7 @@ Note that this is often used to avoid duplicate content, by adding
|
|||
|
||||
```json
|
||||
{
|
||||
"stop_urls": [
|
||||
"https://www.example.com/docs/index.html",
|
||||
"license.html"
|
||||
],
|
||||
"stop_urls": ["https://www.example.com/docs/index.html", "license.html"]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -458,9 +449,7 @@ following every link of your `starts_urls`.
|
|||
|
||||
```json
|
||||
{
|
||||
"sitemap_urls": [
|
||||
"http://www.example.com/docs/sitemap.xml"
|
||||
],
|
||||
"sitemap_urls": ["http://www.example.com/docs/sitemap.xml"]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -474,9 +463,7 @@ Set this to `true` if you want those other version to be crawled as well.
|
|||
|
||||
```json
|
||||
{
|
||||
"sitemap_urls": [
|
||||
"http://www.example.com/docs/sitemap.xml"
|
||||
],
|
||||
"sitemap_urls": ["http://www.example.com/docs/sitemap.xml"],
|
||||
"sitemap_alternate_links": true
|
||||
}
|
||||
```
|
||||
|
|
@ -495,8 +482,8 @@ crawled.
|
|||
## JavaScript rendering
|
||||
|
||||
By default DocSearch expect websites to have server-side rendering, meaning that
|
||||
HTML source is returned directly by the server. If your content is generated by the
|
||||
front-end, you have to tell DocSearch to emulate a browser through Selenium.
|
||||
HTML source is returned directly by the server. If your content is generated by
|
||||
the front-end, you have to tell DocSearch to emulate a browser through Selenium.
|
||||
|
||||
_As client-side crawling is way slower than server-side crawling, we highly
|
||||
encourage you to update your website to enable server-side rendering._
|
||||
|
|
@ -518,9 +505,9 @@ If your website is slow to load, you can use `js_wait` to tell DocSearch to wait
|
|||
a specific amount of time (in seconds) for the page to load before extracting
|
||||
its content.
|
||||
|
||||
Note that this option might have a large impact on the time required
|
||||
to crawl your website and we would encourage you to enable server-side rendering
|
||||
on your website instead.
|
||||
Note that this option might have a large impact on the time required to crawl
|
||||
your website and we would encourage you to enable server-side rendering on your
|
||||
website instead.
|
||||
|
||||
This option has no impact if `js_render` is set to `false`.
|
||||
|
||||
|
|
@ -547,5 +534,4 @@ DocSearch to index all your content.
|
|||
```
|
||||
|
||||
[1]: https://github.com/algolia/docsearch-configs/tree/master/configs
|
||||
|
||||
[2]: https://www.algolia.com/doc/api-reference/settings-api-parameters/
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ JSON configuration file that describe in more details how the crawling should
|
|||
behave. You can find the complete list of options in [our documentation][2].
|
||||
|
||||
We automatically run each config every 24h. This is done from our own
|
||||
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
|
||||
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
|
||||
|
|
@ -26,7 +26,5 @@ open source][3] 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
|
||||
|
|
|
|||
|
|
@ -36,8 +36,8 @@ 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',
|
||||
});
|
||||
docsearch({
|
||||
apiKey: '25626fae796133dc1e734c6bcaaeac3c',
|
||||
indexName: 'docsearch',
|
||||
});
|
||||
```
|
||||
|
|
|
|||
|
|
@ -3,9 +3,9 @@ layout: two-columns
|
|||
title: FAQ
|
||||
---
|
||||
|
||||
If you're not finding the answer to your question in the website, this
|
||||
page will help you. If you're still unsure, don't hesitate to send [your
|
||||
question to us][1] directly.
|
||||
If you're not finding the answer to your question in the website, this page will
|
||||
help you. If you're still unsure, don't hesitate to send [your question to
|
||||
us][1] directly.
|
||||
|
||||
### How often will you crawl my website?
|
||||
|
||||
|
|
@ -19,9 +19,9 @@ updated.
|
|||
|
||||
Nothing.
|
||||
|
||||
The DocSearch crawler is running on our own infra. It will read 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.
|
||||
The DocSearch crawler is running on our own infra. It will read 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.
|
||||
|
||||
### How much does it cost?
|
||||
|
||||
|
|
@ -29,8 +29,8 @@ Nothing.
|
|||
|
||||
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.
|
||||
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 free to [open your own Algolia
|
||||
account][3] and run DocSearch on your own without this limitation. In that case
|
||||
|
|
@ -39,9 +39,9 @@ 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. Which part of the
|
||||
page is defined in your custom config.
|
||||
The data we save in the index is the data we extract from your website 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
|
||||
dashboard, that will let you have more data about the anonymized searches that
|
||||
|
|
@ -60,10 +60,9 @@ more complete information in our [privacy policy][6].
|
|||
|
||||
### Can I use DocSearch on non-doc pages?
|
||||
|
||||
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:
|
||||
You need to use the searchableAttributes and attributesForFaceting.
|
||||
The free DocSearch we provide will crawl documentation pages. To use it on other
|
||||
parts of your website, you'll need to create your own Algolia account and
|
||||
either:
|
||||
|
||||
- Run the [DocSearch crawler][7] on your own
|
||||
- Use one of our other [framework integrations or API clients][8]
|
||||
|
|
@ -72,10 +71,9 @@ account and either:
|
|||
|
||||
Yes, but we do not recommend it.
|
||||
|
||||
Code samples are a great way for humans to understand how a specific pattern
|
||||
ap alpha
|
||||
/ method should be used. It often requires boilerplate code though, repeated
|
||||
across examples, which will add noise to the results.
|
||||
Code samples are a great way for humans to understand how a specific pattern ap
|
||||
alpha / 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
|
||||
|
|
@ -93,11 +91,7 @@ as those starting with `http://`.
|
|||
|
||||
```json
|
||||
{
|
||||
"stop_urls": [
|
||||
"/$",
|
||||
"/index.html$",
|
||||
"^http://"
|
||||
]
|
||||
"stop_urls": ["/$", "/index.html$", "^http://"]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -111,17 +105,10 @@ Feel free to ping `@docsearch` on GitHub in the issue as 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/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/
|
||||
|
|
|
|||
|
|
@ -3,29 +3,29 @@ layout: two-columns
|
|||
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 update your
|
||||
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 update your
|
||||
frontend.
|
||||
|
||||
<img src="./assets/docsearch-how-it-works.png" alt="How it works" class="mt-2"/>
|
||||
|
||||
### You apply
|
||||
|
||||
The first thing you'll need to do is to apply for DocSearch by filling the
|
||||
form on this page (make sure to double check that you qualify first). We are
|
||||
The first thing you'll need to do is to apply for DocSearch by filling the form
|
||||
on this page (make sure to double check that you qualify first). We are
|
||||
receiving a lot of requests, so this form makes sure we won't be forgetting
|
||||
anyone.
|
||||
|
||||
We guarantee that we will answer to every request, but we receive a lot
|
||||
of applications, so please give us a couple of days to get back to you :)
|
||||
We guarantee that we will answer to every request, but we receive a lot of
|
||||
applications, so please give us a couple of days to get back to you :)
|
||||
|
||||
### We create a configuration
|
||||
|
||||
Once we receive your application, 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, 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 900+ configs we
|
||||
already created, we're able to automate most of it. Once done, we'll run a first
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ again, on the page hierarchy, as extracted from the `selectors`.
|
|||
|
||||
The default strategy is to first look at the closest header of the matching
|
||||
text. For example, a paragraph under `Settings / API / verySpecificMethod()`,
|
||||
will be ranked higher than one under `Settings / API`. The idea here is that if
|
||||
will be ranked higher than one under `Settings / API`. The idea here is that if
|
||||
you have a match under a deep hierarchy, chances are that this match is specific
|
||||
and might be more interesting that something found in a broad topic.
|
||||
|
||||
|
|
@ -51,10 +51,11 @@ hierarchy. In that case, we use the paragraph position. The first paragraph of
|
|||
the page will be ranked higher than the last one.
|
||||
|
||||
You also have a way to boost some pages directly in your config by using the
|
||||
`page_rank` option. This accepts a numeric value, and all pages with
|
||||
a `page_rank` of 5 will be returned before pages with a `page_rank` of 1.
|
||||
`page_rank` option. This accepts a numeric value, and all pages with a
|
||||
`page_rank` of 5 will be returned before pages with a `page_rank` of 1.
|
||||
|
||||
You could even overwrite the default `customRanking` used by the index by using
|
||||
the `custom_settings` option of your config.
|
||||
|
||||
[1]: https://www.algolia.com/doc/guides/ranking/ranking-formula/#tie-breaking-approach
|
||||
[1]:
|
||||
https://www.algolia.com/doc/guides/ranking/ranking-formula/#tie-breaking-approach
|
||||
|
|
|
|||
|
|
@ -17,17 +17,10 @@ If you're a maintaining such a tool and would like to get added to the list, get
|
|||
[in touch with us][8]
|
||||
|
||||
[1]: https://docusaurus.io/
|
||||
|
||||
[2]: https://docusaurus.io/docs/en/search#docsNav
|
||||
|
||||
[3]: https://vuepress.vuejs.org/
|
||||
|
||||
[4]: https://vuepress.vuejs.org/default-theme-config/#algolia-search
|
||||
|
||||
[5]: https://docs.gitbook.com/
|
||||
|
||||
[6]: http://pkgdown.r-lib.org/index.html
|
||||
|
||||
[7]: http://pkgdown.r-lib.org/articles/pkgdown.html#search
|
||||
|
||||
[8]: mailto:docsearch@algolia.com
|
||||
|
|
|
|||
|
|
@ -3,36 +3,34 @@ layout: two-columns
|
|||
title: Run your own
|
||||
---
|
||||
|
||||
The version of DocSearch we provide for free is one hosted on our own
|
||||
servers, running every 24 hours. To update your results
|
||||
more often than that, or to index content sitting behind a
|
||||
firewall, you might want to run the crawler yourself.
|
||||
The version of DocSearch we provide for free is one hosted on our own servers,
|
||||
running every 24 hours. To update your results more often than that, or to index
|
||||
content sitting behind a firewall, you might want to run the crawler yourself.
|
||||
|
||||
The code of DocSearch is open source, and we packaged it as a Docker
|
||||
image to make this even easier for you to use.
|
||||
The code of DocSearch is open source, and we packaged it as a Docker image to
|
||||
make this even easier for you to use.
|
||||
|
||||
## Installation
|
||||
|
||||
Start by cloning [the repository][1] and then running `./docsearch
|
||||
docker:build` to create the local image.
|
||||
Start by cloning [the repository][1] and then running `./docsearch docker:build`
|
||||
to create the local image.
|
||||
|
||||
Even if not recommended, you can run DocSearch directly from you host.
|
||||
For that, you'll need to have `python` and `pip` installed, and then
|
||||
run `pip install --user -r requirements.txt`.
|
||||
Even if not recommended, you can run DocSearch directly from you host. For that,
|
||||
you'll need to have `python` and `pip` installed, and then run
|
||||
`pip install --user -r requirements.txt`.
|
||||
|
||||
## Configuration
|
||||
|
||||
You'll need to set your Algolia application ID and admin API key as
|
||||
environment variables. If you don't have an Algolia account, you
|
||||
should [create one][2].
|
||||
You'll need to set your Algolia application ID and admin API key as environment
|
||||
variables. If you don't have an Algolia account, you should [create one][2].
|
||||
|
||||
- `APPLICATION_ID` should be set to your Application ID
|
||||
|
||||
- `API_KEY` should be set to your API Key. Make sure to use an API key
|
||||
with **write** access to your index.
|
||||
- `API_KEY` should be set to your API Key. Make sure to use an API key with
|
||||
**write** access to your index.
|
||||
|
||||
For convenience, you can create a `.env` file in the repository root
|
||||
with the following format and DocSearch will use those values.
|
||||
For convenience, you can create a `.env` file in the repository root with the
|
||||
following format and DocSearch will use those values.
|
||||
|
||||
```sh
|
||||
APPLICATION_ID=YOUR_APP_ID
|
||||
|
|
@ -41,9 +39,8 @@ API_KEY=YOUR_API_KEY
|
|||
|
||||
## Creating a new config
|
||||
|
||||
To create your config, run `./docsearch bootstrap`. A prompt will ask
|
||||
you for a some information and will then output a JSON config you can
|
||||
use as a base.
|
||||
To create your config, run `./docsearch bootstrap`. A prompt will ask you for a
|
||||
some information and will then output a JSON config you can use as a base.
|
||||
|
||||
```sh
|
||||
$ ./docsearch bootstrap
|
||||
|
|
@ -73,42 +70,41 @@ index_name is example [enter to confirm]: <Enter>
|
|||
=================
|
||||
```
|
||||
|
||||
Copy-paste the content into a filename `example.json`, we'll use it
|
||||
later to start the crawling. You can find the complete list of
|
||||
available options in [our documentation][3], or browse the [list of
|
||||
live configs][4].
|
||||
Copy-paste the content into a filename `example.json`, we'll use it later to
|
||||
start the crawling. You can find the complete list of available options in [our
|
||||
documentation][3], or browse the [list of live configs][4].
|
||||
|
||||
## Running your config
|
||||
|
||||
Now that you have your environment variables set, you can run the
|
||||
crawler according to your config.
|
||||
Now that you have your environment variables set, you can run the crawler
|
||||
according to your config.
|
||||
|
||||
```sh
|
||||
$ ./docsearch docker:run /path/to/your/config.json
|
||||
```
|
||||
|
||||
This will crawl all pages, extract content from them and then push it
|
||||
to Algolia.
|
||||
This will crawl all pages, extract content from them and then push it to
|
||||
Algolia.
|
||||
|
||||
## Testing your results
|
||||
|
||||
You can test your results by running `./docsearch playground`. This
|
||||
will open a web page with a search input where you can do live tests
|
||||
against the indexed results.
|
||||
You can test your results by running `./docsearch playground`. This will open a
|
||||
web page with a search input where you can do live tests against the indexed
|
||||
results.
|
||||
|
||||
<img src="./assets/playground.png" alt="Playground" class="mt-2"/>
|
||||
|
||||
_Note that if the command fails (it can happen on non-Mac machines),
|
||||
you can get the same result by running a live server in the `./playground` subdirectory.\`_
|
||||
_Note that if the command fails (it can happen on non-Mac machines), you can get
|
||||
the same result by running a live server in the `./playground` subdirectory.\`_
|
||||
|
||||
## Integration
|
||||
|
||||
Once you're satisfied with your config, you can integrate the dropdown
|
||||
menu in your website by following the [instructions here][5].
|
||||
Once you're satisfied with your config, you can integrate the dropdown menu in
|
||||
your website by following the [instructions here][5].
|
||||
|
||||
The difference is that you'll also have to add the `appId` key to your
|
||||
`docsearch()` instance. Also don't forget to use a **search** API key
|
||||
here (in other words, not the **write** API key you used for the crawling).
|
||||
`docsearch()` instance. Also don't forget to use a **search** API key here (in
|
||||
other words, not the **write** API key you used for the crawling).
|
||||
|
||||
```javascript
|
||||
docsearch({
|
||||
|
|
@ -120,18 +116,14 @@ docsearch({
|
|||
|
||||
## Help
|
||||
|
||||
You can run `./docsearch` without any argument to see the list of all
|
||||
available commands.
|
||||
You can run `./docsearch` without any argument to see the list of all available
|
||||
commands.
|
||||
|
||||
Note that we use this command-line 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/pricing#community
|
||||
|
||||
[3]: ./config-file.html
|
||||
|
||||
[4]: https://github.com/algolia/docsearch-configs/tree/master/configs
|
||||
|
||||
[5]: ./dropdown.html
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ The following annotated example will help you style each part:
|
|||
|
||||
/* Description description (eg. Bootstrap currently works...) */
|
||||
.algolia-autocomplete .algolia-docsearch-suggestion--text {
|
||||
font-size: .8rem;
|
||||
font-size: 0.8rem;
|
||||
color: gray;
|
||||
}
|
||||
|
||||
|
|
@ -65,9 +65,8 @@ yourself][3], you don't have to keep the logo.
|
|||
|
||||
## Debugging
|
||||
|
||||
To inspect the dropdown markup with your browser tools, you should
|
||||
add `debug: true` to your `docsearch` call to prevent it from closing on
|
||||
inspection.
|
||||
To inspect the dropdown markup with your browser tools, you should add
|
||||
`debug: true` to your `docsearch` call to prevent it from closing on inspection.
|
||||
|
||||
```javascript
|
||||
docsearch({
|
||||
|
|
@ -78,9 +77,9 @@ docsearch({
|
|||
|
||||
## Other considerations
|
||||
|
||||
Selected suggestion are wrapped in a `.ds-cursor` class. This means
|
||||
that you can use `.ds-cursor .algolia-docsearch-suggestion--content` to style
|
||||
the selected suggestion for example.
|
||||
Selected suggestion are wrapped in a `.ds-cursor` class. This means that you can
|
||||
use `.ds-cursor .algolia-docsearch-suggestion--content` to style 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 used on larger screens. You can
|
||||
|
|
@ -89,18 +88,15 @@ other display.
|
|||
|
||||
## Advanced styling
|
||||
|
||||
To more heavily style the results, feel free to have a look at the
|
||||
[SCSS source code][4].
|
||||
`_variables.scss` contains all the default theming, sizing and breakpoints.
|
||||
To more heavily style the results, 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 `yarn
|
||||
run build:css`. The resulting file will be generated in `./dist/cdn`, and should
|
||||
be used instead of the default one.
|
||||
You can generate your own CSS file by cloning the repository 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
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ title: Tips for a good search
|
|||
---
|
||||
|
||||
DocSearch can work with almost any website, but we found that some site
|
||||
structure yield more relevant result or faster indexing time. In this page
|
||||
we'll share some tips on how you can make the most out of DocSearch.
|
||||
structure yield more relevant result or faster indexing time. In this page we'll
|
||||
share some tips on how you can make the most out of DocSearch.
|
||||
|
||||
### Use a `sitemap.xml`
|
||||
|
||||
|
|
@ -35,9 +35,9 @@ 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.
|
||||
|
||||
_Note that you don't have to use `<hX>` tags and can use `<span
|
||||
class="title-X">` for example instead. Your crawling configuration file will
|
||||
need to mirror those changes, though._
|
||||
_Note that you don't have to use `<hX>` tags and can use
|
||||
`<span class="title-X">` for example instead. Your crawling configuration file
|
||||
will need to mirror those changes, though._
|
||||
|
||||
### Set a unique class to the element holding the content
|
||||
|
||||
|
|
@ -46,26 +46,25 @@ you add a custom `class` to the HTML element wrapping all your textual content.
|
|||
This will help narrow selectors to the relevant content.
|
||||
|
||||
Having such a unique identifier will make your configuration more robust as it
|
||||
will make sure all indexed content is relevant content. We found that
|
||||
this is the most reliable way to exclude headers, sidebars and footers content
|
||||
that are not relevant to the search.
|
||||
will make sure all indexed content is relevant content. We found that this is
|
||||
the most reliable way to exclude headers, sidebars and footers content that are
|
||||
not relevant to the search.
|
||||
|
||||
### Add anchors to headings
|
||||
|
||||
When using headings (as mentioned above), you should also try to add a custom
|
||||
anchor to each of them. Anchors are HTML attributes (`name` or `id`)
|
||||
added to headers that will allow the browser to directly scroll to the right
|
||||
position in the page when clicking a link with a `#` in it.
|
||||
anchor to each of them. Anchors are HTML attributes (`name` or `id`) added to
|
||||
headers that will allow the browser to directly scroll to the right position in
|
||||
the page when clicking a link with a `#` in it.
|
||||
|
||||
DocSearch will honor such anchors and automatically bring your users to the
|
||||
anchor closest to the search result they selected.
|
||||
|
||||
### Marking the active page(s) in the navigation
|
||||
|
||||
If you're using a multi-level navigation, we recommend that you mark
|
||||
each active level with a custom CSS class. This will make it easier for
|
||||
DocSearch to know _where_ the current page fits in the website
|
||||
hierarchy.
|
||||
If you're using a multi-level navigation, we recommend that you mark each active
|
||||
level with a custom CSS class. This will make it easier for DocSearch to know
|
||||
_where_ the current page fits in the website hierarchy.
|
||||
|
||||
For example, if your `troubleshooting.html` page is located under the
|
||||
`Installation` menu in your sidebar, we recommend that you add a custom CSS
|
||||
|
|
|
|||
|
|
@ -5,27 +5,26 @@ title: What is DocSearch?
|
|||
|
||||
DocSearch is born out of the need to scratch our own itch. As developers, we
|
||||
spent a lot of time reading documentation, and it can be hard to find relevant
|
||||
information in large documentations. We're not blaming anyone here; building
|
||||
a good search is a challenge.
|
||||
information in large documentations. We're not blaming anyone here; building a
|
||||
good search is a challenge.
|
||||
|
||||
It happens that we are a search company and we actually have a lot of
|
||||
experience building search interfaces. We wanted to use those skills to help
|
||||
others. That's why we created a way to automatically extract content from tech
|
||||
documentation and make it available to everyone from the first keystroke.
|
||||
It happens that we are a search company and we actually have a lot of experience
|
||||
building search interfaces. We wanted to use those skills to help others. That's
|
||||
why we created a way to automatically extract content from tech documentation
|
||||
and make it available to everyone from the first keystroke.
|
||||
|
||||
DocSearch itself is made of a crawler and a frontend library. We run the
|
||||
crawler on our end every 24h to extract content from your website and push it to
|
||||
an Algolia index. You'll then have to add the frontend library to your website
|
||||
to redirect all the search requests to this index.
|
||||
DocSearch itself is made of a crawler and a frontend library. We run the crawler
|
||||
on our end every 24h to extract content from your website and push it to an
|
||||
Algolia index. You'll then have to add the frontend library to your website to
|
||||
redirect all the search requests to this index.
|
||||
|
||||
DocSearch is entirely free and automated. The one thing we'll need from
|
||||
you is to read [our checklist][2] and apply! After that, we'll share with you
|
||||
the JavaScript snippet needed to add DocSearch to your website. We ask that
|
||||
you keep the "powered by Algolia" link displayed.
|
||||
DocSearch is entirely free and automated. The one thing we'll need from you is
|
||||
to read [our checklist][2] and apply! After that, we'll share with you the
|
||||
JavaScript snippet needed to add DocSearch to your website. We ask that you keep
|
||||
the "powered by Algolia" link displayed.
|
||||
|
||||
DocSearch is [one of our ways][1] to give back to the open source community for
|
||||
everything it did for us already.
|
||||
|
||||
[1]: https://opencollective.com/algolia
|
||||
|
||||
[2]: ./who-can-apply.html
|
||||
|
|
|
|||
|
|
@ -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 technical documentations.
|
||||
We hope you understand.
|
||||
requests we received everyday, we had to focus on technical documentations. We
|
||||
hope you understand.
|
||||
|
||||
### The checklist
|
||||
|
||||
|
|
@ -48,10 +48,9 @@ following criteria:
|
|||
- 🙂 If you're using one of our [official integrations][2], creating your config
|
||||
will be much faster for us.
|
||||
|
||||
- ☹️ 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
|
||||
- ☹️ 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 if you can.
|
||||
|
||||
[1]: ./apply.html
|
||||
|
||||
[2]: ./integrations.html
|
||||
|
|
|
|||
Loading…
Reference in a new issue