Adobe RoboHelp: Using JavaScript Syntax Highligher
Contents
If you write technical help, such as help for developers, there is a good chance that you are familiar with Alex Gorbatchev’s SyntaxHighligher. This nifty JavaScript allows you to easily embed example code with syntax highlighting in web pages. In this tutorial I show you how you can get the SyntaxHighlighter to work in WebHelp created with RoboHelp. The steps in this article work on RoboHelp 9 and later. With the exception of the search highlighting fix, the instructions from this page will work on RoboHelp and prior as well.
Add SyntaxHighligher to a Project
First, you need to download the SyntaxHighlighter files from http://alexgorbatchev.com/SyntaxHighlighter/download/. It doesn’t matter which version you pick, as RoboHelp supports all versions.
When you downloaded the files, go to the folder scripts. From this folder, add the following files as baggage files to your product:
- shCore.js
- shBrush<your language>.js
You must add the brush file for every language you want to use for syntax highlighting. For example, if you want to use syntax highlighting for JavaScript and CSS, add the following files as baggage files:
- shBrushCss.js
- shBrushJScript.js
Update your CSS
Now that the scripts are added to the project, you must add the CSS styles for the syntax highlighter to your project. The syntax highlighter contains several CSS files for different stylings in the folder styles. You need only one style sheet and the default shCoreDefault.css is always a good choice.
The best way to make the styles available in your project is to copy one of the style sheets into your own style sheet.
- Open the file shCoreDefault.css with a text editor.
- Select the contents of the file and copy it.
- Find the CSS file of your project and open it with a text editor.
- At the bottom of your CSS file, paste the contents of shCoreDefault.css.
- Save your style sheet.
- The styles are now available in your style sheet.
Note: if you use the RoboHelp CSS editor, the editor may corrupt the styles of the syntax highlighter. If that happens, remove the styles of the syntax highlighter and add them again.
Alternatively, you can link the syntax highlighter style sheet to your topics. But that means that some topics will use multiple style sheets. And RoboHelp doesn’t work well with multiple style sheet per topic, so I advise you to follow the steps above to copy the styles into your own style sheet.
Add code to your topic
Now that your project is set up, you can add code snippets to your topics. This consists in two steps: (1) Add code snippets and (2) add the syntax highlighter script.
Add code snippets
You add a code snippet to a topic as follows:
- Open the topic.
- Switch to HTML mode.
- Add the following text to your topic:
<pre class="brush: css"> </pre>
- Change the text css with the code you want to add in the snippet.
- Paste the code inside the tags. In this example, I added some CSS markup:
- Save the topic.
The code snippet has been added. To enable highlighting, you now have to add the required scripts.
Add the syntax highlighter scripts
You can choose to add the syntax highlighter scripts in every topic, but you can also make the scripts available through the header or footer of your master page. In this tutorial, I will show you how to add the code to the topic itself.
-
- Open the topic that contains the code snippet.
- Switch to HTML mode.
- Just after the
<body>tag, add the following text:
<script type="text/javascript" src="/shCore.js"></script> <script type="text/javascript" src="/shBrushCss.js"></script> <script type="text/javascript">//<![CDATA[ SyntaxHighlighter.defaults['toolbar'] = false; SyntaxHighlighter.all(); //]]></script>
- Amend the path to the scripts. The above code assumes the script files are in the same folder as your topic. For more information about paths, see the this tutorial.
- Change shBrushCss.js to point to the file with the brush of the language of your code snippet. If you use code snippets with different languages in one topic, you must add a link to the brush file of every language. Simply add a new line for every language.
- Save your changes.
If you switch to Design mode, your topic will look like this:
Generate the Help
You are now set to generate your output. There are no special instructions or requirements for your output. After you generate, don’t forget to patch RoboHelp’s search function. The result:
Fix the RoboHelp Search
Once you generated, there is only one thing left to do: change the RoboHelp search highlighting. This is required because search highlighting may break the syntax highlight. To fix this, follow these steps:
- Open whtopic.js with a text editor.
- Search for the function
doHighLightDomElement. (Line 489 in RoboHelp 11.) - Inside this function, find the code
if ( doesTagRecursiveProcess( node ) )(Line 506 in RoboHelp 11.) - Place the following text before the line you found in the previous step:
if(node.nodeName != "PRE") { - Now find the code
doHighLightDomElement( a_aSuspendedNodes, node );(Line 513 in RoboHelp 11.) - Add a closing bracket
}behind this line. The function must now look like this:
- Save the file.
The search function is patched. Search results in code snippets will be highlighted in Chrome and Internet Explorer. Unfortunately, code snippets are longer be highlighted in Firefox, but searching won’t break the syntax highlighting either. (And Firefox still finds search results in code snippets, only the highlighting is removed.)
Keshav Arora
The download link given in this post points to a page that is no longer available on http://alexgorbatchev.com/ and throws a 404 error. The download link given on http://alexgorbatchev.com points to GitHub (https://github.com/syntaxhighlighter/syntaxhighlighter). At this page, master branch does not the scripts and stylesheets. The “dev.bak” branch contains these files but they are not working fine. Finally, I downloaded the Syntax Highlighter from https://www.nuget.org/packages/SyntaxHighlighter/3.0.83 and it worked fine.
Also, if ” JavaScript error: XregExp not defined” error is coming then please follow the steps given at http://blog.blakesimpson.co.uk/read/5-installing-syntaxhighlighter-error-xregexp-not-defined
Marisa
It looks like a lot of folks referenced this as being the best instructions around for a time! However, unfortunately with some RoboHelp updates, it looks like they aren’t doing the trick now.
Do you think you’ll revisit these steps to update them? 😀