I upgraded to the new SyntaxHighlighter today in preparation for a couple of posts that hopefully I’ll make by the end of the month. (Topics: explaining and condemning default instances (VB .NET “feature”), a neat discussion of SRP that was generated from an XVBT post, and a possible series on creating design-time experiences for WPF controls.) My installation experience was less than desirable.

There is no documentation for installation on the SyntaxHighlighter wiki, or if there is documentation it’s not linked from the main page. There’s barely documentation for the features as well. There’s four or five “look what I can do” pages that demonstrate its features, but no pages that tell you how you can do these fancy things too. There’s some cool features, but the only way I can figure out how to make them work is to dive into the JS myself. Lame. For example, on the demo page there’s a demonstration of highlighting lines; what’s the syntax for this? Also, what’s the “html-script” attribute do? How am I supposed to find it.

Anyway, here’s how to install SyntaxHighlighter based on my experience:

1. Copy the scripts, styles, and src directories to a location on your server. (Maybe src isn’t required; I included it just in case.)
2. On the page that you want to highlight code, make sure to import brushes, import styles, and call the magic code that does the work. For example, if you want to highlight some C# code, your page header needs to include:

   <script type="text/javascript" src="scripts/shCore.js"></script>
   <script type="text/javascript" src="scripts/shBrushCSharp.js"></script>
   <link type="text/css" rel="stylesheet" href="styles/shCore.css"/>
   <link type="text/css" rel="stylesheet" href="styles/shThemeDefault.css"/>
   <script type="text/javascript">
       SyntaxHighlighter.config.clipboardSwf = 'scripts/clipboard.swf';
       SyntaxHighlighter.all();
   </script>
   

   Do not load anything before shCore.js, or you will get errors.

That’s all I would have needed to have an effortless install of SyntaxHighlighter; it’s a shame the documentation isn’t there. Before you get all “it’s a wiki: do it yourself” high-and-mighty on me, go try to add it yourself. You can’t. The leaf pages of the wiki are editable, but I can’t seem to find a way to edit the main page. Perhaps there’s a way to add a new page, but there’s no way to enumerate the pages on that wiki so without a link from the main page any new “Installation” page is going to be invisible. So I would, but I can’t. Hopefully, someone will eventually create an installation page so silly people like me don’t have to spend 20 minutes discovering that the order of the brushes really matters. Or maybe it’ll never happen and this page will be the only documentation for it. Who knows.