Checkmk
to checkmk.com

1. Einleitung

Diese Website – docs.checkmk.com – nutzt statisch mit Asciidoctor gebaute HTML-Seiten, die täglich aktualisiert werden. Solch eine Lösung ist performant und sie wird noch viele Jahre die effizienteste Möglichkeit sein, Ihnen das Handbuch auszuliefern. Ein weiterer Vorteil ist, dass jeder Artikel als Einzeldatei vorhanden ist. Damit kann der Index für die Suche im Dateisystem ohne den Umweg über das Netzwerk aufgebaut werden. Um dies zu nutzen, wurde die Suche im September 2022 von einer Crawler-Lösung auf das JavaScript-Programm Lunr.js umgestellt.

Lunr verwendet einen Index, der als JavaScript-Objekt beim ersten Seitenaufruf komplett mitgeladen wird. Das Objekt ist komprimiert weniger als ein Megabyte groß und verbleibt im Cache des Browsers, was die Suche sehr schnell macht. Nur, wenn ein neuer Index verfügbar ist — was einmal täglich der Fall ist — wird dieser neu in den Browser Cache geladen.

Das Bauen des Index zusammen mit den HTML-Seiten erlaubt es uns, Seitenelemente wie das Inhaltsverzeichnis auszublenden, so dass der Index nur relevante Begriffe enthält.

2. Suchen im Suchfeld

Prinzipiell funktioniert die Suche wie bei jeder anderen Suchmaschine auch: Sie geben Suchbegriffe in das Suchfeld auf docs.checkmk.com ein. Diese werden mit dem Index abgeglichen und Sie erhalten eine gewichtete Liste von Ergebnissen.

Bei der einfachen Suche geben Sie die Suchbegriffe nacheinander in das Suchfeld sein. Die Ergebnisliste ist dann wie folgt sortiert:

  1. Ganz oben stehen Seiten, die alle Suchbegriffe in direkter Nähe zueinander enthalten.

  2. Es folgen Seiten, die alle Suchbegriffe, aber in größerer Distanz, enthalten.

  3. Schließlich folgen Seiten, welche weniger und schließlich nur einen der eingegebenen Suchbegriffe enthalten.

Das Vorkommen im Seitentitel und in der Meta-Beschreibung wird hierbei höher gewichtet als im Fließtext.

Unterhalb des Suchfelds werden die 5 besten Ergebnisse gelistet. In der Zeile darunter können Sie sich alle Ergebnisse in einem neuen Overlay-Fenster anzeigen lassen.

2.2. Suchbegriffe ein- und ausschließen

Mit den Operatoren + und - können Sie Suchbegriffe explizit einschließen und ausschließen. Beispiele:

+database -oracle

Findet alle Seiten, die database enthalten, oracle aber nicht.

+database -oracle mysql

Findet Seiten, die database, aber nicht oracle enthalten und zeigt diejenigen Ergebnisse höher gewichtet, die zudem noch mysql enthalten.

-database -oracle -mysql

Findet alle Seiten, in denen weder database noch oracle noch mysql vorkommen.

2.3. Zusammen vorkommende Begriffe

Um zusammen stehende Begriffe zu finden, können Sie Leer- oder Satzzeichen oder Kopplungsstriche durch zwei Backslashes gefolgt von einem Leerzeichen maskieren. So findet agent\\ controller alle Seiten mit Agent Controller auch wenn die falsche Schreibweise mit Bindestrich verwendet wird. Mit +agent +controller werden dagegen Seiten gefunden, die Agent und Controller in beliebiger Reihenfolge und in beliebigem Abstand enthalten.

2.4. Wildcard

Der Asterisk * ersetzt eine beliebige Zeichenkette an einer beliebigen Stelle eines Suchbegriffs. Während Sie tippen, fügen wir im Hintergrund automatisch den Asterisk am Ende des eingegebenen Textes hinzu, um die Vorschau erzeugen zu können. Schließen Sie Ihre Suche mit einem Leerzeichen ab, um den exakten Suchbegriff zu finden.

2.5. Gewichtung

Hängen Sie eine Ganzzahl mit einem Zirkumflex an einen Suchbegriff an, um ihn um diesen Faktor höher als den Standard zu gewichten:

oracle^10 mysql^3 database

Gewichtet oracle zehnfach höher als database und mysql dreifach höher als database.

3. Verlinkung auf die Suche

Sie können für die Suche auf docs.checkmk.com in der URL auch Parameter übergeben. Das JavaScript überträgt den Suchbegriff dann ins Suchfeld und startet die Suche. Folgende Parameter sind möglich:

find=searchterm

Mindestens ein Suchbegriff ist notwendig, mehrere Suchbegriffe können Sie mit + trennen. Verwenden Sie die Prozentdarstellung für alle anderen Sonderzeichen und Umlaute. Zum Beispiel wird + durch %2B ersetzt und - durch %2D.

fulloverlay=1

Öffnet nicht die Vorschau mit fünf Ergebnissen, sondern das größere Overlay-Fenster mit allen Treffern.

imlucky=1

Öffnet sofort den Artikel des ersten Suchergebnisses.

origin=forum

Geben Sie diesen Parameter zum Ursprung mit an, wenn Sie zum Beispiel aus dem Forum verlinken oder sich die Suche im Handbuch als Suchmaschine anlegen. Unser Webserver schreibt die Query-Parameter in seine Log-Dateien. Wir werten diesen Parameter statistisch aus, derzeit für bookmarks, forum, support und checkmk.

Prinzipiell funktioniert die Suche auf jeder Seite. Sie können beispielsweise den englischen Artikel zum Linux-Agenten mit geöffneter Suche nach dem Begriff linux wie folgt aufrufen:
https://docs.checkmk.com/latest/en/agent_linux.html?find=linux&origin=bookmarks

Auf dieser Seite