+Plugins should, when imported, call `hook()` to hook into ikiwiki's
+processing. The function uses named parameters, and use varies depending on
+the type of hook being registered -- see below. Note that a plugin can call
+the function more than once to register multiple hooks. All calls to
+`hook()` should be passed a "type" parameter, which gives the type of
+hook, a "id" paramter, which should be a unique string for this plugin, and
+a "call" parameter, which tells what function to call for the hook.
+
+An optional "last" parameter, if set to a true value, makes the hook run
+after all other hooks of its type. Useful if the hook depends on some other
+hook being run first.
+
+## Types of hooks
+
+In roughly the order they are called.
+
+### getopt
+
+ hook(type => "getopt", id => "foo", call => \&getopt);
+
+This allows for plugins to perform their own processing of command-line
+options and so add options to the ikiwiki command line. It's called during
+command line processing, with @ARGV full of any options that ikiwiki was
+not able to process on its own. The function should process any options it
+can, removing them from @ARGV, and probably recording the configuration
+settings in %config. It should take care not to abort if it sees
+an option it cannot process, and should just skip over those options and
+leave them in @ARGV.
+
+### checkconfig
+
+ hook(type => "checkconfig", id => "foo", call => \&checkconfig);
+
+This is useful if the plugin needs to check for or modify ikiwiki's
+configuration. It's called early in the startup process. The
+function is passed no values. It's ok for the function to call
+`error()` if something isn't configured right.
+
+### refresh
+
+ hook(type => "refresh", id => "foo", call => \&refresh);
+
+This hook is called just before ikiwiki scans the wiki for changed files.
+It's useful for plugins that need to create or modify a source page. The
+function is passed no values.
+
+### needsbuild
+
+ hook(type => "needsbuild", id => "foo", call => \&needsbuild);
+
+This allows a plugin to manipulate the list of files that need to be
+built when the wiki is refreshed. The function is passed a reference to an
+array of pages that will be rebuilt, and can modify the array, either
+adding or removing files from it.
+
+### filter
+
+ hook(type => "filter", id => "foo", call => \&filter);
+
+Runs on the raw source of a page, before anything else touches it, and can
+make arbitrary changes. The function is passed named parameters "page",
+"destpage", and "content". It should return the filtered content.
+
+### preprocess
+
+Adding a [[ikiwiki/PreProcessorDirective]] is probably the most common use
+of a plugin.
+
+ hook(type => "preprocess", id => "foo", call => \&preprocess);
+
+Replace "foo" with the command name that will be used inside brackets for
+the preprocessor directive.
+
+Each time the directive is processed, the referenced function (`preprocess`
+in the example above) is called, and is passed named parameters. A "page"
+parameter gives the name of the page that embedded the preprocessor
+directive, while a "destpage" parameter gives the name of the page the
+content is going to (different for inlined pages), and a "preview"
+parameter is set to a true value if the page is being previewed. All
+parameters included in the directive are included as named parameters as
+well. Whatever the function returns goes onto the page in place of the
+directive.
+
+An optional "scan" parameter, if set to a true value, makes the hook be
+called during the preliminary scan that ikiwiki makes of updated pages,
+before begining to render pages. This parameter should be set to true if
+the hook modifies data in `%links`. Note that doing so will make the hook
+be run twice per page build, so avoid doing it for expensive hooks. (As an
+optimisation, if your preprocessor hook is called in a void contets, you
+can assume it's being run in scan mode.)
+
+Note that if the [[htmlscrubber]] is enabled, html in
+[[ikiwiki/PreProcessorDirective]] output is sanitised, which may limit what
+your plugin can do. Also, the rest of the page content is not in html
+format at preprocessor time. Text output by a preprocessor directive will
+be linkified and passed through markdown (or whatever engine is used to
+htmlize the page) along with the rest of the page.
+
+### linkify
+
+ hook(type => "linkify", id => "foo", call => \&linkify);
+
+This hook is called to convert [[WikiLinks|WikiLink]] on the page into html
+links. The function is passed named parameters "page", "destpage", and
+"content". It should return the linkified content. Present in IkiWiki 2.40
+and later.
+
+Plugins that implement linkify must also implement a scan hook, that scans
+for the links on the page and adds them to `%links`.
+
+### scan
+
+ hook(type => "scan", id => "foo", call => \&scan);
+
+This hook is called early in the process of building the wiki, and is used
+as a first pass scan of the page, to collect metadata about the page. It's
+mostly used to scan the page for WikiLinks, and add them to `%links`.
+Present in IkiWiki 2.40 and later.
+
+The function is passed named parameters "page" and "content". Its return
+value is ignored.
+
+### htmlize
+
+ hook(type => "htmlize", id => "ext", call => \&htmlize);
+
+Runs on the raw source of a page and turns it into html. The id parameter
+specifies the filename extension that a file must have to be htmlized using
+this plugin. This is how you can add support for new and exciting markup
+languages to ikiwiki.
+
+The function is passed named parameters: "page" and "content" and should
+return the htmlized content.
+
+### pagetemplate
+
+ hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
+
+[[Templates|wikitemplates]] are filled out for many different things in
+ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
+a cgi. This hook allows modifying the variables available on those
+templates. The function is passed named parameters. The "page" and
+"destpage" parameters are the same as for a preprocess hook. The "template"
+parameter is a [[cpan HTML::Template]] object that is the template that
+will be used to generate the page. The function can manipulate that
+template object.
+
+The most common thing to do is probably to call `$template->param()` to add
+a new custom parameter to the template.
+
+### templatefile
+
+ hook(type => "templatefile", id => "foo", call => \&templatefile);
+
+This hook allows plugins to change the [[template|wikitemplates]] that is
+used for a page in the wiki. The hook is passed a "page" parameter, and
+should return the name of the template file to use, or undef if it doesn't
+want to change the default ("page.tmpl"). Template files are looked for in
+/usr/share/ikiwiki/templates by default.
+
+### sanitize
+
+ hook(type => "sanitize", id => "foo", call => \&sanitize);
+
+Use this to implement html sanitization or anything else that needs to
+modify the body of a page after it has been fully converted to html.
+
+The function is passed named parameters: "page", "destpage", and "content",
+and should return the sanitized content.
+
+### format
+
+ hook(type => "format", id => "foo", call => \&format);
+
+The difference between format and sanitize is that sanitize only acts on
+the page body, while format can modify the entire html page including the
+header and footer inserted by ikiwiki, the html document type, etc. (It
+should not rely on always being passed the entire page, as it won't be
+when the page is being previewed.)
+
+The function is passed named parameters: "page" and "content", and
+should return the formatted content.
+
+### delete
+
+ hook(type => "delete", id => "foo", call => \&delete);
+
+Each time a page or pages is removed from the wiki, the referenced function
+is called, and passed the names of the source files that were removed.
+
+### change
+
+ hook(type => "change", id => "foo", call => \&render);
+
+Each time ikiwiki renders a change or addition (but not deletion) to the
+wiki, the referenced function is called, and passed the names of the
+source files that were rendered.
+
+### cgi
+
+ hook(type => "cgi", id => "foo", call => \&cgi);
+
+Use this to hook into ikiwiki's cgi script. Each registered cgi hook is
+called in turn, and passed a CGI object. The hook should examine the
+parameters, and if it will handle this CGI request, output a page
+(including the http headers) and terminate the program.
+
+Note that cgi hooks are called as early as possible, before any ikiwiki
+state is loaded, and with no session information.
+
+### auth
+
+ hook(type => "auth", id => "foo", call => \&auth);
+
+This hook can be used to implement a different authentication method than
+the standard web form. When a user needs to be authenticated, each registered
+auth hook is called in turn, and passed a CGI object and a session object.
+
+If the hook is able to authenticate the user, it should set the session
+object's "name" parameter to the authenticated user's name. Note that
+if the name is set to the name of a user who is not registered,
+a basic registration of the user will be automatically performed.
+
+### sessioncgi
+
+ hook(type => "sessioncgi", id => "foo", call => \&sessioncgi);
+
+Unlike the cgi hook, which is run as soon as possible, the sessioncgi hook
+is only run once a session object is available. It is passed both a CGI
+object and a session object. To check if the user is in fact signed in, you
+can check if the session object has a "name" parameter set.
+
+### canedit
+
+ hook(type => "canedit", id => "foo", call => \&pagelocked);
+
+This hook can be used to implement arbitrary access methods to control when
+a page can be edited using the web interface (commits from revision control
+bypass it). When a page is edited, each registered canedit hook is called
+in turn, and passed the page name, a CGI object, and a session object.
+
+If the hook has no opinion about whether the edit can proceed, return
+`undef`, and the next plugin will be asked to decide. If edit can proceed,
+the hook should return "". If the edit is not allowed by this hook, the
+hook should return an error message for the user to see, or a function
+that can be run to log the user in or perform other action necessary for
+them to be able to edit the page.
+
+This hook should avoid directly redirecting the user to a signin page,
+since it's sometimes used to test to see which pages in a set of pages a
+user can edit.
+
+### editcontent
+
+ hook(type => "editcontent", id => "foo", call => \&editcontent);
+
+This hook is called when a page is saved (or previewed) using the web
+interface. It is passed named parameters: `content`, `page`, `cgi`, and
+`session`. These are, respectively, the new page content as entered by the
+user, the page name, a `CGI` object, and the user's `CGI::Session`.