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:

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.