This plugin allows Ikiwiki to display source files complete with syntax highlighting. Files with recognized extensions (i.e. my-file.cpp) will be rendered just like any other Ikiwiki page. You can even edit your source files with Ikiwiki's editor.

Source code: highlightcode.pm

Status

Seems to work (note: not anymore, since we're no longer on ikiwiki). Here are some examples:

There are some minor issues:

  • You cannot highlight two files with the same base name. Example.c and Example.h will both try to produce Example/index.html. Hopefully in the future Ikiwiki will allow plugins to tell Ikiwiki to not strip extensions so that Example.c will render to Example.c/index.html.
  • Ikiwiki will try to process the source file looking for links. It is likely to find a few garbage ones. Allowing plugins to override the linkify hook by file type (as also required by the Mediawiki Plugin) would potentially solve this problem.
    • Dammit, it also converts links in the raw files. That makes sense; linkify is called before htmlize and we don't create the raw file until htmlize. This really needs to be fixed.

Victor May also wrote a code highlighting plugin, syntax. It seems aimed at highlighting inlined code snippets rather than entire source files.

Installation

Install the Syntax::Highlight::Engine::Kate Perl module.

cpan Syntax::Highlight::Engine::Kate

Copy highlightcode.pm into your plugins directory.

cp highlight.pm lib/IkiWiki/Plugins

Add it to the list of enabled plugins in your setup file:

add_plugins => [qw{highlightcode}],

And you're done.

Usage

All files with recognized language extensions will be rendered as if they were any other wiki page.

Supported Languages

To see the list of file extensions that Code Highlight supports, run this in your terminal:

perl -MSyntaxhlight::Engine::Kate -e 'print join "\n", \
        keys %{Syntax::Highlight::Engine::Kate->new->extensions()}'

We don't yet support all the patterns printed (for instance, we don't do Makefiles yet), but we support everything of the format *.ext. Plus patches: file.diff / file.patch.

To see what language corresponds to each extension:

perl -MSyntax::Highlight::Engine::Kate -e \
       'my $exts = Syntax::Highlight::Engine::Kate->new->extensions;
       while(my($k,$v) = each %$exts) { print "$k\t-> ".join(",",@$v)."\n"; }'

Changing Styles

By default Highlight Code applies colors with font tags. This requires zero configuration: just turn on the plugin and your code gets highlighted. Font tags are deprecated in xhtml, however, so it's probably better to use CSS. To fix this, first turn on use_css in your configuration file:

highlightcode_use_css => 1,

And then add the appropriate styles to your local.css.

Highlighting With CSS

TODO

  • Ask Ikiwiki to not strip extensions from the rendered files. I want to be able to render file.c and file.h in the same directory.
    • Q: Could targetpage help with this? A: no, it's only a library call, not a hook.
  • How should we handle files that are recognized by their full filename? Like Makefile, httpd.conf, etc?
  • Can I turn off link checking for this entire file? (a possible solution is to be able to specify custom scan/linkify routines per filetype. The Mediawiki Plugin could really use this too).
  • In XSLT, attributes and strings are much too close in color.
  • Maybe support highlighting inlined code fragments too?
  • Want to see something funny? Click on this broken link to create the page, then check out the Page Type menu. Every language extension that this plugin handles is listed as a page type! This should certainly be fixed but I don't quite know how to fix it.