]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/plugins/write.mdwn
format plugin categorization
[git.ikiwiki.info.git] / doc / plugins / write.mdwn
index 62bebbeedf28bfe5124c6ff67b0b399cc4094ede..68454d56c70ffd75970f4b70fb2942a389008cc0 100644 (file)
@@ -68,20 +68,21 @@ In roughly the order they are called.
 
 This allows for plugins to perform their own processing of command-line
 options and so add options to the ikiwiki command line. It's called during
-command line processing, with @ARGV full of any options that ikiwiki was
+command line processing, with `@ARGV` full of any options that ikiwiki was
 not able to process on its own. The function should process any options it
-can, removing them from @ARGV, and probably recording the configuration
-settings in %config. It should take care not to abort if it sees
+can, removing them from `@ARGV`, and probably recording the configuration
+settings in `%config`. It should take care not to abort if it sees
 an option it cannot process, and should just skip over those options and
-leave them in @ARGV.
+leave them in `@ARGV`.
 
 ### checkconfig
 
        hook(type => "checkconfig", id => "foo", call => \&checkconfig);
 
 This is useful if the plugin needs to check for or modify ikiwiki's
-configuration. It's called early in the startup process. The
-function is passed no values. It's ok for the function to call
+configuration. It's called early in the startup process. `%config`
+is populated at this point, but other state has not yet been loaded.
+The function is passed no values. It's ok for the function to call
 `error()` if something isn't configured right.
 
 ### refresh
@@ -201,6 +202,17 @@ like `Makefile` that have no extension.
 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
+
+       hook(type => "postscan", id => "foo", call => \&postscan);
+
+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
+update search indexes. Added in ikiwiki 2.54.
+
+The function is passed named parameters "page" and "content". Its return
+value is ignored.
+
 ### pagetemplate
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
@@ -237,17 +249,6 @@ 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);
@@ -456,6 +457,12 @@ describing the option. There can also be an item named "plugin", which
 describes the plugin as a whole. For example:
 
                 return
+                       plugin => {
+                               description => "description of this plugin",
+                               safe => 1,
+                               rebuild => 1,
+                               section => "misc",
+                       },
                        option_foo => {
                                type => "boolean",
                                description => "enable foo?",
@@ -470,11 +477,6 @@ describes the plugin as a whole. For example:
                                safe => 1,
                                rebuild => 0,
                        },
-                       plugin => {
-                               description => "description of this plugin",
-                               safe => 1,
-                               rebuild => 1,
-                       },
 
 * `type` can be "boolean", "string", "integer", "pagespec",
   or "internal" (used for values that are not user-visible). The type is
@@ -495,6 +497,8 @@ describes the plugin as a whole. For example:
   the plugin) will require a wiki rebuild, false if no rebuild is needed,
   and undef if a rebuild could be needed in some circumstances, but is not
   strictly required.
+* `section` can optionally specify which section in the config file
+  the plugin fits in.
 
 ### genwrapper
 
@@ -625,23 +629,26 @@ dependency type from one or more of these keywords:
 
 If multiple types are specified, they are combined.
 
-#### `use_pagespec($$;@)`
+#### `pagespec_match_list($$;@)`
 
 Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages
 in the wiki that match the [[ikiwiki/PageSpec]]. 
 
 The page will automatically be made to depend on the specified
 [[ikiwiki/PageSpec]], so `add_depends` does not need to be called. This
-is significantly more efficient than calling `add_depends`
-followed by `pagespec_match_list`. You should use this anytime a plugin
-needs to match a set of pages and generate something based on that list.
+is often significantly more efficient than calling `add_depends` and
+`pagespec_match` in a loop. You should use this anytime a plugin
+needs to match a set of pages and do something based on that list.
+
+Unlike pagespec_match, this may throw an error if there is an error in
+the pagespec.
 
 Additional named parameters can be specified:
 
 * `deptype` optionally specifies the type of dependency to add. Use the
   `deptype` function to generate a dependency type.
-* `limit` is a reference to a function, that is called and passed a page,
-  and must return true for the page to be included.
+* `filter` is a reference to a function, that is called and passed a page,
+  and returns true if the page should be filtered out of the list.
 * `sort` specifies a sort order for the list. See
   [[ikiwiki/PageSpec/sorting]] for the avilable sort methods.
 * `reverse` if true, sorts in reverse.
@@ -650,6 +657,9 @@ Additional named parameters can be specified:
 * `list` makes it only match amoung the specified list of pages.
   Default is to match amoung all pages in the wiki.
 
+Any other named parameters are passed on to `pagespec_match`, to further
+limit the match.
+
 #### `add_depends($$;$)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
@@ -672,19 +682,6 @@ The most often used is "location", which specifies the location the
 PageSpec should match against. If not passed, relative PageSpecs will match
 relative to the top of the wiki.
 
-#### `pagespec_match_list($$;@)`
-
-Passed a reference to a list of page names, and [[ikiwiki/PageSpec]],
-returns the set of pages that match the [[ikiwiki/PageSpec]].
-
-Additional named parameters can be passed, to further limit the match.
-The most often used is "location", which specifies the location the
-PageSpec should match against. If not passed, relative PageSpecs will match
-relative to the top of the wiki.
-
-Unlike pagespec_match, this may throw an error if there is an error in
-the pagespec.
-
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which
@@ -719,6 +716,7 @@ control some options. These are:
 * anchor - set to make the link include an anchor
 * rel - set to add a rel attribute to the link
 * class - set to add a css class to the link
+* title - set to add a title attribute to the link
 
 #### `readfile($;$)`