X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/a65d312467c5ab179ecf4aa715790f371a46634a..3d82d47e1896b8e64c1e22b09a05968fc481aebf:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 4dc55e302..686f7e518 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
 
@@ -189,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.
 
@@ -216,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);
@@ -314,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
@@ -337,6 +348,56 @@ 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.
+
+### getsetup
+
+	hook(type => "getsetup", id => "foo", call => \&getsetup);
+
+This hooks is not called during normal operation, but only when setting up 
+the wiki, or generating a setup file. Plugins can use this hook to add
+configuration options.
+
+The hook is passed no parameters. It returns data about the configuration
+options added by the plugin. It can also check if the plugin is usable, and
+die if the plugin is not available, which will cause the plugin to not be
+offered in the configuration interface.
+
+The data returned is a list of `%config` options, followed by a hash
+describing the option. For example:
+
+                return
+			option_foo => {
+				type => "boolean",
+				description => "enable foo",
+				safe => 1,
+				rebuild => 1,
+	                },
+			option_bar => {
+				type => "string",
+				example => "hello",
+				description => "what to say",
+				safe => 1,
+				rebuild => 0,
+			},
+
+* `type` can be "boolean", "string", "integer", "internal" (used for values
+  that are not user-visible). The type is the type of the leaf values; 
+  the `%config` option may be an array or hash of these.
+* `example` can be set to an example value.
+* `description` is a short description of the option.
+* `safe` should be false if the option should not be displayed in unsafe
+  configuration methods, such as the web interface. Anything that specifies
+  a command to run, a path on disk, or a regexp should be marked as unsafe.
+* `rebuild` should be true if changing the option will require a wiki rebuild.
+
 ## Plugin interface
 
 To import the ikiwiki plugin interface:
@@ -422,7 +483,7 @@ 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`.
 
@@ -562,12 +623,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
@@ -624,4 +688,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)`