Yet another syntax highlighter for ScrewTurn Wiki

ScrewTurn Wiki is an excellent free wiki engine. It’s open source, runs on top of ASP.NET, supports ActiveDirectory authentication, and is super-easy to set up. Because of these qualities, I use it as the default choice for product or project related internal wikis (and yes, you can of course run it on the Internet).

What ScrewTurn does not supply out of the box is syntax highlighting for source code. What it does have however is a well-documented and simple enough plugin model that allows you to roll your own. There already is a an implementation by Tim Bellette that is contained in a single DLL and looks very OK, and another one that uses the GeShi PHP application, which is good because GeShi knows every language in the world, but requires you to set up a PHP application in addition to ScrewTurn, which might be a problem or not.

Why I choose to come up with my own syntax highlighter plugin is that a) I sometimes like building stuff and need an excuse for that and b) I really like the source code formatter that WordPress uses. As you can behold it here:

// See how nice this looks? It's got line numbers,
// alternating background, and these super-useful buttons
// to copy the whole code into the clipboard and print it
// that appear when you hover over the code.

The amazing thing about this formatter is that it is completely implemented as client-side JavaScript and CSS. Alex Gorbatchev has developed this little feat, and published it as open source. What you need to do to get code formatting onto an HTML page is to decorate a “pre” tag with a CSS class, and add links to the script files.

Letting ScrewTurn Wiki so this is quite easy. All you need to do is to write a formatter plugin. In addition to some minor infrastructure wire-up, this type of plugin lets you modify the content of a wiki article, and its title. The API for writing ScrewTurn Wiki is extremely enjoyable and well documented, deploying is a matter of seconds – you can just drop your DLL into the public/plugins directory of the web application, or even use its administrative user interface to upload new plugins into the app when you don’t have access to the server.

Usage

The markup for code in ScrewTurn Wiki is:

Text before the code
@@
// Your source code goes here
@@
Text after the code

In order to support wikis that already contain code following that syntax (and especially for one large project with 500+ pages…) this syntax is supported. However, it does not indicate which language the code is in, so that the formatter defaults to plain text; it still provides the line numbers and fancy background.

To indicate the language, add the name of the programming language as the first word of the code block. The name of the language can be any of the syntaxes supported by the SyntaxHighlighter. A single page in the wiki can contain code blocks in several programming languages.

@@ csharp
// Comment
public string Greeting = "huhu";
@@

Text between code blocks

@@ xml
<!-- Comment -->
<node>content</node>
@@

Configuration

In the admin UI of ScrewTurn Wiki, you can provide a configuration string for plugins. This one supports three configuration options:

• ScriptUrl The syntax highlighter needs to download some CSS, JavaScript, and Flash files. By default, these files are downloaded from my Dropbox (which makes quite a good poor man’s CDN). If you like to download them from somewhere else, specify the base URL in the ScriptUrl option. The best-performing way to deliver the files will be to download them onto the wiki’s web server and reference them with a relative URL.
• Theme The syntax highlighter offers some color-scheme themes. Pick one with this option; or omit it to use the default one.
• DefaultLang If no language is specified on a code block, the default language is used. Without specifying this option, no specific language is used and the code appears as plain text; specify the DefaultLang option to use another language as default.
  In this example the script files are loaded from a directory on the wiki server with the machine-absolute URL “/syntaxHighlighter/”, the white-on-black Emacs color theme is used, and the default language is C#.

  ScriptUrl=/syntaxHighlighter/;
  Theme=Emacs;
  DefaultLang=csharp
  

• CustomLang
  The syntax highlighter allows adding new javascript “brush” files in orde to support additional languages that are not included in the standard script library. *If you have not written or imported custom brush definitions, or if you don’t know what is meant by that, you do not need to set this option.*

  By default, the ScrewTurn plugin does not know about these custom languages. To use additional brush definitions, add a custom language to the configuration string, and add the name of the javascript file that implements it.

  In this example, an additional language called “magic” is added. It uses a brush file named “shBrushMagic.js”.

  CustomLang:magic=shBrushMagic.js
  

  Note that the custom brush file has to reside in the same directory as the standard brush definition files.

  You can specify multiple custom languages, and you can assign different synonyms for the same brush:

  CustomLang:magic=shBrushMagic.js;
  CustomLang:mushroom=shBrushMagic.js;
  CustomLang:slippers=shBrushSlippers.js
  

Revisions

• 1.0 Initial Release. Uses SyntaxHighlighter 2.1
• 1.1 Uses SyntaxHightlighter 3.0

Download

DOWNLOAD SINGLE DLL
Installation: Download. Log onto ScrewTurn Wiki as an admin. Go to Administration -> Providers. Under “Providers DLLs Management”, upload the DLL: done.

SOURCE CODE
C#, Visual Studio 2010 Project – Hosted on Google Code

Licensed under LGPLv3 .

Known Issues

If you’ve got a problem installing the plug-in, or it does not work as expected, please use the Google Code issue tracking system. You’ll need to log on using a Google account.

Code blocks in tables

When you try to put a code block into a table, you’ll find out that this block won’t be formatted correctly. This is not a genuine problem of this plug-in, but caused by a general limitation in ScrewTurn wiki that does not allow any formatting in table cells. The FormatterPlus plug-in by Denis Stankovski fixes this. Together with this plug-in, code blocks in tables work fine.

About Christian

Christian is a software architect/developer. He lives in Germany, reads a lot, and likes cycling.

‹ Unit testing the IAsyncResult pattern

Chocolate-covered unit tests ›

Tagged with: code formatting, ScrewTurn, wiki
Posted in Coding, Tools