describing the option. There can also be an item named "plugin", which
describes the plugin as a whole. For example:
- return
+ return
plugin => {
description => "description of this plugin",
safe => 1,
page will be updated whenever anything matching the PageSpec is modified.
This can be overridden by passing a `deptype` value as the third parameter.
-#### `pagespec_match($$;@)`
+### `pagespec_match($$;@)`
Passed a page name, and [[ikiwiki/PageSpec]], returns a true value if the
[[ikiwiki/PageSpec]] matches the page.
If multiple types are specified, they are combined.
-#### `bestlink($$)`
+### `bestlink($$)`
Given a page and the text of a link on the page, determine which
existing page that link best points to. Prefers pages under a
goes down the directory tree to the base looking for matching
pages, as described in [[ikiwiki/SubPage/LinkingRules]].
-#### `htmllink($$$;@)`
+### `htmllink($$$;@)`
Many plugins need to generate html links and add them to a page. This is
done by using the `htmllink` function. The usual way to call
This is the standard gettext function, although slightly optimised.
+### `ngettext`
+
+This is the standard ngettext function, although slightly optimised.
+
### `urlto($$;$)`
Construct a relative url to the first parameter from the page named by the
they match; "created_before(foo)" is influenced by the metadata of foo;
while "glob(*)" is not influenced by the contents of any page.
+### Sorting plugins
+
+Similarly, it's possible to write plugins that add new functions as
+[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to
+the IkiWiki::PageSpec package named `cmp_foo`, which will be used when sorting
+by `foo` or `foo(...)` is requested.
+
+The function will be passed three or more parameters. The first two are
+page names, and the third is `undef` if invoked as `foo`, or the parameter
+`"bar"` if invoked as `foo(bar)`. It may also be passed additional, named
+parameters.
+
+It should return the same thing as Perl's `cmp` and `<=>` operators: negative
+if the first argument is less than the second, positive if the first argument
+is greater, or zero if they are considered equal. It may also raise an
+error using `error`, for instance if it needs a parameter but one isn't
+provided.
+
+You can also define a function called `check_cmp_foo` in the same package.
+If you do, it will be called while preparing to sort by `foo` or `foo(bar)`,
+with argument `undef` or `"bar"` respectively; it may raise an error using
+`error`, if sorting like that isn't going to work.
+
### Setup plugins
The ikiwiki setup file is loaded using a pluggable mechanism. If you look