CSS+JS Code-Schnipsel zum Aufwerten einer Onlinedokumentation

Viele Möglichkeiten, die HTML, CSS und JavaScript heute bieten, und die auf Webseiten längst üblich sind, werden von den Redaktionssystemen für Technische Dokumentation nicht unterstützt. Allerdings bieten fast alle Redaktionssysteme die Möglichkeit, solche Dinge auf eigene Faust hinzuzufügen und damit eine Onlinedokumentation im Einzelfall ungemein aufzuwerten.

Hier finden Sie eine Sammlung fertiger Lösungen und Code-Schnipsel, die vielleicht auch für Ihre eigenen Projekte einen Mehrwert schaffen können.

Verfügbare Lösungen und Beispiele

Aktuell enthält diese Sammlung Lösungen und Beispiele für folgende Anwendungen:

• Schaltfläche zur Rückkehr an den Seitenanfang in Onlinedokumentation
• Begrenzung der Textbreite und automatische Silbentrennung in Onlinedokumentation
• Mehrspaltige Listen und Abschnitte in Onlinedokumentation
• Zwei synchrone Spalten in Onlinedokumentation
• Marginalien in Onlinedokumentation
• Kacheln in Onlinedokumentation – Tiles
• Registerkarten in Onlinedokumentation – Tabs
• Aufklappbare Abschnitte in Onlinedokumentation – Dropdowns, Toggles
• Aufklappbare Bilder in Onlinedokumentation – Thumbnails
• Zoombare Bilder in Onlinedokumentation
• Filter in Onlinedokumentation
• Sortierbare, filterbare, responsive Tabellen in Onlinedokumentation
• Tabellen mit klebender Kopfzeile in Onlinedokumentation
• Tabellen und Bilder als Ganzes klebend in Onlinedokumentation
• Code-Boxen mit Syntax-Highlighting in Onlinedokumentation
• Mathematische Formeln in Onlinedokumentation
• Styles für Hinweise und Warnhinweise in Onlinedokumentation
• Styles für Listen in Onlinedokumentation
• Styles für Hervorhebungen in Onlinedokumentation
• Styles für Tasten in Onlinedokumentation
• Automatische Kennzeichnung externer Links in Onlinedokumentation
• Styles für bestmögliche Druckergebnisse in Onlinedokumentation
• Dezente Animationseffekte in Onlinedokumentation
• Automatisches Mini-TOC mit Scroll Spy in Onlinedokumentation
• Feedback- und Bewertungsfunktionen in Onlinedokumentation

Voraussetzungen

Um die gezeigten Lösungen erfolgreich in Ihre eigenen Projekte übertragen zu können, brauchen Sie HTML, CSS und JavaScript nicht im Detail zu beherrschen. Ein paar elementare Grundkenntnisse, zusammen mit den hier vorgestellten Code-Schnipseln, genügen bereits. Sie sollten lediglich bereits wissen:

• wie HTML-Dateien allgemein aufgebaut sind
• wie Sie CSS-Code in den Head-Abschnitt einer HTML-Datei einfügen oder im Head-Abschnitt einer HTML-Datei eine externe CSS-Datei verlinken
• wie Sie innerhalb Ihres Redaktionssystems in Seitenvorlagen und in Topics HTML-, CSS- und JavaScript-Code einfügen

• wie Sie zusätzliche Dateien in den Output Ihres Redaktionssystems aufnehmen können (nicht für alle Lösungen erforderlich; verfügen die Leser Ihrer Onlinedokumentation über einen Internetzugriff, können Sie die Dateien alternativ auch auf einem Webserver bereitstellen)

Spezielle Hinweise zu einzelnen Redaktionssystemen

Die Lösungen der Sammlung wurden alle mit dem Redaktionssystem Help+Manual getestet und implementiert (diese Website ist ebenfalls mit Help+Manual erstellt). Welches Help Authoring Tool oder Redaktionssystem Sie einsetzen, ist prinzipiell jedoch egal. Nur in seltenen Fällen ist eine Lösung möglicherweise nicht mit dem Output eines bestimmten Redaktionssystems kompatibel.

Spezielle Hinweise zum Redaktionssystem Madcap Flare

Wenn Sie in Flare eine zusätzliche CSS-Datei verlinken, kann es vorkommen, dass Flare diese Referenz beim Generieren des Outputs ungefragt löscht.

Abhilfe: Das Löschen lässt sich verhindern, indem Sie das betreffende Statement erst zur Laufzeit durch ein JavaScript erzeugen:

<script>
 document.write('<link rel="stylesheet" href="YOUR-STYLESHEET.css" />')
</script>

Spezielle Hinweise zum Redaktionssystem HelpNDoc

Das von HelpNDoc zum Erstellen von WebHelp verwendete Default-Template ist Ajax-basiert. Das hat zur Folge, dass ein in einem HTML-Schnipsel stehender JavaScript-Code nicht ausgeführt wird, wenn das Topic über das Inhaltsverzeichnis geöffnet wird. Auch in einem solchen Snippet stehende Links auf externe CSS- und JavaScript-Dateien werden in diesem Fall ignoriert.

Abhilfe: Sie können Hyperlinks auf eigene CSS- und JavaScript-Dateien in einem eigenen Template in der Datei topics.pas.html hinzufügen. Eigene JavaScripte können Sie ebenfalls in der Datei topics.pas.html hinzufügen, und zwar direkt nach der Zeile <% print(GetCustomJs()); %>. Insgesamt sieht dies dann wie folgt aus:

<% print(GetCustomJs()); %>
app.EVENTS.onTopicChanged = (sUrl) => {
 ADD-YOUR-SCRIPTS-HERE
}

Ein paar mit HelpNDoc erstellte Beispiele finden Sie hier (sehen Sie sich erforderlichenfalls im Browser den Quelltext der Seiten an).

HelpNDoc ersetzt beim Generieren die Namen von Absatz- und Zeichenformaten durch fortlaufend nummerierte Klassen. Diese sind leider nicht dauerhaft stabil, sondern können sich später wieder ändern, wenn Sie die Texte überarbeiten. Es ist daher wenig sinnvoll, diese Klassen in einer eigenen CSS-Datei einfach zu überschreiben.

Tabellen besitzen in von HelpNDoc erzeugten Dokumenten kein <thead> Element, auch dann nicht, wenn im Editor ein Tabellenheader definiert wird. Daher sind keine Lösungen nutzbar, die ein <thead> Element einer Tabelle voraussetzen.

Siehe auch meine weiteren Arbeitshilfen zur Technischen Dokumentation.