Now that it knows what pages it needs to build, ikiwiki runs two
compile passes. First, it runs `scan` hooks, which collect metadata about
the pages. Then it runs a page rendering pipeline, by calling in turn these
-hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `postscan`,
+hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `indexhtml`,
`pagetemplate`, `sanitize`, `format`.
After all necessary pages are built, it calls the `change` hook. Finally,
If `hook` is passed an optional "longname" parameter, this value is used
when prompting a user to choose a page type on the edit page form.
-### postscan
+### indexhtml
- hook(type => "postscan", id => "foo", call => \&postscan);
+ hook(type => "indexhtml", id => "foo", call => \&indexhtml);
This hook is called once the page has been converted to html (but before
the generated html is put in a template). The most common use is to
hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
-[[Templates|wikitemplates]] are filled out for many different things in
+[[Templates]] 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
hook(type => "templatefile", id => "foo", call => \&templatefile);
-This hook allows plugins to change the [[template|wikitemplates]] that is
+This hook allows plugins to change the [[template|templates]] 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.
+should return the name of the template file to use (relative to the
+template directory), or undef if it doesn't want to change the default
+("page.tmpl").
+
+### pageactions
+
+ hook(type => "pageactions", id => "foo", call => \&pageactions);
+
+This hook allows plugins to add arbitrary actions to the action bar on a
+page (next to Edit, RecentChanges, etc). The hook is passed a "page"
+parameter, and can return a list of html fragments to add to the action
+bar.
### sanitize
### `template($;@)`
-Creates and returns a [[!cpan HTML::Template]] object. The first parameter
-is the name of the file in the template directory. The optional remaining
+Creates and returns a [[!cpan HTML::Template]] object. (In a list context,
+returns the parameters needed to construct the obhect.)
+
+The first parameter is the name of the template file. The optional remaining
parameters are passed to `HTML::Template->new`.
+Normally, the template file is first looked for in the templates/ subdirectory
+of the srcdir. Failing that, it is looked for in the templatedir.
+
+Wiki pages can be used as templates. This should be done only for templates
+which it is safe to let wiki users edit. Enable it by passing a filename
+with no ".tmpl" extension. Template pages are normally looked for in
+the templates/ directory. If the page name starts with "/", a page
+elsewhere in the wiki can be used.
+
+### `template_depends($$;@)`
+
+Use this instead of `template()` if the content of a template is being
+included into a page. This causes the page to depend on the template,
+so it will be updated if the template is modified.
+
+Like `template()`, except the second parameter is the page.
+
### `htmlpage($)`
Passed a page name, returns the base name that will be used for a the html
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.
+If the third parameter is true, this is the publication time of a page.
+(Ie, set the html5 pubdate attribute.)
+
### `gettext`
This is the standard gettext function, although slightly optimised.
### `add_autofile($$$)`
-Sometimes you may want to add a file to the `srcdir`. For example,
-[[plugins/tag]] pages can be automatically created as needed. This function
-can be used to do that.
+Sometimes you may want to add a file to the `srcdir` as a result of content
+of other pages. For example, [[plugins/tag]] pages can be automatically
+created as needed. This function can be used to do that.
-The three parameters are the filename to add, the name of the plugin,
-and a callback function. The callback will be called if it is appropriate
-to automatically add the file, and should then take care of creating it,
-and doing anything else it needs to (such as checking it into revision
-control). Note that the callback may not always be called. For example,
-if an automatically added file is deleted by the user, ikiwiki will avoid
-re-adding it again.
+The three parameters are the filename to create (relative to the `srcdir`),
+the name of the plugin, and a callback function. The callback will be
+called if it is appropriate to automatically add the file, and should then
+take care of creating it, and doing anything else it needs to (such as
+checking it into revision control). Note that the callback may not always
+be called. For example, if an automatically added file is deleted by the
+user, ikiwiki will avoid re-adding it again.
-This function needs to be called during the scan hook, or earlier to work.
+This function needs to be called during the scan hook, or earlier in the
+build process, in order to add the file early enough for it to be built.
## Miscellaneous