1ikiwiki(1)                  General Commands Manual                 ikiwiki(1)
2
3
4

NAME

6       ikiwiki - a wiki compiler
7

SYNOPSIS

9       ikiwiki [options] source destination
10
11       ikiwiki --setup setupfile [options]
12

DESCRIPTION

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
18       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

MODE OPTIONS

23       These options control the mode that ikiwiki operates in.
24
25       --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
31       --rebuild
32              Force a rebuild of all pages.
33
34       --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
40       --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
46              Example, to enable some plugins:
47
48               ikiwiki  --changesetup   ~/ikiwiki.setup   --plugin   goodstuff
49              --plugin calendar
50
51       --dumpsetup setupfile
52              Causes ikiwiki to write to the specified setup file, dumping out
53              its current configuration.
54
55       --wrappers
56              If used with --setup --refresh, this makes it  also  update  any
57              configured wrappers.
58
59       --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
66       --cgi  Enable  CGI  mode. In cgi mode ikiwiki runs as a cgi script, and
67              supports editing pages, signing in, and registration.
68
69              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
74       --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
80              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
83              Note  that  the  generated  wrapper will ignore all command line
84              parameters.
85
86       --aggregate
87              If the plugins/aggregate plugin is enabled, this  makes  ikiwiki
88              poll configured feeds and save new posts to the srcdir.
89
90              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
94       --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
101               ikiwiki --setup ~/ikiwiki.setup --render foo.mdwn
102
103       --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
110       --version
111              Print ikiwiki's version number.
112

CONFIG OPTIONS

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
118       --wikiname name
119              The name of the wiki, default is "wiki".
120
121       --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
129              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
134       --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
140       --wrappermode mode
141              Specify a mode to chmod the wrapper to after creating it.
142
143       --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
150       --rcs=svn|git|.., --no-rcs
151              Enable or disable use of a revision_control_system.
152
153              The source directory will be assumed to be a  working  copy,  or
154              clone, or whatever the revision control system you select uses.
155
156              In  CGI  mode,  with  a  revision  control system enabled, pages
157              edited via the web will be committed.
158
159              No revision control is enabled by default.
160
161       --svnrepo /svn/wiki
162              Specify the location of the svn repository for the wiki.
163
164       --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
170       --rss, --norss
171              If  rss is set, ikiwiki will default to generating RSS feeds for
172              pages that inline a blog.
173
174       --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
179       --atom, --noatom
180              If atom is set, ikiwiki will default to  generating  Atom  feeds
181              for pages that inline a blog.
182
183       --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
188       --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
193              This  parameter  can be specified multiple times to specify more
194              than one URL to ping.
195
196       --url URL
197              Specifies the URL to the wiki. This is a required  parameter  in
198              CGI mode.
199
200       --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
205       --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
210       --adminemail you@example.org
211              Specifies  the email address that ikiwiki should use for sending
212              email.
213
214       --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
220       --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
224       --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
229       --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
237              For  an openid user specify the full URL of the login, including
238              "http://".
239
240       --plugin name
241              Enables the use of the specified plugin in the wiki.  Note  that
242              plugin names are case sensitive.
243
244       --disable-plugin name
245              Disables   use   of  a  plugin.  For  example  "--disable-plugin
246              htmlscrubber" to do away with HTML sanitization.
247
248       --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
255       --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
259       --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
264       --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
269       --htmlext html
270              Configures  the extension used for generated html files. Default
271              is "html".
272
273       --timeformat format
274              Specify how to display the time or date. The  format  string  is
275              passed to the strftime(3) function.
276
277       --verbose, --no-verbose
278              Be verbose about what is being done.
279
280       --syslog, --no-syslog
281              Log to syslog(3).
282
283       --usedirs, --no-usedirs
284              Toggle  creating  output  files  named page/index.html (default)
285              instead of page.html.
286
287       --prefix-directives, --no-prefix-directives
288              Toggle new  '!'-prefixed  syntax  for  preprocessor  directives.
289              ikiwiki currently defaults to --prefix-directives.
290
291       --w3mmode, --no-w3mmode
292              Enable  w3mmode,  which allows w3m to use ikiwiki as a local CGI
293              script, without a web server.
294
295       --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
300       --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
306       --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
312       --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

EXAMPLES

318       ikiwiki --setup my.setup
319
320              Completely (re)build the wiki using the specified setup file.
321
322       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
326       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
333       ikiwiki --rebuild srcdir destdir
334              Use  srcdir as source and build HTML in destdir, without using a
335              setup file.
336
337       ikiwiki srcdir destdir
338              Use srcdir as source to update changed pages' HTML  in  destdir,
339              without using a setup file.
340

ENVIRONMENT

342       CC
343
344              This controls what C compiler is used to build wrappers. Default
345              is 'cc'.
346
347       CFLAGS This can be used to pass options to the C compiler when building
348              wrappers.
349

SEE ALSO

351       ikiwiki-mass-rebuild(8)
352
353       ikiwiki-update-wikilist(1)
354
355       ikiwiki-transition(1)
356

AUTHOR

358       Joey Hess <joey@ikiwiki.info>
359
360                                                                    ikiwiki(1)
Impressum