]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blob - doc/usage.mdwn
Added a comment
[git.ikiwiki.info.git] / doc / usage.mdwn
1 # NAME
3 ikiwiki - a wiki compiler
5 # SYNOPSIS
7 ikiwiki [options] source destination
9 ikiwiki --setup setupfile [options]
11 # DESCRIPTION
13 `ikiwiki` is a wiki compiler. It builds static HTML pages for a wiki, from
14 `source` in the [[ikiwiki/Markdown]] language (or others), and writes it out to
15 `destination`.
17 Note that most options can be shortened to single letters, boolean
18 flags such as --verbose can be negated with --no-verbose, and
19 options such as --verbose can also be spelled like -verbose.
21 # MODE OPTIONS
23 These options control the mode that ikiwiki operates in.
25 * --refresh
27   Refresh the wiki, updating any changed pages. This is the default
28   behavior if no other mode action is specified (but note that --setup is
29   a mode action, and has different default behavior).
31 * --rebuild
33   Force a rebuild of all pages.
35 * --setup setupfile
37   Load options from the given setup file. If no other mode action is specified,
38   generate wrappers and rebuild the wiki, as if --rebuild --wrappers were used.
39   If you only want to build any changed pages, you can use --refresh with
40   --setup.
42 * --changesetup setupfile
44   Reads the setup file, adds any configuration changes specified by other
45   options, and writes the new configuration back to the setup file. Also
46   updates any configured wrappers. In this mode, the wiki is not fully
47   rebuilt, unless you also add --rebuild.
49   Example, to enable some plugins:
51         ikiwiki --changesetup ~/ikiwiki.setup --plugin goodstuff --plugin calendar
53 * --dumpsetup setupfile
55   Causes ikiwiki to write to the specified setup file, dumping out
56   its current configuration.
58 * --wrappers
60   If used with --setup --refresh, this makes it also update any configured
61   wrappers.
63 * --clean
65   This makes ikiwiki clean up by removing any files it generated in the
66   `destination` directory, as well as any configured wrappers, and the
67   `.ikiwiki` state directory. This is mostly useful if you're running
68   ikiwiki in a Makefile to build documentation and want a corresponding
69   `clean` target.
71 * --cgi
73   Enable [[CGI]] mode. In cgi mode ikiwiki runs as a cgi script, and
74   supports editing pages, signing in, and registration.
76   To use ikiwiki as a [[CGI]] program you need to use --wrapper or --setup
77   to generate a wrapper. The wrapper will generally need to run suid 6755 to
78   the user who owns the `source` and `destination` directories.
80 * --wrapper [file]
82   Generate a wrapper binary that is hardcoded to do action specified by
83   the other options, using the specified input files and `destination`
84   directory. The filename to use for the wrapper is optional.
86   The wrapper is designed to be safely made suid and be run by untrusted
87   users, as a [[post-commit]] hook, or as a [[CGI]].
89   Note that the generated wrapper will ignore all command line parameters.
91 * --aggregate
93   If the [[plugins/aggregate]] plugin is enabled, this makes ikiwiki poll
94   configured feeds and save new posts to the srcdir.
96   Note that to rebuild previously aggregated posts, use the --rebuild option
97   along with this one. --rebuild will also force feeds to be polled even if
98   they were polled recently.
100 * --render file
102   Renders a single file, outputting the resulting html. Does not save state,
103   so this cannot be used for building whole wikis, but it is useful for
104   previewing an edited file at the command line. Generally used in conjunction
105   with --setup to load in a wiki's setup:
107         ikiwiki --setup ~/ikiwiki.setup --render foo.mdwn
109 * --post-commit
111   Run in post-commit mode, the same as if called by a [[post-commit]] hook.
112   This is probably only useful when using ikiwiki with a web server on one host
113   and a repository on another, to allow the repository's real post-commit
114   hook to ssh to the web server host and manually run ikiwiki to update
115   the web site.
117 * --version
119   Print ikiwiki's version number.
121 # CONFIG OPTIONS
123 These options configure the wiki. Note that [[plugins]] can add additional
124 configuration options of their own. All of these options and more besides can
125 also be configured using a setup file.
127 * --wikiname name
129   The name of the wiki, default is "wiki".
131 * --templatedir dir
133   Specify the directory that [[templates|templates]] are stored in.
134   Default is `/usr/share/ikiwiki/templates`, or another location as configured at
135   build time. If the templatedir is changed, missing templates will still
136   be searched for in the default location as a fallback. Templates can also be
137   placed in the "templates/" subdirectory of the srcdir.
139   Note that if you choose to copy and modify ikiwiki's templates, you will need
140   to be careful to keep them up to date when upgrading to new versions of
141   ikiwiki. Old versions of templates do not always work with new ikiwiki
142   versions.
144 * --underlaydir dir
146   Specify the directory that is used to underlay the source directory.
147   Source files will be taken from here unless overridden by a file in the
148   source directory. Default is `/usr/share/ikiwiki/basewiki` or another
149   location as configured at build time.
151 * --wrappermode mode
153   Specify a mode to chmod the wrapper to after creating it.
155 * --wrappergroup group
157   Specify what unix group the wrapper should be owned by. This can be
158   useful if the wrapper needs to be owned by a group other than the default.
159   For example, if a project has a repository with multiple committers with
160   access controlled by a group, it makes sense for the ikiwiki wrappers
161   to run setgid to that group.
163 * --rcs=svn|git|.., --no-rcs
165   Enable or disable use of a [[revision_control_system|rcs]].
167   The `source` directory will be assumed to be a working copy, or clone, or
168   whatever the revision control system you select uses.
170   In [[CGI]] mode, with a revision control system enabled, pages edited via
171   the web will be committed.
173   No revision control is enabled by default.
175 * --svnrepo /svn/wiki
177   Specify the location of the svn repository for the wiki.
179 * --svnpath trunk
181   Specify the path inside your svn repository where the wiki is located.
182   This defaults to `trunk`; change it if your wiki is at some other path
183   inside the repository. If your wiki is rooted at the top of the repository,
184   set svnpath to "".
186 * --rss, --norss
188   If rss is set, ikiwiki will default to generating RSS feeds for pages
189   that inline a [[blog]].
191 * --allowrss
193   If allowrss is set, and rss is not set, ikiwiki will not default to
194   generating RSS feeds, but setting `rss=yes` in the inline directive can
195   override this default and generate a feed.
197 * --atom, --noatom
199   If atom is set, ikiwiki will default to generating Atom feeds for pages
200   that inline a [[blog]].
202 * --allowatom
204   If allowatom is set, and rss is not set, ikiwiki will not default to
205   generating Atom feeds, but setting `atom=yes` in the inline directive can
206   override this default and generate a feed.
208 * --pingurl URL
210   Set this to the URL of an XML-RPC service to ping when an RSS feed is
211   updated. For example, to ping Technorati, use the URL
212   http://rpc.technorati.com/rpc/ping
214   This parameter can be specified multiple times to specify more than one
215   URL to ping.
217 * --url URL
219   Specifies the URL to the wiki. This is a required parameter in [[CGI]] mode.
221 * --cgiurl http://example.org/ikiwiki.cgi
223   Specifies the URL to the ikiwiki [[CGI]] script wrapper. Required when
224   building the wiki for links to the cgi script to be generated.
226 * --historyurl URL
228   Specifies the URL to link to for page history browsing. In the URL,
229   "\[[file]]" is replaced with the file to browse. It's common to use
230   [[ViewVC]] for this.
232 * --adminemail you@example.org
234   Specifies the email address that ikiwiki should use for sending email.
236 * --diffurl URL
238   Specifies the URL to link to for a diff of changes to a page. In the URL,
239   "\[[file]]" is replaced with the file to browse, "\[[r1]]" is the old
240   revision of the page, and "\[[r2]]" is the new revision. It's common to use
241   [[ViewVC]] for this.
243 * --exclude regexp
245   Specifies a rexexp of source files to exclude from processing.
246   May be specified multiple times to add to exclude list.
248 * --include regexp
250   Specifies a rexexp of source files, that would normally be excluded,
251   but that you wish to include in processing.
252   May be specified multiple times to add to include list.
254 * --adminuser name
256   Specifies a username of a user (or, if openid is enabled, an openid) 
257   who has the powers of a wiki admin. Currently allows locking of any page,
258   and [[banning|banned_users]] users, as well as powers granted by
259   enabled plugins (such as [[moderating comments|plugins/moderatedcomments]] 
260   and [[plugins/websetup]]. May be specified multiple times for multiple
261   admins.
263   For an openid user specify the full URL of the login, including "http://".
265 * --plugin name
267   Enables the use of the specified [[plugin|plugins]] in the wiki. 
268   Note that plugin names are case sensitive.
270 * --disable-plugin name
272   Disables use of a plugin. For example "--disable-plugin htmlscrubber"
273   to do away with HTML sanitization.
275 * --libdir directory
277   Makes ikiwiki look in the specified directory first, before the regular
278   locations when loading library files and plugins. For example, if you set
279   libdir to "/home/you/.ikiwiki/", you can install a foo.pm plugin as
280   "/home/you/.ikiwiki/IkiWiki/Plugin/foo.pm".
282 * --discussion, --no-discussion
284   Enables or disables "Discussion" links from being added to the header of
285   every page. The links are enabled by default.
287 * --numbacklinks n
289   Controls how many backlinks should be displayed at the bottom of a page.
290   Excess backlinks will be hidden in a popup. Default is 10. Set to 0 to
291   disable this feature.
293 * --userdir subdir
295   Optionally, allows links to users of the wiki to link to pages inside a
296   subdirectory of the wiki. The default is to link to pages in the toplevel
297   directory of the wiki.
299 * --htmlext html
301   Configures the extension used for generated html files. Default is "html".
303 * --timeformat format
305   Specify how to display the time or date. The format string is passed to the
306   strftime(3) function.
308 * --verbose, --no-verbose
310   Be verbose about what is being done.
312 * --syslog, --no-syslog
314   Log to syslog(3).
316 * --usedirs, --no-usedirs
318   Toggle creating output files named page/index.html (default) instead of page.html.
320 * --prefix-directives, --no-prefix-directives
322   Toggle new '!'-prefixed syntax for preprocessor directives.  ikiwiki currently
323   defaults to --prefix-directives.
325 * --w3mmode, --no-w3mmode
327   Enable [[w3mmode]], which allows w3m to use ikiwiki as a local CGI script,
328   without a web server.
330 * --sslcookie
332   Only send cookies over an SSL connection. This should prevent them being
333   intercepted. If you enable this option then you must run at least the 
334   CGI portion of ikiwiki over SSL.
336 * --gettime, --no-gettime
338   Extract creation and modification times for each new page from the
339   the revision control's log. This is done automatically when building a
340   wiki for the first time, so you normally do not need to use this option.
342 * --set var=value
343   
344   This allows setting an arbitrary configuration variable, the same as if it
345   were set via a setup file. Since most commonly used options can be
346   configured using command-line switches, you will rarely need to use this.
348 * --set-yaml var=value
350   This is like --set, but it allows setting configuration variables that
351   use complex data structures, by passing in a YAML document.
353 # EXAMPLES
355 * ikiwiki --setup my.setup
357   Completely (re)build the wiki using the specified setup file.
359 * ikiwiki --setup my.setup --refresh
361   Refresh the wiki, using settings from my.setup, and avoid
362   rebuilding any pages that have not changed. This is faster.
364 * ikiwiki --setup my.setup --refresh --wrappers
366   Refresh the wiki, including regenerating all wrapper programs,
367   but do not rebuild all pages. Useful if you have changed something
368   in the setup file that does not need a full wiki rebuild to update
369   all pages, but that you want to immediately take effect.
371 * ikiwiki --rebuild srcdir destdir
373   Use srcdir as source and build HTML in destdir, without using a
374   setup file.
376 * ikiwiki srcdir destdir
378   Use srcdir as source to update changed pages' HTML in destdir,
379   without using a setup file.
381 # ENVIRONMENT
383 * CC
385   This controls what C compiler is used to build wrappers. Default is 'cc'.
387 * CFLAGS
389   This can be used to pass options to the C compiler when building wrappers.
391 # SEE ALSO
393 * [[ikiwiki-mass-rebuild]](8)
394 * [[ikiwiki-update-wikilist]](1)
395 * [[ikiwiki-transition]](1)
397 # AUTHOR
399 Joey Hess <joey@ikiwiki.info>
401 Warning: Automatically converted into a man page by mdwn2man. Edit with care