web commit by BradRoberts

[git.ikiwiki.info.git] / doc / plugins / write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 18aa34dca7b304f9028c6d3b5a98583aa91e75a1..5cace0911c1f2d6cf3b6f40e0c4371a838d8b1e2 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -30,6 +30,12 @@ hook, a "id" paramter, which should be a unique string for this plugin, and
 a "call" parameter, which is a reference to a function to call for the
 hook.
 
 a "call" parameter, which is a reference to a function to call for the
 hook.
 

+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.
+

 ## Types of hooks
 
 In roughly the order they are called.
 ## Types of hooks
 
 In roughly the order they are called.


@@ -64,6 +70,14 @@ Runs on the raw source of a page, before anything else touches it, and can
 make arbitrary changes. The function is passed named parameters `page` and
 `content` and should return the filtered content.
 
 make arbitrary changes. The function is passed named parameters `page` and
 `content` and should return the filtered content.
 

+### scan
+
+       hook(type => "scan", id => "foo", call => \&scan);
+
+This is identical to a preprocess hook (see below), except that it is
+called in the initial pass that scans pages for data that will be used in
+later passes. Scan hooks are the only hook that should modify 
+

 ### preprocess
 
 Adding a [[PreProcessorDirective]] is probably the most common use of a
 ### preprocess
 
 Adding a [[PreProcessorDirective]] is probably the most common use of a


@@ -77,7 +91,7 @@ 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
 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 gices the name of the page the
+directive, while a "destpage" parameter gives the name of the page the

 content is going to (different for inlined pages). 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 directive.
 content is going to (different for inlined pages). 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 directive.


@@ -210,6 +224,11 @@ ikiwiki program.
 
 Hook into ikiwiki's processing. See the discussion of hooks above.
 
 
 Hook into ikiwiki's processing. See the discussion of hooks above.
 

+Note that in addition to the named parameters described above, a parameter
+named no_override is supported, If it's set to a true value, then this hook
+will not override any existing hook with the same id. This is useful if
+the id can be controled by the user.
+

 #### `debug($)`
 
 Logs a debugging message. These are supressed unless verbose mode is turned
 #### `debug($)`
 
 Logs a debugging message. These are supressed unless verbose mode is turned