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.

Advertisements
About

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

Tagged with: , ,
Posted in Coding, Tools
43 comments on “Yet another syntax highlighter for ScrewTurn Wiki
  1. ChrisW says:

    The DLL download link is broken 24.3.10 19:44GMT 😦

    • Christian says:

      Sorry, I moved the download link to Google Code, but then I realized they don’t let you change the content of files once you’ve uploaded them. Which does not fly so well with the auto-update feature of ScrewTurn. The link is now back.

      • ChrisW says:

        yep, working now thanks. Now Alex’s site is down!

        Does the highlighter support SQL ?
        Cheers
        Chris

      • ChrisW says:

        doh ! answer yes. I should have just tried it first. This is fantastic. Thanks !

  2. Rob says:

    Superb plugin. Is there a way to remove the line numbers? When you copy the code from the page it grabs the numbers as well. Thanks!

    • Christian says:

      Currently there’s no option to disable thre line numbers, but: when you hover over the code block, you see a layover appear on the top-right corner. The second button copies the content of the code block directly to the clipboard. Or: the first button opens a new window with just the unformatted code, from where you can copy it.

      • Rich Hemmings says:

        Apologies for resurrecting an old topic, buut…

        My overlay doesn’t appear?! 😥
        I’ve ensure the latest version – 3.0.83

        I get the overlay while hovering over the code on this page, but not in my wiki, I just see a little green block with a “?” mark in it?

        My config:
        ScriptUrl=/syntaxhighlighter_3.0.83/;
        Theme=Default;
        DefaultLang=sql;

        Leads me to think its something in my config that I haven’t set up properly?

        Any help is greatly appreciated.

        Rich

  3. Ricky says:

    Thanks for your wonderful work, it works great!
    But when i setup the DefaultLang with csharp, Screwturn just shows no effect. Any idea?

  4. Ricky says:

    Thanks for your rapid reply.
    I figured out why the DefalutLang didn’t work in my case.
    I set the configuration string in the “HTML HEAD” section of the layout page instead of the provider page, like:

    ScriptUrl=”/SyntaxHighliter”;
    DefaultLang=”csharp”;

    this script works perfectly but apparently is my misunderstanding of the configuration.
    Thanks again for your help.

  5. jabits says:

    Very Nice! Thank you.

  6. […] Yet another syntax highlighter for ScrewTurn Wiki « greenicicle 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. (tags: dev dotnet wiki screwturn) […]

  7. Chris says:

    Do you have an escape string in the library ? i.e is it possible to escape @@.

    @@ is commonly used for MS SQL server variables – so now anywhere I have SQL code with a system variable the code highlighting breaks.

    thanks
    Chris

    • Christian says:

      Hmm. This problem lies one level deeper: ScrewTurn transforms the wiki markup content to HTML in multiple steps. The syntax highlighter kicks in _after_ ScrewTurn has already converted “@@” delimited sequences to “<pre>” HTML tags. The problem SQL expressions that use @@ as a prefix would need to be fixed _before_ ScrewTurn processes content.

      This can be done via a formatter plug-in that runs in an earlier phase. It should be fairly easy. How would you like the wiki formatted content to look? Please provide an example.

      • David says:

        So, is there a work around, or do we wait for something to be changed???

      • Christian says:

        Hi David,

        you’re also affected by the problem? What I tried to express was: ScrewTurn uses the “@@” sequence to delimit code blocks, see here. When your code contains a SQL Server function like @@TRANCOUNT, ScrewTurn thinks it the code block ends. This happens with or without the syntax highlighter.

        The problem would need to be tackled by adding another formatting extension. There are two ways one could go:

        • Use an escape sequence within the code; e.g. @@@TRANCOUNT. Thinking about that, I don’t like it too much; you’d have to re-format code you copy and paste into wiki articles.
        • Use a different delimiter like @sql@. @@ sequences inside these blocks would be ignored.

        I’d prefer the second option, would this solve your problem?

  8. Chris says:

    Hi, I think either of the options you mention is ok. The ideal solution would be that you could still copy + paste the code into the editor but I can see that this would be a challenge to handle.

    I personally don’t like typing so the shorter the escape sequence the better (for me !)

    Thanks for your help and thanks for a great plugin.

    rgds
    Chris

  9. Luke says:

    Is the plugin supposed to support custom brushes, as the original script does? I’ve created a custom brush, shBrushMagic.js, and placed in the the folder with the rest of the brushes. I then put:
    @@ magic
    CODE CODE CODE
    @@
    in to the page. However, the “magic” keyword displays and the plain text brush is used. It should be easy enough to treat the keyword dynamically instead of hard-coding. Or, maybe, I’ve done something incorrectly?
    Configuration:
    ScriptURL=/syntaxHighlighter/;
    Theme=Eclipse;

    • Christian says:

      Ah, I’ve waited for that question. In fact, I’ve made a design mistake: detecting an optional first word in arbitrary text makes restricting the choice of words a necessity. I should have gone for a control sequence with defined delimiters from the start. On the other hand, I wanted to make uage as easy.as possible, and optimize further mainstream use case (the whole thing has been an internal project).

      You did not do anything wrong, and you’re right, supporting custom brushes is easy to implement. Would putting a custom brush definition in, say, double curly braces solve the limitation for you?

    • Christian says:

      I’ve added the option to add custom brushes via the plug-in configuration. See http://code.google.com/p/greeniciclescrewturnsyntaxhighlighter/wiki/Configuration for details.

  10. Bill says:

    Hello, I am having some trouble with xml code — when I enclose the code like:
    @@ xml

    test text

    @@

    It renders out as

    1
    2 test text
    3

    It seems to be adding text in front of each line and eliminating indentations. Am I using it wrong or is it a bug or possibly caused by something else?

    • Bill says:

      the comment removed xml tags, here I go again…
      code was like:

      @@ xml
      <test>
      test text
      </test>
      @@

      It renders out as

      1 <BR><test>
      2 <BR>test text
      3 <BR></test>

    • Christian says:
      This is how your code should look like:

      The numbers on front of the lines are line numbers. To view, copy, or print the source code without the line numbers, use the buttons that appear when you hover over the source code block.

      Indentation is not changed by the syntax highlighter. It does not mess up your indentation – to verify that it is exactly like you’ve entered it, use the hovering buttons. On the other hand, it does not provide automatic indentation of XML. Pretty-printing XML would be a nice feature, but it’s not in the scope of the plug-in currently.

      Hope this helps,
      Christian

      • Luke says:

        He probably has his code within a list:
        # Entry 1
        #* @@ CPP
        Code
        Code

        @@

        This will result in <br/&gr tags being added. It’s not a problem with your plugin. However, moving your formatter to an earlier stage of the render might fix the issue…. and it might not.

  11. homebunny says:

    Hi,

    I would like to use following syntax:

    @@ SQL SELECT * FROM INVENTJOURNALTRANS
    WHERE (DATAAREAID = N’?pDATAAREAID?’)
    @@

    But the nowiki tags are not supported by your plugin and i’m getting strange results …

    • Christian says:

      Hi homebunny,

      this is what your text looks on my wiki:
      Formatted SQL Text

      … looks OK to me. But I don’t see any nowiki tags either – is something missing from the code you’ve posted?

  12. Couga says:

    Hi Christian,

    Is it possible to get the DLL donwload from other source than dropbox. The firewall in my company prevents me from getting the DLL.

    Couga

  13. Schommi says:

    Great tool Christian – works like a charm right out of the box. Tanks alot!

    Cheers,
    Schommi

  14. Grant says:

    Hello Christian. I’m trying to add ScriptUrl to the configuration string but I can’t get it to ‘see’ the files on my server. I placed your DLL file in the Plugins directory and the plugin works great.

    But when I copied the extra files into a subdirectory of the Plugins directory, which I named syntaxhighlighter_3.0.83, and then included ‘ScriptUrl=/syntaxhighlighter_3.0.83/’ in the configuration string, the code stopped being formatted. I don’t know if maybe it couldn’t find the files or I have the string wrong. I guess that’s my question to you then. Is that string wrong?

    Thanks! And thank you for a nice plugin! I have dozens of snippets of code in my wiki and they’ve always been so difficult to read…

    • Christian says:

      Hi Grant,

      the script URL is really a URL used by the client-side script, not the plugin. So when you are using a relative URL that begins with a slash (“/”), then the script files directory needs to be located at the web site root, not a subdirectory of the server. The plugins directory is not even published. If you’r ein control of the server, the easiest thing to do is to move the syntaxhighlighter script file directory to the wwwroot directory.

      • Grant says:

        Thanks Christian! I placed the syntaxhighlighter_3.0.83 directory directly under httpdocs (root) and then set ‘ScriptUrl=/syntaxhighlighter_3.0.83/’. Worked like a charm.

  15. Scott says:

    Ever since I have upgraded to 1.1 in screwturn wiki I have lost the alternating lines of gray and the over buttons. I would much rather have the style that is shown on this site.

    Was that theme taken away? what can I do?

    Thank you.

    • Christian says:

      The buttons have gone away: the SyntaxHighlighter has been changed so that you can directly copy text to th clipboard. I would think the stripes are still there – going to check when l am back at the computer.

      Are you hosting your own script files? In that case you might want to check you’ve got the current version.

      • Scott says:

        Thanks for replying on the copy text, I later found out the root syntax highlighter author removed that functionality for the double click option.

        I started to use the download script file method and ran into some problems with file placement and missing files. I tried to get it to work three times without success in getting it to work right and eventually gave up and went with the default of getting it from your dl.dropbox location.

        I had a hard time trying to get the wiki to honor the ScriptUrl property..when it did use it, it only used it for some of the files…I ended up just using what the provider expected.

        I do get one error now.

        can’t load XRegExp twice in the same frame
        [Break on this error] eval(function(p,a,c,k,e,d){e=function(…aceChild|offset|83′.split(‘|’),0,{})) shCore.js (line 17)

        That I have not been able to figure out. So last two things are the error and theme.

  16. dgcom says:

    Christian, thanks for the great plugin, but the switch to syntaxhighlighter 3.0.83 creates several problems:
    – in order to properly copy code in the clipboard, you have to double-click on the code
    – first of all, this is not obvious for a user
    – and second – it won’t work if you have edit on double-click enabled
    – if you just select and copy code, you will end up missing new line characters…

    Also “view source” icon was very helpful before, so I tried using syntaxhighlighter 2.1.382 with plugin version 1.1 and things seems to work except missing “copy to clipboard” button – any idea what else might break?

    I’m going to try asking SyntaxHighlighter’s author to bring back “view source” icon.

    Adding tooltip explaining double-click option might help too.

  17. Michal says:

    Hi,
    would it be possible to use different syntax for this plugin? ie: <code lang=”C#” highlight=”2,5″> … </code> This will solve the problem with @@ and also allowed to define other configurations.

    • Christian says:

      It’s not been made to support multiple syntaxes, sorry. I can only invite you to grab the source code and adapt it; the whole thing is quite easy.

  18. Chad says:

    For some reason I cant seem to get the configuration screen to come up. The plug-in shows up in the delete dialog but it doesnt show up in the format providers list? Is there anything that im doing wrong? I have added the dll to the plugin directory and past that I cant get to the config setting to add them. Any help?

    • Have you uploaded the dll via STW’s ‘add a provider’ section in the admin pages? The files should be in the directory as instructed, and the dll uploaded via the management screen as mentioned. Please expand on what you’re expecting to see – “configuration screen”?

  19. Learn to make use of Search engine optimisation WP Plugin…

    […]Yet another syntax highlighter for ScrewTurn Wiki « greenicicle[…]…

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: