doc/usage.mdwn

   1 # NAME
   2
   3 ikiwiki - a wiki compiler
   4
   5 # SYNOPSIS
   6
   7 ikiwiki [options] source destination
   8
   9 ikiwiki --setup setupfile [options]
  10
  11 # DESCRIPTION
  12
  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`.
  16
  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.
  20
  21 # MODE OPTIONS
  22
  23 These options control the mode that ikiwiki operates in.
  24
  25 * --refresh
  26
  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).
  30
  31 * --rebuild
  32
  33   Force a rebuild of all pages.
  34
  35 * --setup setupfile
  36
  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.
  41
  42 * --changesetup setupfile
  43
  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.
  48
  49   Example, to enable some plugins:
  50
  51         ikiwiki --changesetup ~/ikiwiki.setup --plugin goodstuff --plugin calendar
  52
  53 * --dumpsetup setupfile
  54
  55   Causes ikiwiki to write to the specified setup file, dumping out
  56   its current configuration.
  57
  58 * --wrappers
  59
  60   If used with --setup --refresh, this makes it also update any configured
  61   wrappers.
  62
  63 * --clean
  64
  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.
  70
  71 * --cgi
  72
  73   Enable [[CGI]] mode. In cgi mode ikiwiki runs as a cgi script, and
  74   supports editing pages, signing in, and registration.
  75
  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.
  79
  80 * --wrapper [file]
  81
  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.
  85
  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]].
  88
  89   Note that the generated wrapper will ignore all command line parameters.
  90
  91 * --aggregate
  92
  93   If the [[plugins/aggregate]] plugin is enabled, this makes ikiwiki poll
  94   configured feeds and save new posts to the srcdir.
  95
  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.
  99
 100 * --render file
 101
 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:
 106
 107         ikiwiki --setup ~/ikiwiki.setup --render foo.mdwn
 108
 109 * --post-commit
 110
 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.
 116
 117 * --version
 118
 119   Print ikiwiki's version number.
 120
 121 # CONFIG OPTIONS
 122
 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.
 126
 127 * --wikiname name
 128
 129   The name of the wiki, default is "wiki".
 130
 131 * --templatedir dir
 132
 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.
 138
 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.
 143
 144 * --underlaydir dir
 145
 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.
 150
 151 * --wrappermode mode
 152
 153   Specify a mode to chmod the wrapper to after creating it.
 154
 155 * --wrappergroup group
 156
 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.
 162
 163 * --rcs=svn|git|.., --no-rcs
 164
 165   Enable or disable use of a [[revision_control_system|rcs]].
 166
 167   The `source` directory will be assumed to be a working copy, or clone, or
 168   whatever the revision control system you select uses.
 169
 170   In [[CGI]] mode, with a revision control system enabled, pages edited via
 171   the web will be committed.
 172
 173   No revision control is enabled by default.
 174
 175 * --svnrepo /svn/wiki
 176
 177   Specify the location of the svn repository for the wiki.
 178
 179 * --svnpath trunk
 180
 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 "".
 185
 186 * --rss, --norss
 187
 188   If rss is set, ikiwiki will default to generating RSS feeds for pages
 189   that inline a [[blog]].
 190
 191 * --allowrss
 192
 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.
 196
 197 * --atom, --noatom
 198
 199   If atom is set, ikiwiki will default to generating Atom feeds for pages
 200   that inline a [[blog]].
 201
 202 * --allowatom
 203
 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.
 207
 208 * --pingurl URL
 209
 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
 213
 214   This parameter can be specified multiple times to specify more than one
 215   URL to ping.
 216
 217 * --url URL
 218
 219   Specifies the URL to the wiki. This is a required parameter in [[CGI]] mode.
 220
 221 * --cgiurl http://example.org/ikiwiki.cgi
 222
 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.
 225
 226 * --historyurl URL
 227
 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.
 231
 232 * --adminemail you@example.org
 233
 234   Specifies the email address that ikiwiki should use for sending email.
 235
 236 * --diffurl URL
 237
 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.
 242
 243 * --exclude regexp
 244
 245   Specifies a rexexp of source files to exclude from processing.
 246   May be specified multiple times to add to exclude list.
 247
 248 * --include regexp
 249
 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.
 253
 254 * --adminuser name
 255
 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.
 262
 263   For an openid user specify the full URL of the login, including "http://".
 264
 265 * --plugin name
 266
 267   Enables the use of the specified [[plugin|plugins]] in the wiki.
 268   Note that plugin names are case sensitive.
 269
 270 * --disable-plugin name
 271
 272   Disables use of a plugin. For example "--disable-plugin htmlscrubber"
 273   to do away with HTML sanitization.
 274
 275 * --libdir directory
 276
 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".
 281
 282 * --discussion, --no-discussion
 283
 284   Enables or disables "Discussion" links from being added to the header of
 285   every page. The links are enabled by default.
 286
 287 * --numbacklinks n
 288
 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.
 292
 293 * --userdir subdir
 294
 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.
 298
 299 * --htmlext html
 300
 301   Configures the extension used for generated html files. Default is "html".
 302
 303 * --timeformat format
 304
 305   Specify how to display the time or date. The format string is passed to the
 306   strftime(3) function.
 307
 308 * --verbose, --no-verbose
 309
 310   Be verbose about what is being done.
 311
 312 * --syslog, --no-syslog
 313
 314   Log to syslog(3).
 315
 316 * --usedirs, --no-usedirs
 317
 318   Toggle creating output files named page/index.html (default) instead of page.html.
 319
 320 * --prefix-directives, --no-prefix-directives
 321
 322   Toggle new '!'-prefixed syntax for preprocessor directives.  ikiwiki currently
 323   defaults to --prefix-directives.
 324
 325 * --w3mmode, --no-w3mmode
 326
 327   Enable [[w3mmode]], which allows w3m to use ikiwiki as a local CGI script,
 328   without a web server.
 329
 330 * --sslcookie
 331
 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.
 335
 336 * --gettime, --no-gettime
 337
 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.
 341
 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.
 347
 348 * --set-yaml var=value
 349
 350   This is like --set, but it allows setting configuration variables that
 351   use complex data structures, by passing in a YAML document.
 352
 353 # EXAMPLES
 354
 355 * ikiwiki --setup my.setup
 356
 357   Completely (re)build the wiki using the specified setup file.
 358
 359 * ikiwiki --setup my.setup --refresh
 360
 361   Refresh the wiki, using settings from my.setup, and avoid
 362   rebuilding any pages that have not changed. This is faster.
 363
 364 * ikiwiki --setup my.setup --refresh --wrappers
 365
 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.
 370
 371 * ikiwiki --rebuild srcdir destdir
 372
 373   Use srcdir as source and build HTML in destdir, without using a
 374   setup file.
 375
 376 * ikiwiki srcdir destdir
 377
 378   Use srcdir as source to update changed pages' HTML in destdir,
 379   without using a setup file.
 380
 381 # ENVIRONMENT
 382
 383 * CC
 384
 385   This controls what C compiler is used to build wrappers. Default is 'cc'.
 386
 387 * CFLAGS
 388
 389   This can be used to pass options to the C compiler when building wrappers.
 390
 391 # SEE ALSO
 392
 393 * [[ikiwiki-mass-rebuild]](8)
 394 * [[ikiwiki-update-wikilist]](1)
 395 * [[ikiwiki-transition]](1)
 396
 397 # AUTHOR
 398
 399 Joey Hess <joey@ikiwiki.info>
 400
 401 Warning: Automatically converted into a man page by mdwn2man. Edit with care