highlight: New plugin supporting syntax highlighting of pretty much anything.
[ikiwiki.git] / 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.