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
  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, and boolean
  18 flags such as --verbose can be negated with --no-verbose.
  19
  20 # MODE OPTIONS
  21
  22 These options control the mode that ikiwiki operates in.
  23
  24 * --refresh
  25
  26   Refresh the wiki, updating any changed pages. This is the default
  27   behavior so you don't normally need to specify it.
  28
  29 * --rebuild
  30
  31   Force a rebuild of all pages.
  32
  33 * --setup setupfile
  34
  35   In setup mode, ikiwiki reads the config file, which is really a perl
  36   program that can call ikiwiki internal functions.
  37
  38   The default action when --setup is specified is to automatically generate
  39   wrappers for a wiki based on data in a setup file, and rebuild the wiki.
  40   If you only want to build any changed pages, you can use --refresh with
  41   --setup.
  42
  43 * --dumpsetup setupfile
  44
  45   Causes ikiwiki to write to the specified setup file, dumping out
  46   its current configuration.
  47
  48 * --wrappers
  49
  50   If used with --setup --refresh, this makes it also update any configured
  51   wrappers.
  52
  53 * --clean
  54
  55   This makes ikiwiki clean up by removing any files it denerated in the
  56   `destination` directory, as well as any configured wrappers, and the
  57   `.ikiwiki` state directory. This is mostly useful if you're running
  58   ikiwiki in a Makefile to build documentation and want a corresponding
  59   `clean` target.
  60
  61 * --cgi
  62
  63   Enable [[CGI]] mode. In cgi mode ikiwiki runs as a cgi script, and
  64   supports editing pages, signing in, and registration.
  65
  66   To use ikiwiki as a [[CGI]] program you need to use --wrapper or --setup
  67   to generate a wrapper. The wrapper will generally need to run suid 6755 to
  68   the user who owns the `source` and `destination` directories.
  69
  70 * --wrapper [file]
  71
  72   Generate a wrapper binary that is hardcoded to do action specified by
  73   the other options, using the specified input files and `destination`
  74   directory. The filename to use for the wrapper is optional.
  75
  76   The wrapper is designed to be safely made suid and be run by untrusted
  77   users, as a [[post-commit]] hook, or as a [[CGI]].
  78
  79   Note that the generated wrapper will ignore all command line parameters.
  80
  81 * --aggregate
  82
  83   If the [[plugins/aggregate]] plugin is enabled, this makes ikiwiki poll
  84   configured feeds and save new posts to the srcdir.
  85
  86   Note that to rebuild previously aggregated posts, use the --rebuild option
  87   along with this one. --rebuild will also force feeds to be polled even if
  88   they were polled recently.
  89
  90 * --render file
  91
  92   Renders a single file, outputting the resulting html. Does not save state,
  93   so this cannot be used for building whole wikis, but it is useful for
  94   previewing an edited file at the command line. Generally used in conjunction
  95   with --setup to load in a wiki's setup:
  96
  97         ikiwiki --setup ~/ikiwiki.setup --render foo.mdwn
  98
  99 * --post-commit
 100
 101   Run in post-commit mode, the same as if called by a [[post-commit]] hook.
 102   This is probably only useful when using ikiwiki with a web server on one host
 103   and a repository on another, to allow the repository's real post-commit
 104   hook to ssh to the web server host and manually run ikiwiki to update
 105   the web site.
 106
 107 * --version
 108
 109   Print ikiwiki's version number.
 110
 111 # CONFIG OPTIONS
 112
 113 These options configure the wiki. Note that [[plugins]] can add additional
 114 configuration options of their own. All of these options and more besides can
 115 also be configured using a setup file.
 116
 117 * --wikiname name
 118
 119   The name of the wiki, default is "wiki".
 120
 121 * --templatedir dir
 122
 123   Specify the directory that [[templates|templates]] are stored in.
 124   Default is `/usr/share/ikiwiki/templates`, or another location as configured at
 125   build time. If the templatedir is changed, missing templates will still
 126   be searched for in the default location as a fallback. Templates can also be
 127   placed in the "templates/" subdirectory of the srcdir.
 128
 129   Note that if you choose to copy and modify ikiwiki's templates, you will need
 130   to be careful to keep them up to date when upgrading to new versions of
 131   ikiwiki. Old versions of templates do not always work with new ikiwiki
 132   versions.
 133
 134 * --underlaydir dir
 135
 136   Specify the directory that is used to underlay the source directory.
 137   Source files will be taken from here unless overridden by a file in the
 138   source directory. Default is `/usr/share/ikiwiki/basewiki` or another
 139   location as configured at build time.
 140
 141 * --wrappermode mode
 142
 143   Specify a mode to chmod the wrapper to after creating it.
 144
 145 * --wrappergroup group
 146
 147   Specify what unix group the wrapper should be owned by. This can be
 148   useful if the wrapper needs to be owned by a group other than the default.
 149   For example, if a project has a repository with multiple committers with
 150   access controlled by a group, it makes sense for the ikiwiki wrappers
 151   to run setgid to that group.
 152
 153 * --rcs=svn|git|.., --no-rcs
 154
 155   Enable or disable use of a [[revision_control_system|rcs]].
 156
 157   The `source` directory will be assumed to be a working copy, or clone, or
 158   whatever the revision control system you select uses.
 159
 160   In [[CGI]] mode, with a revision control system enabled, pages edited via
 161   the web will be committed.
 162
 163   No revision control is enabled by default.
 164
 165 * --svnrepo /svn/wiki
 166
 167   Specify the location of the svn repository for the wiki.
 168
 169 * --svnpath trunk
 170
 171   Specify the path inside your svn repository where the wiki is located.
 172   This defaults to `trunk`; change it if your wiki is at some other path
 173   inside the repository. If your wiki is rooted at the top of the repository,
 174   set svnpath to "".
 175
 176 * --rss, --norss
 177
 178   If rss is set, ikiwiki will default to generating RSS feeds for pages
 179   that inline a [[blog]].
 180
 181 * --allowrss
 182
 183   If allowrss is set, and rss is not set, ikiwiki will not default to
 184   generating RSS feeds, but setting `rss=yes` in the inline directive can
 185   override this default and generate a feed.
 186
 187 * --atom, --noatom
 188
 189   If atom is set, ikiwiki will default to generating Atom feeds for pages
 190   that inline a [[blog]].
 191
 192 * --allowatom
 193
 194   If allowatom is set, and rss is not set, ikiwiki will not default to
 195   generating Atom feeds, but setting `atom=yes` in the inline directive can
 196   override this default and generate a feed.
 197
 198 * --pingurl URL
 199
 200   Set this to the URL of an XML-RPC service to ping when an RSS feed is
 201   updated. For example, to ping Technorati, use the URL
 202   http://rpc.technorati.com/rpc/ping
 203
 204   This parameter can be specified multiple times to specify more than one
 205   URL to ping.
 206
 207 * --url URL
 208
 209   Specifies the URL to the wiki. This is a required parameter in [[CGI]] mode.
 210
 211 * --cgiurl http://example.org/ikiwiki.cgi
 212
 213   Specifies the URL to the ikiwiki [[CGI]] script wrapper. Required when
 214   building the wiki for links to the cgi script to be generated.
 215
 216 * --historyurl URL
 217
 218   Specifies the URL to link to for page history browsing. In the URL,
 219   "\[[file]]" is replaced with the file to browse. It's common to use
 220   [[ViewVC]] for this.
 221
 222 * --adminemail you@example.org
 223
 224   Specifies the email address that ikiwiki should use for sending email.
 225
 226 * --diffurl URL
 227
 228   Specifies the URL to link to for a diff of changes to a page. In the URL,
 229   "\[[file]]" is replaced with the file to browse, "\[[r1]]" is the old
 230   revision of the page, and "\[[r2]]" is the new revision. It's common to use
 231   [[ViewVC]] for this.
 232
 233 * --exclude regexp
 234
 235   Specifies a rexexp of source files to exclude from processing.
 236   May be specified multiple times to add to exclude list.
 237
 238 * --include regexp
 239
 240   Specifies a rexexp of source files, that would normally be excluded,
 241   but that you wish to include in processing.
 242   May be specified multiple times to add to include list.
 243
 244 * --adminuser name
 245
 246   Specifies a username of a user (or, if openid is enabled, an openid)
 247   who has the powers of a wiki admin. Currently allows locking of any page,
 248   and [[banning|banned_users]] users; other powers may be added later.
 249   May be specified multiple times for multiple admins.
 250
 251   For an openid user specify the full URL of the login, including "http://".
 252
 253 * --plugin name
 254
 255   Enables the use of the specified [[plugin|plugins]] in the wiki.
 256   Note that plugin names are case sensitive.
 257
 258 * --disable-plugin name
 259
 260   Disables use of a plugin. For example "--disable-plugin htmlscrubber"
 261   to do away with HTML sanitization.
 262
 263 * --libdir directory
 264
 265   Makes ikiwiki look in the specified directory first, before the regular
 266   locations when loading library files and plugins. For example, if you set
 267   libdir to "/home/you/.ikiwiki/", you can install a foo.pm plugin as
 268   "/home/you/.ikiwiki/IkiWiki/Plugin/foo.pm".
 269
 270 * --discussion, --no-discussion
 271
 272   Enables or disables "Discussion" links from being added to the header of
 273   every page. The links are enabled by default.
 274
 275 * --numbacklinks n
 276
 277   Controls how many backlinks should be displayed at the bottom of a page.
 278   Excess backlinks will be hidden in a popup. Default is 10. Set to 0 to
 279   disable this feature.
 280
 281 * --userdir subdir
 282
 283   Optionally, allows links to users of the wiki to link to pages inside a
 284   subdirectory of the wiki. The default is to link to pages in the toplevel
 285   directory of the wiki.
 286
 287 * --htmlext html
 288
 289   Configures the extension used for generated html files. Default is "html".
 290
 291 * --timeformat format
 292
 293   Specify how to display the time or date. The format string is passed to the
 294   strftime(3) function.
 295
 296 * --verbose, --no-verbose
 297
 298   Be verbose about what is being done.
 299
 300 * --syslog, --no-syslog
 301
 302   Log to syslog(3).
 303
 304 * --usedirs, --no-usedirs
 305
 306   Toggle creating output files named page/index.html (default) instead of page.html.
 307
 308 * --prefix-directives, --no-prefix-directives
 309
 310   Toggle new '!'-prefixed syntax for preprocessor directives.  ikiwiki currently
 311   defaults to --prefix-directives.
 312
 313 * --w3mmode, --no-w3mmode
 314
 315   Enable [[w3mmode]], which allows w3m to use ikiwiki as a local CGI script,
 316   without a web server.
 317
 318 * --sslcookie
 319
 320   Only send cookies over an SSL connection. This should prevent them being
 321   intercepted. If you enable this option then you must run at least the
 322   CGI portion of ikiwiki over SSL.
 323
 324 * --gettime, --no-gettime
 325
 326   Extract creation and modification times for each new page from the
 327   the revision control's log. This is done automatically when building a
 328   wiki for the first time, so you normally do not need to use this option.
 329
 330 * --set var=value
 331
 332   This allows setting an arbitrary configuration variable, the same as if it
 333   were set via a setup file. Since most commonly used options can be
 334   configured using command-line switches, you will rarely need to use this.
 335
 336 * --set-yaml var=value
 337
 338   This is like --set, but it allows setting configuration variables that
 339   use complex data structures, by passing in a YAML document.
 340
 341 # EXAMPLES
 342
 343 * ikiwiki --setup my.setup
 344
 345   Completly (re)build the wiki using the specified setup file.
 346
 347 * ikiwiki --setup my.setup --refresh
 348
 349   Refresh the wiki, using settings from my.setup, and avoid
 350   rebuilding any pages that have not changed. This is faster.
 351
 352 * ikiwiki --setup my.setup --refresh --wrappers
 353
 354   Refresh the wiki, including regnerating all wrapper programs,
 355   but do not rebuild all pages. Useful if you have changed something
 356   in the setup file that does not need a full wiki rebuild to update
 357   all pages, but that you want to immediatly take effect.
 358
 359 # ENVIRONMENT
 360
 361 * CC
 362
 363   This controls what C compiler is used to build wrappers. Default is 'cc'.
 364
 365 * CFLAGS
 366
 367   This can be used to pass options to the C compiler when building wrappers.
 368
 369 # SEE ALSO
 370
 371 * [[ikiwiki-mass-rebuild]](8)
 372 * [[ikiwiki-update-wikilist]](1)
 373 * [[ikiwiki-transition]](1)
 374
 375 # AUTHOR
 376
 377 Joey Hess <joey@ikiwiki.info>
 378
 379 Warning: this page is automatically made into ikiwiki's man page via [mdwn2man](http://git.ikiwiki.info/?p=ikiwiki;a=blob;f=mdwn2man;hb=HEAD).  Edit with care