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.
2.1. Einfache Suche
Bei der einfachen Suche geben Sie die Suchbegriffe nacheinander in das Suchfeld sein. Die Ergebnisliste ist dann wie folgt sortiert:
Ganz oben stehen Seiten, die alle Suchbegriffe in direkter Nähe zueinander enthalten.
Es folgen Seiten, die alle Suchbegriffe, aber in größerer Distanz, enthalten.
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:
|
Findet alle Seiten, die |
|
Findet Seiten, die |
|
Findet alle Seiten, in denen weder |
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:
|
Gewichtet |
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:
|
Mindestens ein Suchbegriff ist notwendig, mehrere Suchbegriffe können Sie mit |
|
Öffnet nicht die Vorschau mit fünf Ergebnissen, sondern das größere Overlay-Fenster mit allen Treffern. |
|
Öffnet sofort den Artikel des ersten Suchergebnisses. |
|
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 |
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