This hook is used to inject C code (which it returns) into the `main`
function of the ikiwiki wrapper when it is being generated.
-### sort
-
- hook(type => "sort", id => "foo", call => \&sort_by_foo);
-
-This hook adds an additional [[ikiwiki/pagespec/sorting]] order or overrides
-an existing one. The callback is given two page names as arguments, and
-returns negative, zero or positive if the first page should come before,
-close to (i.e. undefined order), or after the second page.
-
-For instance, the built-in `title` sort order could be reimplemented as
-
- sub sort_by_title {
- pagetitle(basename($_[0])) cmp pagetitle(basename($_[1]));
- }
-
## Exported variables
Several variables are exported to your plugin when you `use IkiWiki;`
$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
* `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.
+ [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that
+ if a sort method is specified that depends on the
+ page content (such as 'meta(foo)'), the deptype needs to be set to
+ a content dependency.
* `reverse` if true, sorts in reverse.
* `num` if nonzero, specifies the maximum number of matching pages that
will be returned.
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]].
+
+### `add_autofile($$$)`
+
+Sometimes you may want to add a file to the `srcdir` as a result of content
+of other pages. For example, [[plugins/tag]] pages can be automatically
+created as needed. This function can be used to do that.
+
+The three parameters are the filename to add, the name of the plugin,
+and a callback function. The callback will be called if it is appropriate
+to automatically add the file, and should then take care of creating it,
+and doing anything else it needs to (such as checking it into revision
+control). Note that the callback may not always be called. For example,
+if an automatically added file is deleted by the user, ikiwiki will avoid
+re-adding it again.
+
+This function needs to be called during the scan hook, or earlier in the
+build process, in order to add the file early enough for it to be built.
+
## Miscellaneous
### Internal use pages
It's ok if this is not implemented, and throws an error.
+If the RCS cannot determine a ctime for the file, return 0.
+
+#### `rcs_getmtime($)`
+
+This is used to get the page modification time for a file from the RCS, by
+looking it up in the history.
+
+It's ok if this is not implemented, and throws an error.
+
+If the RCS cannot determine a mtime for the file, return 0.
+
#### `rcs_receive()`
This is called when ikiwiki is running as a pre-receive hook (or
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
sipb-www / ikiwiki.git / blobdiff