nikon/docsearch
1
0
Fork 0
Code Activity Actions

Doc(content): Adding a FAQ (#339)

Browse source 
* integrate previous work

enhance tyle/content

reformat part 1

wait for review

* adance start_urls

* enhance attributes description

* fix typo

* proofread documentation/docsearch

* add apiKey mention

intefrate review and small fixes

finished proofreading

update sclient-rendering

use unseen review

* update README #269

* fix json

* explain new parameter from algolia/docsearch-scraper#368 , solve algolia/docsearch-configs#321

* enhance  as algolia/docsearch-configs#387

* updating flavicon

* add FAQ section

* made some text corrections

* Update 1-customize-configuration-file.html.md.erb
This commit is contained in:
Sylvain Pace 2018-05-28 17:56:08 +02:00 committed by GitHub
parent 9658b67a92
commit d81c817b2a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 79 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

79
docs/source/documentation/4-docsearch-FAQ/1-customize-configuration-file.html.md.erb Normal file
View file

@ -0,0 +1,79 @@
---
title: Customize my configuration file
---
## What content do we recommend indexing?
### Code blocks
We **do not recommend** indexing **code tags** since code blocks are most likely
very similar and redundant from one page to another.
You can exclude code blocks by adding their matching selectors to `selectors_exclude`.
A good practice would be to emphasize the meaningful underlying part of it
thanks to a dedicated class, which you will want to add to the `text` selector
in your configuration file.
For example, in this code snippet, you can exclude the code except the parameter of the function:
```
<code>
function(<toIndex>something useful to search for</toIndex>)
...
</code>
```
### Table of contents
The elements of the table of contents only *target* but do not provide actual content.
They are merely a step on the way to reaching relevant content. As a result, they are
almost always in a different place from the payload. This is why we consider the
table of contents an obstacle for DocSearch to find the coveted information.
We therefore **do not recommend** indexing the elements of the table of contents; their matching
selectors should be added to `selectors_exclude`.
## How are my DocSearch records ranked?
DocSearch empowers the Algolia ranking strategy. The formula is completely
based on [the tie-breaking approach](https://www.algolia.com/doc/guides/ranking/ranking-formula/#tie-breaking-approach).
The special feature of DocSearch's ranking resides in [the custom ranking](https://www.algolia.com/doc/guides/ranking/custom-ranking/):
We have defined 3 main weight indicators for every record. These values are
ordered by importance following the tie-breaking approach:
1. `page_rank`: this value, equal to `0` by default, can be set from the
`start_urls` object. It can be customized in order to boost or restrain some
records depending on **their webpage's URL**. It will need to match a **specific
regular expression pattern**.
**Example:**
```json
{
"index_name": "example",
"start_urls": [
{
"url": "http://example.com/docs/api/v1\\.[0-9]",
"page_rank": 1
}
]
}
```
2. `level`: this value depends on the `level` of the record. A record's level is
its **deepest level attribute not null**. `text` records have a weight of 0.
3. `position`: This value is the position of the matching element within every
picked up element along the original HTML flow. The **sooner** the record appears,
the **higher** it will be ranked.
You can override the way these elements are impacting the search thanks to `custom_settings`.
**Example:**
```json
"custom_settings": {
"customRanking": [
"asc(weight.position)",
"desc(weight.page_rank)",
"desc(weight.level)"
]
}
```