73 lines
2.3 KiB
Markdown
73 lines
2.3 KiB
Markdown
[[!template id=plugin name=highlight author="[[Joey]]"]]
|
|
[[!tag type/format]]
|
|
|
|
This plugin allows ikiwiki to syntax highlight source files, using
|
|
a fast syntax highlighter that supports over a hundred programming
|
|
languages and file formats.
|
|
|
|
## prerequisites
|
|
|
|
You will need to install the perl bindings to the
|
|
[highlight library](http://www.andre-simon.de/), which in Debian
|
|
are in the [[!debpkg libhighlight-perl]] package.
|
|
|
|
## configuration
|
|
|
|
Nothing will be highlighted by default.
|
|
To enable syntax highlighting, use the `tohighlight` setting in your
|
|
setup file to control which files should be syntax highlighted.
|
|
Here is a typical setting for it, enabling highlighting for files
|
|
with the extensions .c, etc, and also for any files named "Makefile".
|
|
|
|
tohighlight => ".c .h .cpp .pl .py Makefile:make",
|
|
|
|
It knows what language to use for most filename extensions (see
|
|
`/etc/highlight/filetypes.conf` for a partial list), but if you want to
|
|
bind an unusual filename extension, or any file without an extension
|
|
(such as a Makefile), to a language, you can do so by appending a colon
|
|
and the name of the language, as illustrated for Makefiles above.
|
|
|
|
## embedding highlighted code
|
|
|
|
To embed highlighted code on a page, you can use the
|
|
[[ikiwiki/directive/format]] directive.
|
|
|
|
For example:
|
|
|
|
\[[!format c """
|
|
void main () {
|
|
printf("hello, world!");
|
|
}
|
|
"""]]
|
|
|
|
You can do this for any of the extensions/filenames enabled in
|
|
`tohighlight`.
|
|
|
|
## colors
|
|
|
|
The colors etc used for the syntax highlighting are entirely configurable
|
|
by CSS. See ikiwiki's [[style.css]] for the defaults.
|
|
|
|
## limitations
|
|
|
|
With this plugin enabled, source files become full-fledged ikiwiki pages,
|
|
which means they can include [[WikiLinks|ikiwiki/wikilink]] and
|
|
[[directives|ikiwiki/directive]] like any other page can, and are also
|
|
affected by the [[smiley]] plugin, if it is enabled. This can be
|
|
annoying if your code accidentially contains things that look like those.
|
|
|
|
On the other hand, this also allows your syntax highlighed
|
|
source code to contain markdown formatted comments and hyperlinks
|
|
to other code files, like this:
|
|
|
|
/* \[[!format mdwn """
|
|
This comment will be formatted as *markdown*!
|
|
|
|
See \[[bar.h]].
|
|
""]] */
|
|
|
|
## security
|
|
|
|
This lets anyone who can edit a page in your wiki also edit
|
|
source code files that are in your wiki. Use appropriate caution.
|