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 files, 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 ## configuration
  15
  16 Nothing will be highlighted by default.
  17 To enable syntax highlighting, use the `tohighlight` setting in your
  18 setup file to control which files should be syntax highlighted.
  19 Here is a typical setting for it, enabling highlighting for files
  20 with the extensions .c, etc, and also for any files named "Makefile".
  21
  22         tohighlight => ".c .h .cpp .pl .py Makefile:make",
  23
  24 It knows what language to use for most filename extensions (see
  25 `/etc/highlight/filetypes.conf` for a partial list), but if you want to
  26 bind an unusual filename extension, or any file without an extension
  27 (such as a Makefile), to a language, you can do so by appending a colon
  28 and the name of the language, as illustrated for Makefiles above.
  29
  30 ## embedding highlighted code
  31
  32 To embed highlighted code on a page, you can use the
  33 [[ikiwiki/directive/format]] directive.
  34
  35 For example:
  36
  37         \[[!format c """
  38         void main () {
  39                 printf("hello, world!");
  40         }
  41         """]]
  42
  43 You can do this for any of the extensions/filenames enabled in
  44 `tohighlight`.
  45
  46 ## colors
  47
  48 The colors etc used for the syntax highlighting are entirely configurable
  49 by CSS. See ikiwiki's [[style.css]] for the defaults.
  50
  51 ## limitations
  52
  53 With this plugin enabled, source files become full-fledged ikiwiki pages,
  54 which means they can include [[WikiLinks|ikiwiki/wikilink]] and
  55 [[directives|ikiwiki/directive]] like any other page can, and are also
  56 affected by the [[smiley]] plugin, if it is enabled. This can be
  57 annoying if your code accidentially contains things that look like those.
  58
  59 On the other hand, this also allows your syntax highlighed
  60 source code to contain markdown formatted comments and hyperlinks
  61 to other code files, like this:
  62
  63         /* \[[!format mdwn """
  64                 This comment will be formatted as *markdown*!
  65
  66                 See \[[bar.h]].
  67         ""]] */
  68
  69 ## security
  70
  71 This lets anyone who can edit a page in your wiki also edit
  72 source code files that are in your wiki. Use appropriate caution.