doc/plugins/highlight.mdwn

   1 [[!template id=plugin name=highlight author="[[Joey]]"]]
   2 [[!tag type/format]]
   3
   4 This plugin allows ikiwiki to syntax highlight source code, using
   5 a fast syntax highlighter that supports over a hundred programming
   6 languages and file formats.
   7
   8 ## prerequisites
   9
  10 You will need to install the perl bindings to the
  11 [highlight library](http://www.andre-simon.de/), which in Debian
  12 are in the [[!debpkg libhighlight-perl]] package.
  13
  14 ## embedding highlighted code
  15
  16 To embed highlighted code on a page, you can use the
  17 [[format]] plugin.
  18
  19 For example:
  20
  21         \[[!format c """
  22         void main () {
  23                 printf("hello, world!");
  24         }
  25         """]]
  26
  27         \[[!format diff """
  28         -bar
  29         +foo
  30         """]]
  31
  32 You can do this for any extension or language name supported by
  33 the [highlight library](http://www.andre-simon.de/) -- basically anything
  34 you can think of should work.
  35
  36 ## highlighting entire source files
  37
  38 To enable syntax highlighting of entire standalone source files, use the
  39 `tohighlight` setting in your setup file to control which files should be
  40 syntax highlighted. Here is a typical setting for it, enabling highlighting
  41 for files with the extensions .c, etc, and also for any files named
  42 "Makefile".
  43
  44         tohighlight => ".c .h .cpp .pl .py Makefile:make",
  45
  46 It knows what language to use for most filename extensions (see
  47 `/etc/highlight/filetypes.conf` for a partial list), but if you want to
  48 bind an unusual filename extension, or any file without an extension
  49 (such as a Makefile), to a language, you can do so by appending a colon
  50 and the name of the language, as illustrated for Makefiles above.
  51
  52 With the plugin configured this way, source files become full-fledged
  53 wiki pages, which means they can include [[WikiLinks|ikiwiki/wikilink]]
  54 and [[directives|ikiwiki/directive]] like any other page can, and are also
  55 affected by the [[smiley]] plugin, if it is enabled. This can be annoying
  56 if your code accidentially contains things that look like those.
  57
  58 On the other hand, this also allows your syntax highlighed
  59 source code to contain markdown formatted comments and hyperlinks
  60 to other code files, like this:
  61
  62         /* \[[!format mdwn """
  63                 This comment will be formatted as *markdown*!
  64
  65                 See \[[bar.h]].
  66         ""]] */
  67
  68 Finally, bear in mind that this lets anyone who can edit a page in your
  69 wiki also edit source code files that are in your wiki. Use appropriate
  70 caution.
  71
  72 ## colors
  73
  74 The colors etc used for the syntax highlighting are entirely configurable
  75 by CSS. See ikiwiki's [[style.css]] for the defaults.