diff options
authorJonas Smedegaard <>2015-01-22 15:02:35 +0100
committerJonas Smedegaard <>2015-01-22 15:02:35 +0100
commit224ca3cd99c6378f1bad4c69366d7b522e471e22 (patch)
parent7609bea2373599512f0be20a688941f0b84b7916 (diff)
Sync with ikiwiki 3.20141016.1.
7 files changed, 90 insertions, 14 deletions
diff --git a/ikiwiki/directive/comment.mdwn b/ikiwiki/directive/comment.mdwn
index 398130e..590ad5c 100644
--- a/ikiwiki/directive/comment.mdwn
+++ b/ikiwiki/directive/comment.mdwn
@@ -1,7 +1,15 @@
The `comment` directive is supplied by the
-[[!iki plugins/comments desc=comments]] plugin, and is used to add a comment
-to a page. Typically, the directive is the only thing on a comment page,
-and is filled out by the comment plugin when a user posts a comment.
+[[!iki plugins/comments desc=comments]] plugin. There should
+be one comment directive in each source file with extension
+`._comment` or `._comment_pending`, and the directive should not
+appear anywhere else. Comments are normally created via the web,
+in which case ikiwiki automatically creates a suitable
+`._comment` file.
+Wiki administrators can also commit comment files to the version
+control system directly: they should be named starting with
+the *comments\_pagename* config option (usually `comment_`)
+and ending with `._comment`, for instance `comment_42._comment`.
@@ -17,7 +25,8 @@ Example:
## usage
The only required parameter is `content`, the others just add or override
-metadata of the comment.
+metadata for the comment. Many parameters are shortcuts for [[meta]]
* `content` - Text to display for the comment.
Note that [[directives|ikiwiki/directive]]
diff --git a/ikiwiki/directive/edittemplate.mdwn b/ikiwiki/directive/edittemplate.mdwn
index 569c281..70bd2ad 100644
--- a/ikiwiki/directive/edittemplate.mdwn
+++ b/ikiwiki/directive/edittemplate.mdwn
@@ -2,7 +2,7 @@ The `edittemplate` directive is supplied by the [[!iki plugins/edittemplate desc
This directive allows registering template pages, that provide default
content for new pages created using the web frontend. To register a
-template, insert a [[ikiwiki/directive/template]] directive on some other
+template, insert an [[ikiwiki/directive/edittemplate]] directive on some other
\[[!edittemplate template="bugtemplate" match="bugs/*"]]
@@ -18,17 +18,37 @@ the directive displaying a note about the template being registered, add
Often the template page contains a simple skeleton for a particular type of
-page. For the bug report pages in the above example, it might look
-something like:
+page, wrapped in a [[templatebody]] directive. For the bug report pages in
+the above example, it might look something like:
+ \[[!templatebody <<ENDBODY
Reproducible: y/n
The template page can also contain [[!cpan HTML::Template]] directives,
-like other ikiwiki [[templates]]. Currently only one variable is
-set: `<TMPL_VAR name>` is replaced with the name of the page being
+like other ikiwiki [[templates]].
+These variables might be set:
+* `<TMPL_VAR name>` is replaced with the name of the page being
+ created.
+* `<TMPL_VAR uuid>` is replaced with a version 4 (random) UUID
+ suitable for use in `\[[!meta guid="urn:uuid:<TMPL_VAR uuid>"]]`.
+ (Requires the `UUID::Tiny` Perl module if not running on Linux.)
+* `<TMPL_VAR time>` is replaced with the current (template generation)
+ time using a fixed format (RFC 3339, `%Y-%m-%dT%H:%M:%SZ`),
+ suitable for use in `\[[!meta date="<TMPL_VAR time>"]]`
+ (see [[meta]]) or `\[[!date "<TMPL_VAR time>"]]` (see [[date]]).
+Text outside the [[templatebody]] directive is not part of the template,
+and can be used to document it.
+If the template does not contain a [[templatebody]] directive, the entire
+source of the page is used for the template. This is deprecated.
[[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/format.mdwn b/ikiwiki/directive/format.mdwn
index 7d11d22..04ed139 100644
--- a/ikiwiki/directive/format.mdwn
+++ b/ikiwiki/directive/format.mdwn
@@ -18,7 +18,7 @@ some other format:
-Note that if the highlight plugin is enabled, this directive can also be
+Note that if the [[!iki plugins/highlight desc=highlight]] plugin is enabled, this directive can also be
used to display syntax highlighted code. Many languages and formats are
supported. For example:
diff --git a/ikiwiki/directive/img.mdwn b/ikiwiki/directive/img.mdwn
index cda62b5..08d1589 100644
--- a/ikiwiki/directive/img.mdwn
+++ b/ikiwiki/directive/img.mdwn
@@ -28,6 +28,9 @@ to the full size version. By default it does; set "link=somepage" to link
to another page instead, or "link=no" to disable the link, or
"link=http://url" to link to a given url.
+The `pagenumber` parameter selects which of multiple images should be rendered;
+this is relevant mainly for GIF and PDF source images.
You can also set default values that will be applied to all later images on
the page, unless overridden. Useful when including many images on a page.
diff --git a/ikiwiki/directive/inline.mdwn b/ikiwiki/directive/inline.mdwn
index d2f6d1d..a4632a5 100644
--- a/ikiwiki/directive/inline.mdwn
+++ b/ikiwiki/directive/inline.mdwn
@@ -51,6 +51,8 @@ directive. These are the commonly used ones:
Set to 0 to show all matching pages.
* `archive` - If set to "yes", only list page titles and some metadata, not
full contents.
+* `title` - Sets the title of the rss feed if one is generated.
+ Defaults to the name of the page.
* `description` - Sets the description of the rss feed if one is generated.
Defaults to the name of the wiki.
* `skip` - Specify a number of pages to skip displaying. Can be useful
diff --git a/ikiwiki/directive/template.mdwn b/ikiwiki/directive/template.mdwn
index 9e3ae54..dd1ca3d 100644
--- a/ikiwiki/directive/template.mdwn
+++ b/ikiwiki/directive/template.mdwn
@@ -31,16 +31,25 @@ large chunks of marked up text to be embedded into a template:
## Creating a template
-The template is a regular wiki page, located in the `templates/`
+The template is in a regular wiki page, located in the `templates/`
subdirectory inside the source directory of the wiki.
+The contents of the [[templatebody]] directive are used as the
+template. Anything outside that directive is not included in the template,
+and is usually used as documentation describing the template.
+If the template does not contain a [[templatebody]] directive, the entire
+source of the page is used for the template. This is deprecated, because
+it leads to the template markup being interpreted as ordinary
+page source when the page is built, as well as being used as the template.
Alternatively, templates can be stored in a directory outside the wiki,
as files with the extension ".tmpl".
By default, these are searched for in `/usr/share/ikiwiki/templates`,
the `templatedir` setting can be used to make another directory be searched
first. When referring to templates outside the wiki source directory, the "id"
-parameter is not interpreted as a pagespec, and you must include the full filename
-of the template page, including the ".tmpl" extension. E.g.:
+parameter is not interpreted as a pagespec, you must include the full filename
+of the template page including the ".tmpl" extension,
+and the templatebody directive is not used. E.g.:
\[[!template id=blogpost.tmpl]]
@@ -63,6 +72,7 @@ few things:
Here's a sample template:
+ \[[!templatebody <<ENDBODY
<span class="infobox">
Name: \[[<TMPL_VAR raw_name>]]<br />
Age: <TMPL_VAR age><br />
@@ -76,6 +86,10 @@ Here's a sample template:
<TMPL_VAR notes>
+ This template describes a person. Parameters: name, age,
+ color (favorite color, optional), notes (optional).
The filled out template will be formatted the same as the rest of the page
that contains it, so you can include WikiLinks and all other forms of wiki
diff --git a/ikiwiki/directive/templatebody.mdwn b/ikiwiki/directive/templatebody.mdwn
new file mode 100644
index 0000000..dfadb2c
--- /dev/null
+++ b/ikiwiki/directive/templatebody.mdwn
@@ -0,0 +1,28 @@
+The `templatebody` directive is supplied by the
+[[!iki plugins/templatebody desc=templatebody]] plugin.
+This directive allows wiki pages to be used as templates
+for the [[template]] or [[edittemplate]] directive, without having
+[[!cpan HTML::Template]] markup interpreted as wiki markup when that
+page is built.
+This directive does not produce any output in the wiki page that
+defines the template; the rest of that page can be used to to document
+how to use the template.
+The first, un-named parameter is the content of the template.
+Because templates often contain [[directives|ikiwiki/directive]], it's
+convenient to use the "here-document" syntax for it:
+ \[[!templatebody <<ENDBODY
+ [[!meta title="<TMPL_VAR name>"]]
+ [[!tag person]]
+ <dl>
+ <dt>Name:</dt><dd><TMPL_VAR name></dd>
+ <dt>Age:</dt><dd><TMPL_VAR age></dd>
+ </dl>
+ <TMPL_VAR description>
+[[!meta robots="noindex, follow"]]