[doc] Advocate for a generic configuration (#631)
* moving recommendated to required configuration * resolves #627
This commit is contained in:
Sylvain Pace
GitHub
parent
80d595339c
commit
f30e44f17d
5 changed files with 12476 additions and 139 deletions
|
|
@ -49,11 +49,11 @@
|
|||
]
|
||||
},
|
||||
{
|
||||
"title": "Tips, FAQ, Misc",
|
||||
"title": "Requirements, Tips, FAQ",
|
||||
"pages": [
|
||||
{
|
||||
"title": "Recommended configuration",
|
||||
"url": "recommended-configuration.html"
|
||||
"title": "Required configuration",
|
||||
"url": "required-configuration.html"
|
||||
},
|
||||
{
|
||||
"title": "Tips",
|
||||
|
|
@ -159,6 +159,10 @@
|
|||
{
|
||||
"from": "documentation/docsearch-FAQ/does-my-project-qualify/index.html",
|
||||
"to": "faq.html"
|
||||
},
|
||||
{
|
||||
"from": "recommended-configuration.html",
|
||||
"to": "required-configuration.html"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
12324
docs/package-lock.json
generated
Normal file
12324
docs/package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -12,24 +12,25 @@ config.
|
|||
|
||||
```html
|
||||
<!-- Before the closing </head> -->
|
||||
<link rel="stylesheet"
|
||||
<link
|
||||
rel="stylesheet"
|
||||
href="https://cdn.jsdelivr.net/npm/docsearch.js@{{docSearchJSVersion}}/dist/cdn/docsearch.min.css"
|
||||
/>
|
||||
|
||||
<!-- Before the closing </body> -->
|
||||
<script
|
||||
src="https://cdn.jsdelivr.net/npm/docsearch.js@{{docSearchJSVersion}}/dist/cdn/docsearch.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/docsearch.js@{{docSearchJSVersion}}/dist/cdn/docsearch.min.js"></script>
|
||||
<script>
|
||||
docsearch({
|
||||
// Your apiKey and indexName will be given to you once
|
||||
// we create your config
|
||||
apiKey: '<API_KEY>',
|
||||
indexName: '<INDEX_NAME>',
|
||||
//appId: '<APP_ID>', // Should be only included if you are running DocSearch on your own.
|
||||
// Replace inputSelector with a CSS selector
|
||||
// matching your search input
|
||||
inputSelector: '<YOUR_CSS_SELECTOR>',
|
||||
// Set debug to true if you want to inspect the dropdown
|
||||
debug: false
|
||||
debug: false,
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,132 +0,0 @@
|
|||
---
|
||||
layout: two-columns
|
||||
title: Recommendation
|
||||
---
|
||||
|
||||
This is great news to know that you want to integrate DocSearch in your website.
|
||||
A good search experience is key to help your users discover your content.
|
||||
Documentation is a huge part of your tool.
|
||||
|
||||
This section, [empowered by the details about how we build a DocSearch
|
||||
index][1], gives you the best practices to optimize our crawl. It will enhance
|
||||
your user's journey.
|
||||
|
||||
## Nice to have
|
||||
|
||||
- Your website should have [an updated sitemap][2]. This is key to let our
|
||||
crawler know what should be updated. Do not worry, we will still crawl your
|
||||
website and discover embedded hyperlinks to find your great content.
|
||||
|
||||
- Every pages needs to have their full context available. Using global element
|
||||
might help.
|
||||
|
||||
- Every `lvlx` DOM elements (matching the selectors defined in your
|
||||
configuration) must have a unique `id` or `name`. This will help the
|
||||
redirection to directly scroll down to the exact place of the matching
|
||||
elements. These attributes defined the right anchor to use.
|
||||
|
||||
- Make sure your documentation content is also available without JavaScript
|
||||
rendering on the client-side. If you absolutely need JavaScript turned on, you
|
||||
need to [set `js_render: true` in your config][3].
|
||||
|
||||
- Use the recommended selectors. See below:
|
||||
|
||||
### Recommended [selectors][4]
|
||||
|
||||
Your HTML can add some specific static classes with no styling. These classes
|
||||
will not impact your content and will help us to create a great discovery
|
||||
experience. Impatient to know how?, follow these points:
|
||||
|
||||
- Add a static `docSearch-content` class to the biggest and smaller element
|
||||
gathering your documentation. This element is the main container of your
|
||||
textual content. HTML tag used are often main or article element.
|
||||
|
||||
- Every elements outside this main documentation container (for instance in nav)
|
||||
should be `global`. They should be sorted according to their `lvl` along the
|
||||
HTML flow (`lvl0` appears before `lvl1`).
|
||||
|
||||
- Use the standard title tags like `h1`, `h2`, `h3` ... Do not forget to set a
|
||||
unique `id` or `name` attribute to these elements as previously described.
|
||||
|
||||
- Stay consistent and do not forget that we need to have some regularity along
|
||||
the HTML flow [as presented here][5].
|
||||
|
||||
### Overview of a clear layout
|
||||
|
||||
A website implementing these good practises will look simple and crystal clear.
|
||||
It can have this following aspect:
|
||||
|
||||
![Recommended layout for your page][5] {mt-2}
|
||||
|
||||
The biggest blue element will be you `docSearch-content` container. Every
|
||||
selectors outside this element will be `global`. Every selectors appear in the
|
||||
same order than their `lvl` along the HTML flow.
|
||||
|
||||
### Introduces global information as meta tags
|
||||
|
||||
Our crawler automatically extract information from our DocSearch specific meta
|
||||
tags:
|
||||
|
||||
```html
|
||||
<meta name="docsearch:language" content="en">
|
||||
<meta name="docsearch:version" content="1.0.0">
|
||||
```
|
||||
|
||||
The `content` value of the meta is added to every records extracted from the
|
||||
page. Given that the name is `docsearch:$NAME`, `$NAME` is set as an attribute
|
||||
to every records while its value is the related `content` value. You can then
|
||||
transform them as [`facetFilters`][6] to filter over them. We will need to use
|
||||
Algolia settings via the DocSearch `custom_settings` parameter and set
|
||||
`attributesForFaceting` Algolia parameter.
|
||||
|
||||
Look at this example with our vuepress integration:
|
||||
|
||||
```json
|
||||
"custom_settings": {
|
||||
"attributesForFaceting": [
|
||||
"lang"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### The generic configuration example
|
||||
|
||||
```json
|
||||
{
|
||||
"index_name": "perfect_docsearch_website",
|
||||
"start_urls": ["https://myperfectwebsite.io"],
|
||||
"sitemap_urls": ["https://myperfectwebsite.io/sitemap.xml"],
|
||||
"stop_urls": [],
|
||||
"selectors": {
|
||||
"lvl0": {
|
||||
"selector": ".header .active",
|
||||
"global": true,
|
||||
"default_value": "Documentation"
|
||||
},
|
||||
"lvl1": {
|
||||
"selector": "nav .active",
|
||||
"global": true,
|
||||
"default_value": "Chapter"
|
||||
},
|
||||
"lvl1": ".docSearch-content h1",
|
||||
"lvl2": ".docSearch-content h2",
|
||||
"lvl3": ".docSearch-content h3",
|
||||
"lvl4": ".docSearch-content h4",
|
||||
"text": ".docSearch-content p, .docSearch-content li"
|
||||
},
|
||||
"custom_settings": {
|
||||
"attributesForFaceting": ["language(meta)", "version(meta)", "tags"]
|
||||
},
|
||||
"nb_hits": "OUTPUT OF THE CRAWL"
|
||||
}
|
||||
```
|
||||
|
||||
Any question ? [Send us an email][7].
|
||||
|
||||
[1]: ./how-do-we-build-an-index.html
|
||||
[2]: https://www.sitemaps.org/
|
||||
[3]: ./config-file.html#js_render-optional
|
||||
[4]: ./config-file.html
|
||||
[5]: ./assets/proper_layout.png
|
||||
[6]: https://www.algolia.com/doc/guides/searching/filtering/#facet-filters
|
||||
[7]: mailto:docsearch@algolia.com
|
||||
140
docs/src/required-configuration.md
Normal file
140
docs/src/required-configuration.md
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
---
|
||||
layout: two-columns
|
||||
title: Required configuration
|
||||
---
|
||||
|
||||
This section, [empowered by the details about how we build a DocSearch
|
||||
index][1], gives you the best practices to optimize our crawl. Adopting this
|
||||
following specification is required to let our crawler build the best experience
|
||||
from your website. You will need to update your website and follow these rules.
|
||||
Your documentation will match our generic configuration:
|
||||
|
||||
Note: If your website is generated thank to one of our supported tool, you do
|
||||
not need to change your website as it is already compliant with our
|
||||
requirements.
|
||||
|
||||
## The generic configuration example
|
||||
|
||||
```json
|
||||
{
|
||||
"index_name": "example",
|
||||
"start_urls": ["https://www.example.com/doc/"],
|
||||
"sitemap_urls": ["https://www.example.com/sitemap.xml"],
|
||||
"stop_urls": [],
|
||||
"selectors": {
|
||||
"lvl0": {
|
||||
"selector": ".DocSearch-lvl0",
|
||||
"global": true,
|
||||
"default_value": "Documentation"
|
||||
},
|
||||
"lvl1": {
|
||||
"selector": ".DocSearch-lvl1",
|
||||
"global": true,
|
||||
"default_value": "Chapter"
|
||||
},
|
||||
"lvl2": ".DocSearch-content .DocSearch-lvl2",
|
||||
"lvl3": ".DocSearch-content .DocSearch-lvl3",
|
||||
"lvl4": ".DocSearch-content .DocSearch-lvl4",
|
||||
"lvl5": ".DocSearch-content .DocSearch-lvl5",
|
||||
"lvl6": ".DocSearch-content .DocSearch-lvl6",
|
||||
"text": ".DocSearch-content p, .DocSearch-content li"
|
||||
},
|
||||
"custom_settings": {
|
||||
"attributesForFaceting": ["language", "version"]
|
||||
},
|
||||
"nb_hits": "OUTPUT OF THE CRAWL"
|
||||
}
|
||||
```
|
||||
|
||||
### Overview of a clear layout
|
||||
|
||||
A website implementing these good practises will look simple and crystal clear.
|
||||
It can have this following aspect:
|
||||
|
||||
![Recommended layout for your page][2] {mt-2}
|
||||
|
||||
The biggest blue element will be you `DocSearch-content` container. More details
|
||||
in the following guidelines.
|
||||
|
||||
### Implement the right classes as [selectors][3]
|
||||
|
||||
You can add some specific static classes to help us identify 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 `DocSearch-content` class to the main container of your textual
|
||||
content. It is mostly a main or 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
|
||||
pickup and injected to every records built from your page. Be careful, the
|
||||
level's value matter and every matching element must have an increasing level
|
||||
along the HTML flow. The level `X` (for `lvlX`) should appear after a level
|
||||
`Y` while `X>Y`. We do not recommend `text` element to be global.
|
||||
|
||||
- `lvlX` selectors should use the standard title tags like `h1`, `h2`, `h3` ...
|
||||
You can add a class to these elements. Do not forget to set a unique `id` or
|
||||
`name` attribute to these elements as explain below.
|
||||
|
||||
- Every `lvlx` DOM elements (matching the selectors defined in your
|
||||
configuration) must have a unique `id` or `name`. This will help the
|
||||
redirection to directly scroll down to the exact place of the matching
|
||||
elements. These attributes defined the right anchor to use.
|
||||
|
||||
- Every textual element (selector `text`) must be wrapped in a tag `<p/>` or
|
||||
`<li/>`. This content must be atomic and split into small entities. Be careful
|
||||
to never nest one of these tags into another one, it will create duplicates.
|
||||
|
||||
- Stay consistent and do not forget that we need to have some regularity along
|
||||
the HTML flow [as presented here][2].
|
||||
|
||||
## Introduces global information as meta tags
|
||||
|
||||
Our crawler automatically extract information from our DocSearch specific meta
|
||||
tag:
|
||||
|
||||
```html
|
||||
<meta name="docsearch:language" content="en" />
|
||||
<meta name="docsearch:version" content="1.0.0" />
|
||||
```
|
||||
|
||||
The `content` value of the meta will be added to every records extracted from
|
||||
the page. Given that the name is `DocSearch:$NAME`, `$NAME` will be set as a
|
||||
attribute in each of them. Its value will be its related `content` value. You
|
||||
can then transform them as [`facetFilters`][4] to filter over them. We will need
|
||||
to use Algolia settings via the DocSearch `custom_settings` parameter and set
|
||||
`attributesForFaceting` Algolia parameter.
|
||||
|
||||
Look at this example with our vuepress integration:
|
||||
|
||||
```json
|
||||
"custom_settings": {
|
||||
"attributesForFaceting": [
|
||||
"lang"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Nice to have
|
||||
|
||||
- Your website should have [an updated sitemap][5]. This is key to let our
|
||||
crawler know what should be updated. Do not worry, we will still crawl your
|
||||
website and discover embedded hyperlinks to find your great content.
|
||||
|
||||
- Every pages needs to have their full context available. Using global element
|
||||
might help (see above).
|
||||
|
||||
- Make sure your documentation content is also available without JavaScript
|
||||
rendering on the client-side. If you absolutely need JavaScript turned on, you
|
||||
need to [set `js_render: true` in your config][6].
|
||||
|
||||
Any question ? [Send us an email][7].
|
||||
|
||||
[1]: ./how-do-we-build-an-index.html
|
||||
[2]: ./assets/proper_layout.png
|
||||
[3]: ./config-file.html
|
||||
[4]: https://www.algolia.com/doc/guides/searching/filtering/#facet-filters
|
||||
[5]: https://www.sitemaps.org/
|
||||
[6]: ./config-file.html#js_render-optional
|
||||
[7]: mailto:DocSearch@algolia.com
|
||||
Loading…
Reference in a new issue