Add underlay plugin
[ikiwiki.git] / doc / plugins / contrib / underlay.mdwn
1 [[!template id=plugin name=underlay author="[[Simon_McVittie|smcv]]"]]
2 [[!tag type/useful]]
3
4 This plugin adds an `add_underlays` option to the `.setup` file.
5 Its value is a list of underlay directories whose content is added to the wiki.
6
7 Multiple underlays are normally set up automatically by other plugins (for
8 instance, the images used by the [[plugins/smiley]] plugin), but they can also be
9 used as a way to pull in external files that you don't want in revision control,
10 like photos or software releases.
11
12 Directories in `add_underlays` should usually be absolute. If relative, they're
13 interpreted as relative to the parent directory of the basewiki underlay, which
14 is probably not particularly useful in this context.
15
16 Please feel free to add this plugin to ikiwiki if it seems like a good
17 thing to have. See the 'underlay' branch in my git repository.
18
19     #!/usr/bin/perl
20     package IkiWiki::Plugin::underlay;
21     # Copyright © 2008 Simon McVittie <http://smcv.pseudorandom.co.uk/>
22     # Licensed under the GNU GPL, version 2, or any later version published by the
23     # Free Software Foundation
24
25     use warnings;
26     use strict;
27     use IkiWiki 2.00;
28
29     sub import {
30         hook(type => "getsetup", id => "underlay",  call => \&getsetup);
31         hook(type => "checkconfig", id => "underlay", call => \&checkconfig);
32     }
33
34     sub getsetup () {
35         return
36                 plugin => {
37                         safe => 0,
38                         rebuild => undef,
39                 },
40                 add_underlays => {
41                         type => "string",
42                         default => [],
43                         description => "extra underlay directories to add",
44                         advanced => 1,
45                         safe => 0,
46                         rebuild => 1,
47                 },
48     }
49
50     sub checkconfig () {
51         return unless exists $config{add_underlays};
52
53         foreach my $dir (@{$config{add_underlays}}) {
54                 add_underlay($dir);
55         }
56     }
57
58     1;