Doc: Remove warnings of textlint (#804)
* doc: add faq point * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * fix one write-good * Update docs/README.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/README.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/README.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/README.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/src/what-is-docsearch.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/src/tips.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/src/what-is-docsearch.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/src/what-is-docsearch.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/src/what-is-docsearch.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/README.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Apply suggestions from code review Co-Authored-By: Haroen Viaene <hello@haroen.me> * Apply suggestions from code review Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/src/faq.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Update docs/src/how-does-it-work.md Co-Authored-By: Haroen Viaene <hello@haroen.me> * Apply suggestions from code review Co-Authored-By: Haroen Viaene <hello@haroen.me> * Apply suggestions from code review Co-Authored-By: Haroen Viaene <hello@haroen.me> * Apply suggestions from code review Co-Authored-By: Haroen Viaene <hello@haroen.me>
This commit is contained in:
Sylvain Pace
GitHub
parent
3f1b653574
commit
3b2d3a3dd6
15 changed files with 131 additions and 133 deletions
|
|
@ -41,15 +41,15 @@ that the website is **not** hosted on Netlify, but on GitHub Pages (more on that
|
|||
later).
|
||||
|
||||
The script compares the date of the last commit in `./docs` with the date of the
|
||||
last deploy. If no new commits were added, it will stop. Otherwise, it will
|
||||
last deploy. If there are no new commits, it will stop. Otherwise, it will
|
||||
continue and build the website.
|
||||
|
||||
To make this comparison, both this script and the manual deploy script add a
|
||||
`last_update` file to the `./dist` folder containing the timestamp of the last
|
||||
deploy. This file is then used to see if changes are present and should be
|
||||
deployed.
|
||||
deploy. This file is then used to see if changes are present if it should deploy
|
||||
anything.
|
||||
|
||||
Once the build is complete, the `./dist` folder is committed to the `gh-pages`
|
||||
Once the build is complete, it commits the `./dist` folder to the `gh-pages`
|
||||
branch and pushed to GitHub. This part requires some non-trivial `git` and `ssh`
|
||||
configuration commands to push data from Netlify to GitHub pages on our behalf
|
||||
(check `./scripts/netlify-master` for more details).
|
||||
|
|
@ -58,20 +58,20 @@ configuration commands to push data from Netlify to GitHub pages on our behalf
|
|||
|
||||
Any new Pull Request to the documentation will trigger a deploy preview build.
|
||||
|
||||
Netlify is configured to run `./scripts/netlify-deploy-preview` on each new PR
|
||||
(check `netlify.toml` for details).
|
||||
Netlify runs `./scripts/netlify-deploy-preview` on each new PR (check
|
||||
`netlify.toml` for details).
|
||||
|
||||
This script will first check if changes were made to the `./docs` subfolder in
|
||||
the PR. If no change were made, the preview will not be generated (this will
|
||||
make processing time faster).
|
||||
This script will first check if the PR changes anything to the `./docs` subfolder.
|
||||
If PR doesn't change anything, it will not generate the preview (this will make
|
||||
processing time faster).
|
||||
|
||||
Whenever the preview is ready, a message from Algobot will be added to the PR,
|
||||
along with the link to the preview. This is configured in Netlify UI in _Build
|
||||
and Deploy > Deploy notifications > Comment on GitHub pull request when deploy
|
||||
succeeds_. It uses a GitHub token from Algobot to post on its behalf. To
|
||||
generate such a token, login to Netlify with Algobot and pretend to create such
|
||||
a notification on any project, generate a token, and then copy-paste it in the
|
||||
real DocSearch account in Netlify.
|
||||
Whenever the preview is ready, Algobot adds a message to the PR, along with the
|
||||
link to the preview. This is a Netlify UI setting in _Build and Deploy > Deploy
|
||||
notifications > Comment on GitHub pull request when deploy succeeds_. It uses a
|
||||
GitHub token from Algobot to post on its behalf. To generate such a token, login
|
||||
to Netlify with Algobot and pretend to create such a notification on any
|
||||
project, generate a token, and then copy-paste it in the real DocSearch account
|
||||
in Netlify.
|
||||
|
||||
## Internals
|
||||
|
||||
|
|
@ -83,11 +83,11 @@ second one adds a webserver with live-reload on top of the first one.
|
|||
|
||||
### HTML
|
||||
|
||||
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.
|
||||
It transforms every Markdown files situated in `./src` into `.html` files in
|
||||
`./dist`. It wrapps them 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.
|
||||
It converts every header to their respective `<hX>` tag, along with a unique
|
||||
`#id` to allow for easy anchoring.
|
||||
|
||||
You can use plain HTML inside those Markdown files if you need more advanced
|
||||
styling. The custom `{my-class}` syntax is also possible if to add CSS classes
|
||||
|
|
@ -109,10 +109,10 @@ This is my paragraph. {p-2}
|
|||
|
||||
### Layouts
|
||||
|
||||
All layouts are saved in the `./src/_layouts` folder.
|
||||
Layouts are in the `./src/_layouts` folder.
|
||||
|
||||
All config options defined into `config.json` are passed to the layouts and can
|
||||
be used there.
|
||||
It passes every config options defined into `config.json` to the layouts and are
|
||||
available there.
|
||||
|
||||
You can also use mixins or include other files from the layouts.
|
||||
|
||||
|
|
@ -121,7 +121,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`.
|
||||
PostCSS processes CSS. 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.
|
||||
|
|
@ -135,8 +135,8 @@ that are actually used) and CleanCSS (to minify it).
|
|||
|
||||
### JavaScript
|
||||
|
||||
JavaScript code is processed through Babel. It will compile all files situated
|
||||
in `./src/js`.
|
||||
Babel processes JavaScript code. It will compile all files situated in
|
||||
`./src/js`.
|
||||
|
||||
_Note that it compiles JS, and does not bundle it. We might add Webpack/Parcel
|
||||
support later._
|
||||
|
|
@ -149,8 +149,8 @@ automatically copied to the `./dist` folder with the same folder structure:
|
|||
|
||||
### Placeholders
|
||||
|
||||
Values defined in the `placeholders` key of the `config.json` file can be used
|
||||
in JavaScript and Markdown files by using the `{{key}}` syntax.
|
||||
You can use the values defined in the `placeholders` key of the `config.json` in
|
||||
JavaScript and Markdown files by using the `{{key}}` syntax.
|
||||
|
||||
For example if you have:
|
||||
|
||||
|
|
@ -163,19 +163,19 @@ For example if you have:
|
|||
}
|
||||
```
|
||||
|
||||
Every occurrence of `{{projectVersion}}` in any `.md` or `.js` file will be
|
||||
replaced with `1.4.2`.
|
||||
It replaces every occurrence of `{{projectVersion}}` in any `.md` or `.js` file
|
||||
with `1.4.2`.
|
||||
|
||||
### Sidebar
|
||||
|
||||
The left sidebar of the documentation is generated based on the `sidebar` key of
|
||||
It generates the left sidebar of the documentation based on the `sidebar` key of
|
||||
the `config.json`. The key should contain an array where each key is a part of
|
||||
the sidebar, with a `title` and a list of `pages`. Each of those pages in turn
|
||||
is an object with a `title` and `url` value.
|
||||
|
||||
The layout will then automatically create all the links and color the active
|
||||
page. Subsections inside the current page will also be added for every `h2`
|
||||
element extracted from the markup of the current page.
|
||||
page. It adds subsections inside the current page for every `h2` element
|
||||
extracted from the markup of the current page.
|
||||
|
||||
### Redirects
|
||||
|
||||
|
|
@ -184,5 +184,4 @@ a `from` and a `to` key. For each `from`, it will create a plain HTML page at
|
|||
this location, that will redirect anyone visiting it to the page defined in
|
||||
`to`.
|
||||
|
||||
_Note that both those links must be defined as relative to the `site.url`
|
||||
value._
|
||||
_Note You must define the links as relative to the `site.url` value._
|
||||
|
|
|
|||
|
|
@ -66,8 +66,8 @@ matching links from `stop_urls`.
|
|||
|
||||
### `selectors_key`, tailor your selectors
|
||||
|
||||
You can define finer sets of selectors depending on the URL. This is done thanks
|
||||
to the parameter `selectors_key` from your `start_urls`.
|
||||
You can define finer sets of selectors depending on the URL. You need to use the
|
||||
parameter `selectors_key` from your `start_urls`.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -509,8 +509,8 @@ Note that this is often used to avoid duplicate content, by adding
|
|||
|
||||
The default value is `0`. By increasing it, you can choose not to index some
|
||||
records if they don't have enough `lvlX` matching. For example, with a
|
||||
`min_indexed_level: 2`, the scraper only indexes temporary records having at
|
||||
least `lvl0`, `lvl1` and `lvl2` set. You can [find out more details about this
|
||||
`min_indexed_level: 2`, the scraper indexes temporary records having at least
|
||||
`lvl0`, `lvl1` and `lvl2` set. You can [find out more details about this
|
||||
strategy in this section][5].
|
||||
|
||||
This is useful when your documentation has pages that share the same `lvl0` and
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ title: CSS config helper
|
|||
---
|
||||
|
||||
To speed up the process of defining which selectors could make a good candidate,
|
||||
we created a custom CSS file to help us see what tags are used at a glance.
|
||||
we created a custom CSS file to help us to see what tags it needs.
|
||||
|
||||
![Jest documentation after][3]
|
||||
|
||||
|
|
|
|||
|
|
@ -3,12 +3,11 @@ layout: two-columns
|
|||
title: Dropdown Search-UI
|
||||
---
|
||||
|
||||
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 our
|
||||
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, 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 our DocSearch library
|
||||
into your website as per the following example. You will receive your `apiKey`
|
||||
and `indexName` credentials as soon as we've created your config.
|
||||
|
||||
```html
|
||||
<!-- Before the closing </head> -->
|
||||
|
|
@ -35,7 +34,8 @@ config.
|
|||
</script>
|
||||
```
|
||||
|
||||
This snippet needs to be integrated to every page that integrates the dropdown UI
|
||||
You need to integrate this snippet into every page that integrates the
|
||||
dropdown UI
|
||||
|
||||
## Testing
|
||||
|
||||
|
|
|
|||
|
|
@ -12,8 +12,7 @@ us][1] directly.
|
|||
Every day.
|
||||
|
||||
The exact time of day might vary each day, but we'll crawl your website at most
|
||||
every 24 hours. We will also trigger a manual crawl every time your
|
||||
configurations is updated.
|
||||
every 24 hours.
|
||||
|
||||
## What do I need to install on my side?
|
||||
|
||||
|
|
@ -40,15 +39,13 @@ account (free accounts can hold as much as 10k records).
|
|||
|
||||
## What data are you collecting?
|
||||
|
||||
We only save the data we extract from your website markup, which we put in a
|
||||
custom JSON format instead of HTML. This is the only data we put in the Algolia
|
||||
DocSearch index. This data is based on the selectors defined in your config
|
||||
file,
|
||||
We save the data we extract from your website markup, which we put in a custom
|
||||
JSON format instead of HTML. This is the data we put in the Algolia DocSearch
|
||||
index. The selectors in your config define the data on file,
|
||||
|
||||
As the website owner, we also give you access to the Algolia Analytics
|
||||
dashboard. This will let you have more data about the anonymized searches that
|
||||
were done on your website. You'll see the most searched terms, or those with no
|
||||
results.
|
||||
dashboard. This will let you have more data about the anonymized searches in
|
||||
your website. You'll see the most searched terms, or those with no results.
|
||||
|
||||
With such Analytics, you will understand better what your users are doing.
|
||||
|
||||
|
|
@ -56,7 +53,7 @@ _If you don't have Analytics access, [send us an email][1] and we'll enable it._
|
|||
|
||||
## Where is my data hosted?
|
||||
|
||||
All DocSearch data is hosted on Algolia's servers, with replications around the
|
||||
We host the DocSearch data in Algolia's servers, with replications around the
|
||||
globe. You can find more details about the actual [server specs here][4], and
|
||||
more complete information in our [privacy policy][5].
|
||||
|
||||
|
|
@ -73,9 +70,9 @@ 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 people use a specific
|
||||
method. 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
|
||||
|
|
@ -87,7 +84,7 @@ This can happen when you have more than one URL 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
|
||||
You can fix the `stop_urls` to all the patterns you want to exclude. The
|
||||
following example will exclude all URLs ending with `/` or `index.html` as well
|
||||
as those starting with `http://`.
|
||||
|
||||
|
|
@ -102,10 +99,9 @@ as those starting with `http://`.
|
|||
Changing your setting from the dashboard might be something you want to do for
|
||||
some reasons .
|
||||
|
||||
Please be aware that your DocSearch settings are set at every time the crawler
|
||||
is successful. These settings will be overridden at the next crawl. We **do not
|
||||
recommend to edit anything from the dashboard**. These changes have be made from
|
||||
the JSON configuration itself.
|
||||
Every successful crawl sets the DocSearch settings. These settings will be
|
||||
overridden at the next crawl. We **do not recommend to edit anything from the
|
||||
dashboard**. These changes come from the JSON configuration itself.
|
||||
|
||||
You can use the [custom_settings parameter][8] in such purpose.
|
||||
|
||||
|
|
@ -118,29 +114,34 @@ encourage you to file an issue in their repository explaining how DocSearch
|
|||
could help. Feel free to [send us an email][1] as well, and we'll provide all
|
||||
the help we can.
|
||||
|
||||
## How many records are created by DocSearch?
|
||||
## How many records does the DocSearch crawl create?
|
||||
|
||||
The [property `nb_hits`][9] in your configuration keeps track of the number of
|
||||
records that were extracted and indexed by the last DocSearch run. It is updated
|
||||
automatically at each run.
|
||||
records the crawl has extracted and indexed by the last DocSearch run. It
|
||||
updates this number automatically.
|
||||
|
||||
The DocSearch scraper follows [the recommended atomic-reindexing strategy][10].
|
||||
It creates a brand new temporary index to populate the data scraped from your
|
||||
website. Once the crawl is successfully achieved, this temporary index overwites
|
||||
the old index defined in your configuration with the key `index_name`.
|
||||
website. When successful, the crawl overwites the old index defined in your
|
||||
configuration with the key `index_name`.
|
||||
|
||||
## Why aren't my pages indexed?
|
||||
|
||||
We are scraping your website according to your configuration. It might happen
|
||||
that some pages are missing from the search. There are several possible
|
||||
reasons for that:
|
||||
that some pages are missing from the search. The possible reasons for that are:
|
||||
|
||||
- Makes sure you are not filtering on the search by wrongly using
|
||||
`facetFilters`. [See here for more details][11].
|
||||
- Make sure the page missing is referenced from an other indexed page thanks to
|
||||
a hyperlink tag `<a/>`.
|
||||
- Make sure that an other indexed page references the page missing thanks
|
||||
to a hyperlink tag `<a/>`.
|
||||
- Make sure you are [providing a compliant sitemap from the configuration][12]
|
||||
and that this page is referenced by it.
|
||||
and that it references the page.
|
||||
|
||||
## Can I know when the next crawl will happen?
|
||||
|
||||
No you can't. You should be aware that we made every crawls in a day. The
|
||||
position of your crawl in the queue is the inverse of the lexicographic order of
|
||||
your `index_name` amongs the whole list of featured website.
|
||||
|
||||
If none of the previous points help, you can contact our support.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ This payload will be the only data extracted from your page.
|
|||
![4th step][5] {mt-2}
|
||||
|
||||
We index the temporary record when we add an element to it (if
|
||||
`min_indexed_level` is set to `0`)
|
||||
`min_indexed_level` equals `0`)
|
||||
|
||||
## We pile up the elements based on the current temporary record
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ title: How does it work?
|
|||
|
||||
Getting up and ready with DocSearch is a straightforward process that requires
|
||||
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 JavaScript
|
||||
Search-UI in your frontend. You only need to copy and paste a JavaScript
|
||||
snippet.
|
||||
|
||||
![How it works][4] {mt-2}
|
||||
|
|
@ -23,13 +23,13 @@ applications, please give us a couple of days to get back to you :)
|
|||
|
||||
Once we receive [your application][1], 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
|
||||
should crawl or ignore, as well as the specific CSS selectors to use for
|
||||
selecting headers, subheaders, etc. All configs are publicly available in our
|
||||
[config repository][2].
|
||||
|
||||
This step still requires some manual work and human brain, but thanks to the +1
|
||||
000 configs we already created, we're able to automate most of it. Once this
|
||||
creation is done, we'll run a first indexing of your website and have it run
|
||||
creation finishes, we'll run a first indexing of your website and have it run
|
||||
automatically every 24h.
|
||||
|
||||
## You update your website
|
||||
|
|
@ -38,10 +38,10 @@ 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 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.
|
||||
The default styling of the dropdown uses a grey theme to fit in most designs. We
|
||||
have made the dropdown itself with HTML using custom CSS classes and we
|
||||
recommend 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.
|
||||
|
|
|
|||
|
|
@ -14,14 +14,14 @@ link in those pages until it has browsed every compliant page.
|
|||
|
||||
If you have explicitly defined a `sitemap.xml`, our crawler will scrape every
|
||||
provided and compliant page. We do recommend using [a sitemap][1] since it
|
||||
clearly exposes URLs to crawl and avoid missing pages that aren't linked from
|
||||
explicitly exposes URLs to crawl and avoid missing pages 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 web page and index it, preserving your
|
||||
data's structure. This is achieved in a simple way:
|
||||
data's structure. It achieves this in a simple way:
|
||||
|
||||
- We **read top down** your web page following your HTML flow and pick out your
|
||||
matching elements according to their **levels** based on the `selectors_level`
|
||||
|
|
@ -40,8 +40,8 @@ isn't flushed._
|
|||
|
||||
Algolia always returns the most relevant results first, using a [tie-breaking
|
||||
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`.
|
||||
then fallback to partial matches. It sorts those results, once again, on the
|
||||
page hierarchy, as extracted from the `selectors`.
|
||||
|
||||
The default strategy is to promote records having matching words in the highest
|
||||
level first. Thus if two results have the same matching words, the one having
|
||||
|
|
@ -49,14 +49,14 @@ them in the highest level (lvl0) will be ranked 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 customized according to the
|
||||
Algolia tie-breaking method.
|
||||
We base relevancy on several factors and customize it according to the Algolia
|
||||
tie-breaking method.
|
||||
|
||||
You can boost pages depending on their URLs. This is done from the `start_urls`
|
||||
and its `page_rank` attributes. It is a numeric value (defaults to 0). The
|
||||
higher 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 on their URLs. You should use the `start_urls` and
|
||||
its `page_rank` attributes. Its value is a numeric value (defaults to 0). The
|
||||
higher the value 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
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ see how to enable DocSearch on your website:
|
|||
- [pkgdown][6] - [DocSearch indexing][7]
|
||||
- [LaRecipe][8] - [Algolia Search][9]
|
||||
|
||||
Additionally, if you're a maintaining a similar tool and would like to be added
|
||||
to the list, get [in touch with us][10]. We'd be happy to help.
|
||||
If you're a maintaining a similar tool and wants us to add you to the list, get
|
||||
[in touch with us][10]. We'd be happy to help.
|
||||
|
||||
[1]: https://docusaurus.io/
|
||||
[2]: https://docusaurus.io/docs/en/search#docsNav
|
||||
|
|
|
|||
|
|
@ -56,14 +56,14 @@ It can have this following aspect:
|
|||
The biggest blue element will be you `DocSearch-content` container. More details
|
||||
in the following guidelines.
|
||||
|
||||
### Implement the right classes as [selectors][3]
|
||||
### Use the right classes as [selectors][3]
|
||||
|
||||
You can add some specific static classes to help us find your content's role.
|
||||
These classes can not involve any style changes. These dedicated classes will
|
||||
help us to create a great learn as you type experience from your documentation.
|
||||
|
||||
- Add a static class `DocSearch-content` to the main container of your textual
|
||||
content. It is mostly a `<main/>` or an `<article/>` HTML element.
|
||||
content. Most of the time, this tag `<main/>` or an `<article/>` HTML element.
|
||||
|
||||
- Every searchable `lvl` elements outside this main documentation container (for
|
||||
instance in a sidebar) must be `global` selectors. They will be globally
|
||||
|
|
|
|||
|
|
@ -20,8 +20,8 @@ variables. If you don't have an Algolia account, you need to [create one][2].
|
|||
- `APPLICATION_ID` set to your Algolia Application ID
|
||||
|
||||
- `API_KEY` set to your API Key. Make sure to use an API key with **write**
|
||||
access to your index. [The ACL `addObject`, `editSettings` and
|
||||
`deleteIndex`][3] must be allowed to this key.
|
||||
access to your index. It needs [the ACL `addObject`, `editSettings` and
|
||||
`deleteIndex`][3].
|
||||
|
||||
For convenience, you can create a `.env` file in the repository root.
|
||||
|
||||
|
|
@ -35,14 +35,14 @@ API_KEY=YOUR_API_KEY
|
|||
You can run a crawl from the packaged Docker image to crawl your website. You
|
||||
will need to [install jq, a lightweight command-line JSON processor][4]
|
||||
|
||||
Then you only need to start the crawl according to your configuration. You
|
||||
should check the [dedicated configuration documentation][5].
|
||||
Then you need to start the crawl according to your configuration. You should
|
||||
check the [dedicated configuration documentation][5].
|
||||
|
||||
```sh
|
||||
docker run -it --env-file=.env -e "CONFIG=$(cat /path/to/your/config.json | jq -r tostring)" algolia/docsearch-scraper
|
||||
```
|
||||
|
||||
Once the crawl is done, you can [jump to the Integration step][6].
|
||||
Once the scraping finishes, you can [jump to the Integration step][6].
|
||||
|
||||
## Running the crawler from the code base
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ DocSearch default colorscheme comes in a grey theme with blue highlight.
|
|||
![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
|
||||
your own theme. You can achieved it by overriding the CSS classes used by the
|
||||
default theme.
|
||||
|
||||
The following annotated example will help you style each part:
|
||||
|
|
@ -77,13 +77,13 @@ docsearch({
|
|||
|
||||
## Other considerations
|
||||
|
||||
Selected suggestions 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.
|
||||
It wraps selected suggestions 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 add
|
||||
media queries (for example `@media (min-width: 768px) {}`) to target different
|
||||
On small screens, DocSearch reverts to a single column layout, while is uses the
|
||||
two-column layout shown in the screenshot on larger screens. You can add media
|
||||
queries (for example `@media (min-width: 768px) {}`) to target different
|
||||
displays.
|
||||
|
||||
## Advanced styling
|
||||
|
|
@ -93,8 +93,8 @@ Whether you would like to do more heavy styling, feel free to have a look at the
|
|||
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.
|
||||
`yarn run build:css`. It generates the resulting file in `./dist/cdn`, and you
|
||||
should use them instead of the default one.
|
||||
|
||||
[1]: ./assets/default-colorscheme.png
|
||||
[2]: https://www.algolia.com/pricing
|
||||
|
|
|
|||
|
|
@ -39,8 +39,7 @@ has better relevance in its search results.
|
|||
|
||||
Finding the right depth of your documentation tree and how to split-up your
|
||||
content are two of the most complex tasks. For large documents, we recommend
|
||||
having 4 levels (from lvl0 until lvl3). Three different levels should be a
|
||||
minimum.
|
||||
having 4 levels (from lvl0 until lvl3). We recommend at least three different levels.
|
||||
|
||||
\_Note that you don't have to use `<hX>` tags and can use
|
||||
`<span class="title-X">` for example instead. Your will need to update your set
|
||||
|
|
@ -122,7 +121,7 @@ dataset (for example a different version), you should use [facets][3].
|
|||
|
||||
What is clearly thought out is clearly and concisely expressed.
|
||||
|
||||
We really recommend that you read this blog post about [how to build a helpful
|
||||
We highly recommend that you read this blog post about [how to build a helpful
|
||||
search for technical documentation][2].
|
||||
|
||||
[1]: https://www.sitemaps.org/index.html
|
||||
|
|
|
|||
|
|
@ -5,10 +5,10 @@ title: What is DocSearch?
|
|||
|
||||
## Why?
|
||||
|
||||
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.
|
||||
We have created DocSearch because we are scratching 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.
|
||||
|
||||
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
|
||||
|
|
@ -17,10 +17,9 @@ and make it available to everyone from the first keystroke.
|
|||
|
||||
## Quick description
|
||||
|
||||
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.
|
||||
We split DocSearch into 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 can then add the frontend library to your website to search in that index.
|
||||
|
||||
## How to feature DocSearch?
|
||||
|
||||
|
|
|
|||
|
|
@ -3,17 +3,17 @@ layout: two-columns
|
|||
title: Who can apply?
|
||||
---
|
||||
|
||||
DocSearch was built from the ground up with the idea of improving search on
|
||||
large technical documentation. For that reason, we are offering a free hosting
|
||||
version to all online technical documentation.
|
||||
We built DocSearch from the ground up with the idea of improving search on large
|
||||
technical documentation. For that reason, we are offering a free hosting version
|
||||
to all online technical documentation.
|
||||
|
||||
We're always sad to have to turn down applications, but with the number of
|
||||
requests we receive everyday, we've had to focus on several criteria. We hope
|
||||
you understand.
|
||||
requests we receive everyday, we've had to focus on fair criteria. We hope you
|
||||
understand.
|
||||
|
||||
## The checklist
|
||||
|
||||
To have your request validated, we'll ask that you validate all the following
|
||||
To have your request validated, we'll ask that you check all the following
|
||||
points.
|
||||
|
||||
- You must be the **owner** of the website, or at least have the power to update
|
||||
|
|
@ -49,10 +49,10 @@ criteria:
|
|||
- 🙂 If you're using one of our [official integrations][4], 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
|
||||
recommend that you put in place server-side rendering for the useful textual
|
||||
content.
|
||||
- ☹️ If we need to render your website 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.
|
||||
|
||||
[1]: ./apply.html
|
||||
[2]: ./run-your-own.html
|
||||
|
|
|
|||
Loading…
Reference in a new issue