Code-Boxen mit Syntax-Highlighting in Onlinedokumentation
Technische Dokumentation, insbesondere Softwaredokumentation, enthält häufig Code-Beispiele. Mit Hilfe einer entsprechenden JavaScript-Bibliothek lassen sich Code-Schnipsel besonders benutzerfreundlich darstellen:
▪Befehle und Parameter werden abhängig von der verwendeten Programmiersprache oder dem Markup farbig dargestellt (Syntax Highlighting).
▪Es gibt eine Funktion zum direkten Kopieren oder Speichern des angezeigten Codes.
▪Es gibt bei Bedarf eine horizontale Scrollfunktion für lange Codezeilen.
Beispiel
Auch diese Website verwendet für ihre Code-Beispiele Code-Boxen mit automatischem Syntax-Highlighting und einer Kopierfunktion. Sehen Sie sich einmal die Code-Ausschnitte im folgenden Abschnitt „Implementierung“ an.
Implementierung
Die hier vorgestellte Lösung nutzt die Open-Source-JavaScript-Bibliothek Prism.
Für das Design stehen diverse Themes zur Auswahl. Für erweiterte Funktionen gibt es zur Bibliothek diverse Plugins. Beim Herunterladen der Bibliothek müssen Sie auswählen, welches Theme und welche Plugins Sie verwenden möchten und in welchen Programmiersprachen die anzuzeigenden Inhalte vorliegen. Je mehr Optionen Sie auswählen, desto größer wird der Download und damit die spätere Ladezeit in Ihrer Onlinedokumentation. Beschränken Sie sich daher auf das, was Sie tatsächlich brauchen.
Schritt 1: Verlinken Sie im Head-Abschnitt Ihrer Seitenvorlage auf die CSS-Datei der Bibliothek (passen Sie den Pfad wie erforderlich an).
<link rel="stylesheet" href="YOUR-PATH/prism.css">
Schritt 2: Binden Sie am Ende des Body-Abschnitts Ihrer Seitenvorlage das JavaScript der Bibliothek ein (passen Sie auch dabei wieder den Pfad wie erforderlich an).
<script src="YOUR-PATH/prism.js"></script>
Schritt 3: Sie können im Text beliebig viele Codeblöcke verwenden. Ein solcher Codeblock sieht wie folgt aus (ersetzen Sie die angegebene Sprache durch die Sprache des darzustellenden Codes):
<pre><code class="language-USED-LANGUAGE">
YOUR-CODE-SAMPLE
</code></pre>
Beispiel: Stellen Sie sich vor, Sie möchten den Code folgender JavaScript-Funktion in Ihrem Dokument darstellen.
function myFunction(p1, p2) {
return p1 * p2;
}
Dies ergibt dann:
<pre><code class="language-javascript">
function myFunction(p1, p2) {
return p1 * p2;
}
</code></pre>
Wichtig: Um zu verhindern, dass der Browser versucht, den anzuzeigenden Inhalt direkt als HTML zu interpretierten, müssen Sie linke spitze Klammern durch die HTML‑Entity < und rechte spitze Klammern durch die HTML-Entity > ersetzen. Damit sieht ein Beispiel mit HTML-Code wie folgt aus:
<pre><code class="language-html">
<!DOCTYPE html>
<html>
<body>
<p>Hello world!</p>
</body>
</html>
</code></pre>
Angezeigt wird das dann im Ergebnis so:
<!DOCTYPE html>
<html>
<body>
<p>Hello world!</p>
</body>
</html>
___
Haben Sie von diesen Informationen profitiert?
Bitte verlinken Sie im Gegenzug auf diese Seite, erwähnen Sie die Seite in sozialen Netzwerken, oder erwerben Sie eines meiner Bücher.
Vielen Dank!
Lust auf mehr? Siehe auch weitere Code-Schnipsel zum Aufwerten einer Onlinedokumentation sowie meine anderen Arbeitshilfen zur Technischen Dokumentation.