### preprocess
-Adding a [[PreProcessorDirective]] is probably the most common use of a
-plugin.
+Adding a [[ikiwiki/PreProcessorDirective]] is probably the most common use
+of a plugin.
hook(type => "preprocess", id => "foo", call => \&preprocess);
be run twice per page build, so avoid doing it for expensive hooks.
Note that if the [[htmlscrubber]] is enabled, html in
-[[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.
+[[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.
### htmlize
hook(type => "templatefile", id => "foo", call => \&templatefile);
-This hook allows plugins to change the [[template|wikitemplate]] that is
+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
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 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.
If the hook has no opinion about whether the edit can proceed, return
-`undef`, and the next plugin will be asked to decide.
+`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
add/remove/change fields, tweak the validation code for the fields, etc. It
will not validate or display the form.
-Form validation and display can be overridden by the formbuilder hook.
-By default, ikiwiki will do a basic validation and display of the form,
-but if this hook is registered, it will stop that and let the hook take
-over.
+Just before a form is displayed to the user, the `formbuilder` hook is
+called. It can be used to validate the form, but should not display it.
### savestate
hash. The best way to understand the contents of the hash is to look at
[[ikiwiki.setup]], which sets the hash content to configure the wiki.
+### %pagestate
+
+The `%pagestate` hash can be used by plugins to save state that they will need
+next time ikiwiki is run. The hash holds per-page state, so to set a value,
+use `%pagestate{$page}{$id}{$key}=$value`, and to retrieve the value,
+use `%pagestate{$page}{$id}{$key}`.
+
+`$key` can be any string you like, but `$id` must be the same as the "id"
+parameter passed to `hook()` when registering the plugin. This is so
+ikiwiki can know when to delete pagestate for plugins that are no longer
+used.
+
+When pages are deleted, ikiwiki automatically deletes their pagestate too.
+
+Note that page state does not persist across wiki rebuilds, only across
+wiki updates.
+
### Other variables
If your plugin needs to access data about other pages in the wiki. It can
Note that while any plugin can use this for a fatal error, plugins should
try to avoid dying on bad input, as that will halt the entire wiki build
-and make the wiki unusable. So for example, if a [[PreProcessorDirective]]
-is passed bad parameters, it's better to return an error message, which can
-appear on the wiki page, rather than calling error().
+and make the wiki unusable. So for example, if a
+[[ikiwiki/PreProcessorDirective]] is passed bad parameters, it's better to
+return an error message, which can appear on the wiki page, rather than
+calling error().
#### `template($;@)`
#### `add_depends($$)`
-Makes the specified page depend on the specified [[PageSpec]].
+Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
#### `pagespec_match($$;@)`
-Passed a page name, and [[PageSpec]], returns true if the [[PageSpec]]
-matches the page.
+Passed a page name, and [[ikiwiki/PageSpec]], returns true if the
+[[ikiwiki/PageSpec]] matches the page.
Additional named parameters can be passed, to further limit the match.
The most often used is "location", which specifies the location the
existing page that link best points to. Prefers pages under a
subdirectory with the same name as the source page, failing that
goes down the directory tree to the base looking for matching
-pages, as described in [[SubPage/LinkingRules]].
+pages, as described in [[ikiwiki/SubPage/LinkingRules]].
#### `htmllink($$$;@)`
If the directory name is not absolute, ikiwiki will assume it is in
the parent directory of the configured underlaydir.
-#### `displaytime($)`
+#### `displaytime($;$)`
Given a time, formats it for display.
+The optional second parameter is a strftime format to use to format the
+time.
+
#### `gettext`
This is the standard gettext function, although slightly optimised.
## PageSpec plugins
It's also possible to write plugins that add new functions to
-[[PageSpecs|PageSpec]]. Such a plugin should add a function to the
+[[PageSpecs|ikiwiki/PageSpec]]. Such a plugin should add a function to the
IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is
-how it will be accessed in a [[PageSpec]]. The function will be passed
+how it will be accessed in a [[ikiwiki/PageSpec]]. The function will be passed
two parameters: The name of the page being matched, and the thing to match
against. It may also be passed additional, named parameters. It should return
a IkiWiki::SuccessReason object if the match succeeds, or an