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
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
+Replace "foo" with the command name that will be used for the preprocessor
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.)
+Each time the directive is processed, the referenced function (`preprocess`
+in the example above) is called. Whatever the function returns goes onto
+the page in place of the directive. Or, if the function aborts using
+`error()`, the directive will be replaced with the error message.
+
+The function is passed named parameters. First come the parameters set
+in the preprocessor directive. These are passed in the same order as
+they're in the directive, and if the preprocessor directive contains a bare
+parameter (example: `\[[!foo param]]`), that parameter will be passed with
+an empty value.
+
+After the parameters from the preprocessor directive some additional ones
+are passed: 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.
+
+If `hook` is passed an optional "scan" parameter, set to a true value, this
+makes the hook be called during the preliminary scan that ikiwiki makes of
+updated pages, before begining to render pages. This should be done 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 context, you
+can assume it's being run in scan mode, and avoid doing expensive things at
+that point.)
Note that if the [[htmlscrubber]] is enabled, html in
[[ikiwiki/PreProcessorDirective]] output is sanitised, which may limit what
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:
#### `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)`