hook.
An optional "last" parameter, if set to a true value, makes the hook run
-after all other hooks of its type. Useful if the hook depends on some other
-hook being run first.
+after all other hooks of its type, and an optional "first" parameter makes
+it run first. Useful if the hook depends on some other hook being run first.
## Types of hooks
This allows a plugin to manipulate the list of files that need to be
built when the wiki is refreshed. The function is passed a reference to an
-array of pages that will be rebuilt, and can modify the array, either
+array of files that will be rebuilt, and can modify the array, either
adding or removing files from it.
### scan
This hook is called early in the process of building the wiki, and is used
as a first pass scan of the page, to collect metadata about the page. It's
-mostly used to scan the page for WikiLinks, and add them to `%links`.
+mostly used to scan the page for [[WikiLinks|ikiwiki/WikiLink]], and add them to `%links`.
Present in IkiWiki 2.40 and later.
The function is passed named parameters "page" and "content". Its return
hook(type => "linkify", id => "foo", call => \&linkify);
-This hook is called to convert [[WikiLinks|WikiLink]] on the page into html
+This hook is called to convert [[WikiLinks|ikiwiki/WikiLink]] on the page into html
links. The function is passed named parameters "page", "destpage", and
"content". It should return the linkified content. Present in IkiWiki 2.40
and later.
return the htmlized content.
If `hook` is passed an optional "keepextension" parameter, set to a true
-value, then this extension will not be stripped from the source filename when
+value, then the extension will not be stripped from the source filename when
generating the page.
+If `hook` is passed an optional "noextension" parameter, set to a true
+value, then the id parameter specifies not a filename extension, but
+a whole filename that can be htmlized. This is useful for files
+like `Makefile` that have no extension.
+
### pagetemplate
hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
### canedit
- hook(type => "canedit", id => "foo", call => \&pagelocked);
+ hook(type => "canedit", id => "foo", call => \&canedit);
This hook can be used to implement arbitrary access methods to control when
a page can be edited using the web interface (commits from revision control
since it's sometimes used to test to see which pages in a set of pages a
user can edit.
+### checkcontent
+
+ hook(type => "checkcontent", id => "foo", call => \&checkcontent);
+
+This hook is called to check the content a user has entered on a page,
+before it is saved, and decide if it should be allowed.
+
+It is passed named parameters: `content`, `page`, `cgi`, and `session`. If
+the content the user has entered is a comment, it may also be passed some
+additional parameters: `author`, `url`, and `subject`. The `subject`
+parameter may also be filled with the user's comment about the change.
+
+Note: When the user edits an existing wiki page, the passed `content` will
+include only the lines that they added to the page, or modified.
+
+The hook should return `undef` on success. If the content is disallowed, it
+should return a message stating what the problem is, or a function
+that can be run to perform whatever action is necessary to allow the user
+to post the content.
+
### editcontent
hook(type => "editcontent", id => "foo", call => \&editcontent);
* `example` can be set to an example value.
* `description` is a short description of the option.
* `link` is a link to further information about the option. This can either
- be a wikilink, or an url.
+ be a [[ikiwiki/WikiLink]], or an url.
* `advanced` can be set to true if the option is more suitable for advanced
users.
* `safe` should be false if the option should not be displayed in unsafe
destination file.
* `%pagesources` contains the name of the source file for each page.
-Also, the %IkiWiki::version variable contains the version number for the
+Also, the `%IkiWiki::version` variable contains the version number for the
ikiwiki program.
### Library functions
If the destination directory doesn't exist, it will first be created.
+The filename and directory are separate parameters because of
+some security checks done to avoid symlink attacks. Before writing a file,
+it checks to make sure there's not a symlink with its name, to avoid
+following the symlink. If the filename parameter includes a subdirectory
+to put the file in, it also checks if that subdirectory is a symlink, etc.
+The directory parameter, however, is not checked for symlinks. So,
+generally the directory parameter is a trusted toplevel directory like
+the srcdir or destdir, and any subdirectories of this are included in the
+filename parameter.
+
#### `will_render($$)`
Given a page name and a destination file name (not including the base
#### `linkpage($)`
This converts text that could have been entered by the user as a
-[[WikiLink]] into a wiki page name.
+[[ikiwiki/WikiLink]] into a wiki page name.
#### `srcfile($;$)`
To make an internal use page, register a filename extension that starts
with "_". Internal use pages cannot be edited with the web interface,
-generally shouldn't contain wikilinks or preprocessor directives (use
+generally shouldn't contain [[WikiLinks|ikiwiki/WikiLink]] or preprocessor directives (use
either on them with extreme caution), and are not matched by regular
PageSpecs glob patterns, but instead only by a special `internal()`
[[ikiwiki/PageSpec]].
IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is
how it will be accessed in a [[ikiwiki/PageSpec]]. The function will be passed
two parameters: The name of the page being matched, and the thing to match
-against. It may also be passed additional, named parameters. It should return
-a IkiWiki::SuccessReason object if the match succeeds, or an
-IkiWiki::FailReason object if the match fails.
+against. It may also be passed additional, named parameters.
+
+It should return a IkiWiki::SuccessReason object if the match succeeds, or
+an IkiWiki::FailReason object if the match fails. If the match cannot be
+attempted at all, for any page, it can instead return an
+IkiWiki::ErrorReason object explaining why.
### Setup plugins
For example, your plugin might want to override `displaytime`, to change
the html markup used when displaying a date. Or it might want to override
`IkiWiki::formattime`, to change how a date is formatted. Or perhaps you
-want to override `bestlink` and change how ikiwiki deals with WikiLinks.
+want to override `bestlink` and change how ikiwiki deals with [[WikiLinks|ikiwiki/WikiLink]].
By venturing into this territory, your plugin is becoming tightly tied to
ikiwiki's internals. And it might break if those internals change. But
sipb-www / ikiwiki.git / blobdiff