X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/73c7c4ebf71ab7d2e91197250b5025a9b085098c..bd5f94d2ac85d6fb5d60400345fe41b91f2d303c:/doc/plugins/write.mdwn?ds=inline

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 4fd102bfd..7c28088de 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -3,7 +3,7 @@ written to extend ikiwiki in many ways. Despite the length of this page,
 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
 
@@ -46,11 +46,13 @@ being edited.
 
 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.
+the type of hook being registered -- see below. 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" parameter, 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
@@ -99,6 +101,18 @@ 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.
 
+### 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.
+
 ### filter
 
 	hook(type => "filter", id => "foo", call => \&filter);
@@ -154,23 +168,11 @@ 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
+Runs on the 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.
@@ -187,7 +189,7 @@ 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
+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.
 
@@ -214,6 +216,17 @@ 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.
 
+### 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);
@@ -258,9 +271,9 @@ state is loaded, and with no session information.
 
 	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. 
+This hook can be used to implement an authentication method. 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
@@ -312,7 +325,7 @@ It can modify the content as desired, and should return the content.
 	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
@@ -331,15 +344,24 @@ called. It can be used to validate the form, but should not display it.
 
 	hook(type => "savestate", id => "foo", call => \&savestate);
 
-This hook is called wheneven ikiwiki normally saves its state, just before
+This hook is called whenever ikiwiki normally saves its state, just before
 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:
 
-	use IkiWiki '1.00';
+	use IkiWiki '2.00';
 
 This will import several variables and functions into your plugin's
 namespace. These variables and functions are the ones most plugins need,
@@ -410,16 +432,17 @@ Aborts with an error message. If the second parameter is passed, it is a
 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, 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`.
 
@@ -559,12 +582,15 @@ time.
 
 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
@@ -621,4 +647,5 @@ when imported, populate `$IkiWiki::Setup::raw_setup` with a reference
 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)`