1. Introduction
This website — docs.checkmk.com — uses static HTML pages built with Asciidoctor, which are updated daily. Such a solution is performant and it will be the most efficient way to provide the User Guide to you for many years to come. Another advantage is that each article is available as a single file. This means that the index for the search can be built into the file system without requiring a detour via the network. To take advantage of this, the search was switched from a crawler solution to the Lunr.js JavaScript program in September 2022.
Lunr uses an index that is fully loaded as a JavaScript object on the first page load. This object is less than one megabyte in compressed size and remains in the browser’s cache, which makes the search very fast. Only when a new index is available — which is once a day — will it be reloaded into the browser cache.
Building the index along with the HTML pages allows us to hide page elements such as the table of contents, so that the index contains only relevant terms.
2. Using the search box
In principle, the search works like any other search engine: enter search terms in the search box on docs.checkmk.com.
These are matched against the index and you will receive a weighted list of results.
2.1. The simple search
In a simple search, enter the search terms one after the other in the search box. The resulting list will be sorted as follows:
At the top of the results list are pages that contain all of the search terms and which are the closest match.
This is followed by pages that contain all of the search terms, but which match less closely.
Finally follow pages which contain fewer of the terms, and finally only one of the entered search terms.
An occurrence in a page title and in a meta description is weighted higher than one in body text.
Below the search box, the 5 best results are listed. In the line below, you can display all results in a new overlay window.
2.2. Including and excluding search terms
You can use the + and - operators to explicitly include or exclude search terms. Examples:
|
Finds all pages that contain |
|
Finds pages that contain |
|
Finds all pages that contain neither |
2.3. Terms that are used in combination
To find any terms that are used together, you can mask spaces or punctuation or hyphens by using two backslashes followed by a space.
So agent\\ controller will find all pages with Agent Controller even if the wrong hyphenated spelling is used.
With +agent +controller, on the other hand, pages are found that contain Agent and Controller in any order and with any spacing.
2.4. Wildcard
The asterisk * replaces any string at any position of a search term.
As you type, in the background an asterisk is automatically added to the end of your typed text to generate the preview.
Finish your search text with a space to find the exact search term.
2.5. Weighting
Append an integer with a circumflex (^) to a search term to weight it higher than the default for that factor:
|
Weights |
3. Linking to search
You can also pass parameters for a search in docs.checkmk.com via the URL.
The JavaScript then transfers the search term(s) to the search box and starts the search.
The following parameters are available:
|
At least one search term is required. You can separate multiple search terms with |
|
Does not open the preview with five results, but the larger overlay window with all hits. |
|
Immediately opens the article of the first search result. |
|
Specify this parameter to the origin if you link from the forum, for example, or if you create the search in the User guide as a search engine.
Our web server writes the query parameter to its log files.
We evaluate this parameter statistically, currently for |
In principle, the search works on any page.
For example, you can access the English article on the Linux agent with an open search for the term linux as follows:
https://docs.checkmk.com/latest/en/agent_linux.html?find=linux&origin=bookmarks