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,
$links{"foo"} = ["bar", "baz"];
+### `%typedlinks`
+
+The `%typedlinks` hash records links of specific types. Do not modify this
+hash directly; call `add_link()`. The keys are page names, and the values
+are hash references. In each page's hash reference, the keys are link types
+defined by plugins, and the values are hash references with link targets
+as keys, and 1 as a dummy value, something like this:
+
+ $typedlinks{"foo"} = {
+ tag => { short_word => 1, metasyntactic_variable => 1 },
+ next_page => { bar => 1 },
+ };
+
+Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in
+`%typedlinks`.
+
### `%pagesources`
The `%pagesources` has can be used to look up the source filename
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
filename of the page. For example, `targetpage("foo", "rss", "feed")`
will yield something like `foo/feed.rss`.
-### `add_link($$)`
+### `add_link($$;$)`
This adds a link to `%links`, ensuring that duplicate links are not
added. Pass it the page that contains the link, and the link text.
+An optional third parameter sets the link type. If not specified,
+it is an ordinary [[ikiwiki/WikiLink]].
+
## Miscellaneous
### Internal use pages
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::SortSpec package named `cmp_foo`, which will be used when sorting
+by `foo` or `foo(...)` is requested.
+
+The names of pages to be compared are in the global variables `$a` and `$b`
+in the IkiWiki::SortSpec package. The function should return the same thing
+as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`,
+positive if `$a` 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.
+
+The function will also be passed one or more parameters. The first is
+`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`;
+it may also be passed additional, named parameters.
+
### Setup plugins
The ikiwiki setup file is loaded using a pluggable mechanism. If you look