Part 2: How to highlight code with SyntaxHighlighter in MadCap Flare 4

Posted on June 5, 2009

8


Note: See update to this post for MadCap Flare 6 by Eilan Jung.

This works in all online outputs, CHM and WebHelp. Its a full JavaScript syntax highlighter with a nifty Copy to clipboard function.64 Capture

Download and prepare. Download SyntaxHighlighter. Read the Usage instructions in the Wiki, and language aliases. Note the attributes the <pre> tag needs. An important but small portion of code you need to get it to work is actually in a comment posted by a user on the wiki – not in the official usage instructions ( See August 7 2007, by klein.stephane ), which I will include later in this post. After download completes, unpack the style sheets and scripts into a location in your project. You should end up with something like the following:

Create folders for the SyntaxHighlighter files in your project.

Set up a stylesheet link in your Flare stylesheet. This is where it differs a bit from the usage instructions. Open your project stylesheet, the one you keep in Flare for your topics. (for example, Styles.css ;   not the one that came with the plug-in.) In the Style Sheet Editor, create a stylesheet link to SyntaxHighlighter.css. In case, you don’t know where it is, the following tip should help.

How to create a stylesheet liink

Paste the following code into your Flare topic header (the topic you want syntax highlighting), anywhere between the <head> </head> tags.

The following code includes two brushes for highlighting XML and C# code. Replace with other brushes as necessary.

<script language="javascript" src="js/shCore.js">
</script>

<script language="javascript" src="js/shBrushCSharp.js"></script>  

<script language="javascript" src="js/shBrushXml.js"></script> 

<script language="javascript">  dp.SyntaxHighlighter.ClipboardSwf = '/js/clipboard.swf';
dp.SyntaxHighlighter.HighlightAll('code');</script>
<script language="javascript">
window.onload = function () {
    dp.SyntaxHighlighter.ClipboardSwf = '/js/clipboard.swf';
    dp.SyntaxHighlighter.HighlightAll('code');
}
</script>

Highlight some code. Find the code you want syntax highlighted in your topic, SQL, C#, XML – its your choice. Open the topic. Paste the code snippet. With the style picker enclose the code snippet in a <pre> tag. Switch to the Text Editor view, or in Notepad, type the right attributes as per usage instructions.

For example for some XML/XHTML code it might look like this in your code editor.

<pre name=”code” class=”xml”>

  <fruit>Pink guavas</fruit>

</pre>

Finally, build the project for a WebHelp or CHM target.

What about different types of code? Use the right SyntaxHighlighter language alias to highlight different types of code. Change the different highlighting brushes in the <head> </head>. The call to a syntax highlighting brush looks like this.

<script language="javascript" src="js/shBrushCSharp.js"></script>

Tip

For code blocks with multiple lines, enclose in one pre tag block. Use the line break key (SHIFT + ENTER) combination to insert a line break within a <pre> tag. This has the advantage of retaining multiple lines of  code blocks together under one pre tag. Preview the topic in WebHelp or CHM Help.

Variations

Instead of putting highlighting scripts in each topic, move syntax highlighting code into a Master Page. Edit the path of relocated scripts to make sure they match. Then build.

Convert syntax highlighted code into a reusable snippet. Enclose the correct pre tag with the snippet. This helps you reuse the code snippet later in other topics.

Tagged: ,
Posted in: Coding, Styles/Typography