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
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);
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);
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?",
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
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
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.
* `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]].
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
* 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($;$)`