CSS+JS Code snippets for enhancing online documentation

Many possibilities provided by HTML, CSS, and JavaScript that have long been common on websites, are not supported by technical documentation authoring tools. However, almost all authoring tools allow you to add such things on your own, which may enhance an online documentation immensely.

Here you can find a collection of ready-made solutions and code snippets that may add some value also to your own projects.

Available solutions and examples

Currently, this collection contains solutions and examples for the following applications:

Return to top of page button in online documentation

Limited text width and automatic hyphenation in online documentation

Multicolumn lists and sections in online documentation

Two synchronous columns in online documentation

Marginalia in online documentation

Tiles in online documentation

Tabs in online documentation

Expandable sections in online documentation (dropdowns, toggles)

Expandable images in online documentation (thumbnails)

Zoomable images in online documentation

Filters in online documentation

Sortable, filterable, responsive tables in online documentation

Tables with a sticky header in online documentation

Tables and images that are sticky as a whole in online documentation

Code boxes with syntax highlighting in online documentation

Mathematical formulas in online documentation

Styles for notes and warnings in online documentation

Styles for lists in online documentation

Styles for highlighting in online documentation

Styles for keyboard keys in online documentation

Automatic marking of external links in online documentation

Styles for best-possible print results in online documentation

Subtle animation effects in online documentation

Automatic mini TOC with Scroll Spy in online documentation

Feedback and rating functions in online documentation

Requirements

To successfully apply the solutions shown to your own projects, you don't need to know HTML, CSS, and JavaScript in detail. Some very basic knowledge, together with the code snippets presented here, will do. The only things that you should know already are:

how HTML files are generally structured

how to insert CSS code into the head section of an HTML file or link an external CSS file in the head section of an HTML file

how to insert HTML, CSS, and JavaScript code into templates and topics in your authoring tool

how to include additional files into the output of your editorial system (not required for all solutions; if the readers of your online documentation have Internet access, you can alternatively provide the files on a web server)

Special notes on particular authoring tools

The solutions of the collection have all been tested and implemented with the authoring tool Help+Manual (this website has also been built with Help+Manual). In principle, however, it does not matter which help authoring tool or content management system you use. Only in rare cases, a particular solution may not be compatible with the output of a certain system.

Special notes on the authoring tool Madcap Flare

If you link an additional CSS file in Flare, Flare may automatically remove this link when generating the output.

Workaround: You can prevent the deletion by creating the respective statement only at runtime by using JavaScript:


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

Special notes on the authoring tool HelpNDoc

The default template used by HelpNDoc to create WebHelp is Ajax-based. As a result, JavaScript code contained in an HTML snippet is not executed when the topic is opened from the table of contents. Links to external CSS and JavaScript files in such a snippet are also ignored in this case.

Workaround: You can add hyperlinks to custom CSS and JavaScript files in a custom template in the file topics.pas.html. You can also add your own JavaScripts in the file topics.pas.html, directly below the line <% print(GetCustomJs()); %>. Together, this will look like this:


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

You can find some Examples created with HelpNDoc here (if necessary, take a look at the source code of the pages in your browser).

When generating output, HelpNDoc replaces the names of paragraph and character styles with consecutively numbered classes. Unfortunately, these are not permanently stable but may change again later when you revise the texts. Thus, it makes little sense to simply overwrite these classes in a separate CSS file.

Tables do not have a <thead> element in documents generated by HelpNDoc, even if a table header is defined in the editor. Therefore, no solutions that require a <thead> element of a table can be used.

See also my other technical documentation work aids.