1ikiwiki(1) General Commands Manual ikiwiki(1)
2
6 ikiwiki - a wiki compiler
7
9 ikiwiki [options] source destination
10 ikiwiki --setup setupfile [options]
12
14 ikiwiki is a wiki compiler. It builds static HTML pages for a wiki,
15 from source in the ikiwiki/Markdown language (or others), and writes it
16 out to destination.
17 Note that most options can be shortened to single letters, boolean
19 flags such as --verbose can be negated with --no-verbose, and options
20 such as --verbose can also be spelled like -verbose.
21
23 These options control the mode that ikiwiki operates in.
24 --refresh
26 Refresh the wiki, updating any changed pages. This is the
27 default behavior if no other mode action is specified (but note
28 that --setup is a mode action, and has different default behav‐
29 ior).
30 --rebuild
32 Force a rebuild of all pages.
33 --setup setupfile
35 Load options from the given setup file. If no other mode action
36 is specified, generate wrappers and rebuild the wiki, as if
37 --rebuild --wrappers were used. If you only want to build any
38 changed pages, you can use --refresh with --setup.
39 --changesetup setupfile
41 Reads the setup file, adds any configuration changes specified
42 by other options, and writes the new configuration back to the
43 setup file. Also updates any configured wrappers. In this mode,
44 the wiki is not fully rebuilt, unless you also add --rebuild.
45 Example, to enable some plugins:
47 ikiwiki --changesetup ~/ikiwiki.setup --plugin goodstuff
49 --plugin calendar
50 --dumpsetup setupfile
52 Causes ikiwiki to write to the specified setup file, dumping out
53 its current configuration.
54 --wrappers
56 If used with --setup --refresh, this makes it also update any
57 configured wrappers.
58 --clean
60 This makes ikiwiki clean up by removing any files it generated
61 in the destination directory, as well as any configured wrap‐
62 pers, and the .ikiwiki state directory. This is mostly useful if
63 you're running ikiwiki in a Makefile to build documentation and
64 want a corresponding clean target.
65 --cgi Enable CGI mode. In cgi mode ikiwiki runs as a cgi script, and
67 supports editing pages, signing in, and registration.
68 To use ikiwiki as a CGI program you need to use --wrapper or
70 --setup to generate a wrapper. The wrapper will generally need
71 to run suid 6755 to the user who owns the source and destination
72 directories.
73 --wrapper [file]
75 Generate a wrapper binary that is hardcoded to do action speci‐
76 fied by the other options, using the specified input files and
77 destination directory. The filename to use for the wrapper is
78 optional.
79 The wrapper is designed to be safely made suid and be run by
81 untrusted users, as a post-commit hook, or as a CGI.
82 Note that the generated wrapper will ignore all command line
84 parameters.
85 --aggregate
87 If the plugins/aggregate plugin is enabled, this makes ikiwiki
88 poll configured feeds and save new posts to the srcdir.
89 Note that to rebuild previously aggregated posts, use the
91 --rebuild option along with this one. --rebuild will also force
92 feeds to be polled even if they were polled recently.
93 --render file
95 Renders a single file, outputting the resulting html. Does not
96 save state, so this cannot be used for building whole wikis, but
97 it is useful for previewing an edited file at the command line.
98 Generally used in conjunction with --setup to load in a wiki's
99 setup:
100 ikiwiki --setup ~/ikiwiki.setup --render foo.mdwn
102 --post-commit
104 Run in post-commit mode, the same as if called by a post-commit
105 hook. This is probably only useful when using ikiwiki with a
106 web server on one host and a repository on another, to allow the
107 repository's real post-commit hook to ssh to the web server host
108 and manually run ikiwiki to update the web site.
109 --version
111 Print ikiwiki's version number.
112
114 These options configure the wiki. Note that plugins can add additional
115 configuration options of their own. All of these options and more
116 besides can also be configured using a setup file.
117 --wikiname name
119 The name of the wiki, default is "wiki".
120 --templatedir dir
122 Specify the directory that templates are stored in. Default is
123 /usr/share/ikiwiki/templates, or another location as configured
124 at build time. If the templatedir is changed, missing templates
125 will still be searched for in the default location as a fall‐
126 back. Templates can also be placed in the "templates/" subdirec‐
127 tory of the srcdir.
128 Note that if you choose to copy and modify ikiwiki's templates,
130 you will need to be careful to keep them up to date when upgrad‐
131 ing to new versions of ikiwiki. Old versions of templates do not
132 always work with new ikiwiki versions.
133 --underlaydir dir
135 Specify the directory that is used to underlay the source direc‐
136 tory. Source files will be taken from here unless overridden by
137 a file in the source directory. Default is /usr/share/iki‐
138 wiki/basewiki or another location as configured at build time.
139 --wrappermode mode
141 Specify a mode to chmod the wrapper to after creating it.
142 --wrappergroup group
144 Specify what unix group the wrapper should be owned by. This can
145 be useful if the wrapper needs to be owned by a group other than
146 the default. For example, if a project has a repository with
147 multiple committers with access controlled by a group, it makes
148 sense for the ikiwiki wrappers to run setgid to that group.
149 --rcs=svn|git|.., --no-rcs
151 Enable or disable use of a revision_control_system.
152 The source directory will be assumed to be a working copy, or
154 clone, or whatever the revision control system you select uses.
155 In CGI mode, with a revision control system enabled, pages
157 edited via the web will be committed.
158 No revision control is enabled by default.
160 --svnrepo /svn/wiki
162 Specify the location of the svn repository for the wiki.
163 --svnpath trunk
165 Specify the path inside your svn repository where the wiki is
166 located. This defaults to trunk; change it if your wiki is at
167 some other path inside the repository. If your wiki is rooted at
168 the top of the repository, set svnpath to "".
169 --rss, --norss
171 If rss is set, ikiwiki will default to generating RSS feeds for
172 pages that inline a blog.
173 --allowrss
175 If allowrss is set, and rss is not set, ikiwiki will not default
176 to generating RSS feeds, but setting rss=yes in the inline
177 directive can override this default and generate a feed.
178 --atom, --noatom
180 If atom is set, ikiwiki will default to generating Atom feeds
181 for pages that inline a blog.
182 --allowatom
184 If allowatom is set, and rss is not set, ikiwiki will not
185 default to generating Atom feeds, but setting atom=yes in the
186 inline directive can override this default and generate a feed.
187 --pingurl URL
189 Set this to the URL of an XML-RPC service to ping when an RSS
190 feed is updated. For example, to ping Technorati, use the URL
191 http://rpc.technorati.com/rpc/ping
192 This parameter can be specified multiple times to specify more
194 than one URL to ping.
195 --url URL
197 Specifies the URL to the wiki. This is a required parameter in
198 CGI mode.
199 --cgiurl http://example.org/ikiwiki.cgi
201 Specifies the URL to the ikiwiki CGI script wrapper. Required
202 when building the wiki for links to the cgi script to be gener‐
203 ated.
204 --historyurl URL
206 Specifies the URL to link to for page history browsing. In the
207 URL, "[[file]]" is replaced with the file to browse. It's common
208 to use ViewVC for this.
209 --adminemail you@example.org
211 Specifies the email address that ikiwiki should use for sending
212 email.
213 --diffurl URL
215 Specifies the URL to link to for a diff of changes to a page. In
216 the URL, "[[file]]" is replaced with the file to browse,
217 "[[r1]]" is the old revision of the page, and "[[r2]]" is the
218 new revision. It's common to use ViewVC for this.
219 --exclude regexp
221 Specifies a rexexp of source files to exclude from processing.
222 May be specified multiple times to add to exclude list.
223 --include regexp
225 Specifies a rexexp of source files, that would normally be
226 excluded, but that you wish to include in processing. May be
227 specified multiple times to add to include list.
228 --adminuser name
230 Specifies a username of a user (or, if openid is enabled, an
231 openid) who has the powers of a wiki admin. Currently allows
232 locking of any page, and banning users, as well as powers
233 granted by enabled plugins (such as [[moderating comments|plug‐
234 ins/moderatedcomments]] and plugins/websetup. May be specified
235 multiple times for multiple admins.
236 For an openid user specify the full URL of the login, including
238 "http://".
239 --plugin name
241 Enables the use of the specified plugin in the wiki. Note that
242 plugin names are case sensitive.
243 --disable-plugin name
245 Disables use of a plugin. For example "--disable-plugin
246 htmlscrubber" to do away with HTML sanitization.
247 --libdir directory
249 Makes ikiwiki look in the specified directory first, before the
250 regular locations when loading library files and plugins. For
251 example, if you set libdir to "/home/you/.ikiwiki/", you can
252 install a foo.pm plugin as "/home/you/.ikiwiki/IkiWiki/Plug‐
253 in/foo.pm".
254 --discussion, --no-discussion
256 Enables or disables "Discussion" links from being added to the
257 header of every page. The links are enabled by default.
258 --numbacklinks n
260 Controls how many backlinks should be displayed at the bottom of
261 a page. Excess backlinks will be hidden in a popup. Default is
262 10. Set to 0 to disable this feature.
263 --userdir subdir
265 Optionally, allows links to users of the wiki to link to pages
266 inside a subdirectory of the wiki. The default is to link to
267 pages in the toplevel directory of the wiki.
268 --htmlext html
270 Configures the extension used for generated html files. Default
271 is "html".
272 --timeformat format
274 Specify how to display the time or date. The format string is
275 passed to the strftime(3) function.
276 --verbose, --no-verbose
278 Be verbose about what is being done.
279 --syslog, --no-syslog
281 Log to syslog(3).
282 --usedirs, --no-usedirs
284 Toggle creating output files named page/index.html (default)
285 instead of page.html.
286 --prefix-directives, --no-prefix-directives
288 Toggle new '!'-prefixed syntax for preprocessor directives.
289 ikiwiki currently defaults to --prefix-directives.
290 --w3mmode, --no-w3mmode
292 Enable w3mmode, which allows w3m to use ikiwiki as a local CGI
293 script, without a web server.
294 --sslcookie
296 Only send cookies over an SSL connection. This should prevent
297 them being intercepted. If you enable this option then you must
298 run at least the CGI portion of ikiwiki over SSL.
299 --gettime, --no-gettime
301 Extract creation and modification times for each new page from
302 the the revision control's log. This is done automatically when
303 building a wiki for the first time, so you normally do not need
304 to use this option.
305 --set var=value
307 This allows setting an arbitrary configuration variable, the
308 same as if it were set via a setup file. Since most commonly
309 used options can be configured using command-line switches, you
310 will rarely need to use this.
311 --set-yaml var=value
313 This is like --set, but it allows setting configuration vari‐
314 ables that use complex data structures, by passing in a YAML
315 document.
316
318 ikiwiki --setup my.setup
319 Completely (re)build the wiki using the specified setup file.
321 ikiwiki --setup my.setup --refresh
323 Refresh the wiki, using settings from my.setup, and avoid
324 rebuilding any pages that have not changed. This is faster.
325 ikiwiki --setup my.setup --refresh --wrappers
327 Refresh the wiki, including regenerating all wrapper programs,
328 but do not rebuild all pages. Useful if you have changed some‐
329 thing in the setup file that does not need a full wiki rebuild
330 to update all pages, but that you want to immediately take
331 effect.
332 ikiwiki --rebuild srcdir destdir
334 Use srcdir as source and build HTML in destdir, without using a
335 setup file.
336 ikiwiki srcdir destdir
338 Use srcdir as source to update changed pages' HTML in destdir,
339 without using a setup file.
340
342 CC
343 This controls what C compiler is used to build wrappers. Default
345 is 'cc'.
346 CFLAGS This can be used to pass options to the C compiler when building
348 wrappers.
349
351 ikiwiki-mass-rebuild(8)
352 ikiwiki-update-wikilist(1)
354 ikiwiki-transition(1)
356
358 Joey Hess <joey@ikiwiki.info>
359 ikiwiki(1)