it's not really hard. This page is a complete reference to everything a
plugin might want to do. There is also a quick [[tutorial]].
-[[toc levels=2]]
+[[!toc levels=2]]
## Types of plugins
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
+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 function is passed named parameters: "page", "destpage", and "content",
and should return the sanitized content.
+### postscan
+
+ hook(type => "postscan", id => "foo", call => \&postscan);
+
+This hook is called once the full page body is available (but before the
+format hook). The most common use is to update search indexes. Added in
+ikiwiki 2.54.
+
+The function is passed named parameters "page" and "content". Its return
+value is ignored.
+
### format
hook(type => "format", id => "foo", call => \&format);
hook(type => "formbuilder_setup", id => "foo", call => \&formbuilder_setup);
hook(type => "formbuilder", id => "foo", call => \&formbuilder);
-These hooks allow tapping into the parts of ikiwiki that use [[cpan
+These hooks allow tapping into the parts of ikiwiki that use [[!cpan
CGI::FormBuilder]] to generate web forms. These hooks are passed named
parameters: `cgi`, `session`, `form`, and `buttons`. These are, respectively,
the `CGI` object, the user's `CGI::Session`, a `CGI::FormBuilder`, and a
the state is saved. The function can save other state, modify values before
they're saved, etc.
+## renamepage
+
+ hook(type => "renamepage", id => "foo", call => \&renamepage);
+
+This hook is called by the [[plugins/rename]] plugin when it renames
+something. The hook is passed named parameters: `page`, `oldpage`,
+`newpage`, and `content`, and should try to modify the content to reflect
+the name change. For example, by converting links to point to the new page.
+
## Plugin interface
To import the ikiwiki plugin interface:
function that is called after the error message is printed, to do any final
cleanup.
-Note that while any plugin can use this for a fatal error, plugins should
-try to avoid dying on bad input when building a page, as that will halt
-the entire wiki build 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().
+If called inside a preprocess hook, error() does not abort the entire
+wiki build, but instead replaces the [[ikiwiki/PreProcessorDirective]] with
+a version containing the error message.
+
+In other hooks, error() is a fatal error, so use with care. Try to avoid
+dying on bad input when building a page, as that will halt
+the entire wiki build and make the wiki unusable.
#### `template($;@)`
-Creates and returns a [[cpan HTML::Template]] object. The first parameter
+Creates and returns a [[!cpan HTML::Template]] object. The first parameter
is the name of the file in the template directory. The optional remaining
parameters are passed to `HTML::Template->new`.
This is the standard gettext function, although slightly optimised.
-#### `urlto($$)`
+#### `urlto($$;$)`
Construct a relative url to the first parameter from the page named by the
second. The first parameter can be either a page name, or some other
destination file, as registered by `will_render`.
+If the third parameter is passed and is true, an absolute url will be
+constructed instead of the default relative url.
+
#### `targetpage($$)`
Passed a page and an extension, returns the filename that page will be
to a hash containing all the config items.
By the way, to parse a ikiwiki setup file, a program just needs to
-do something like `use IkiWiki::Setup; my %setup=IkiWiki::Setup::load($filename)`
+do something like:
+`use IkiWiki::Setup; my %setup=IkiWiki::Setup::load($filename)`