Document trail plugin v3

4 files changed, 60 insertions, 0 deletions

diff --git a/doc/plugins/contrib/ikiwiki/directive/trail.mdwn b/doc/plugins/contrib/ikiwiki/directive/trail.mdwn
new file mode 100644
index 000000000..cf8c370a7
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/trail.mdwn
@@ -0,0 +1,24 @@
+The `trail` directive is supplied by the
+[[!iki plugins/contrib/trail desc=trail]] plugin. It sets options for the
+trail represented by this page, and can also add pages to the trail. Example usage:
+
+    \[[!trail sort="meta(title)" circular="no"]]
+
+The available options are:
+
+* `pages`: adds pages that match a [[ikiwiki/PageSpec]] to the trail
+
+* `pagenames`: adds a space-separated list of pages to the trail,
+  with the same [[SubPage/LinkingRules]] as for a [[ikiwiki/WikiLink]]
+
+* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
+  items of the trail are ordered according to the first link to each item
+  found on the trail page
+
+* `reverse`: reverses the [[ikiwiki/pagespec/sorting]] order
+
+* `circular`: if set to `yes` or `1`, the trail is made into a loop by
+  making the last page's "next" link point to the first page, and the first
+  page's "previous" link point to the last page
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
new file mode 100644
index 000000000..4fae7ac8a
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
@@ -0,0 +1,11 @@
+The `trailinline` directive is provided by the
+[[!iki plugins/contrib/trail desc=trail]]
+plugin. It is equivalent to combining [[ikiwiki/directive/trail]] and
+[[ikiwiki/directive/inline]] directives with the same options.
+
+A typical use is to navigate through all posts in a blog:
+
+      \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
+        feedshow=10 quick=yes]]
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn
new file mode 100644
index 000000000..73b1985a5
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn
@@ -0,0 +1,9 @@
+The `trailitem` directive is supplied by the
+[[!iki plugins/contrib/trail desc=trail]] plugin. It is used like this:
+
+    \[[!trailitem some_other_page]]
+
+to add `some_other_page` to the trail represented by this page, without
+generating a visible hyperlink.
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
new file mode 100644
index 000000000..0e40e2411
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
@@ -0,0 +1,16 @@
+The `traillink` directive is supplied by the
+[[!iki plugins/contrib/trail desc=trail]]
+plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the
+linked page to the trail represented by the page containing the directive.
+
+In its simplest form, the first parameter is like the content of a WikiLink:
+
+    \[[!traillink some_other_page]]
+
+The displayed text can also be overridden, either with a `|` symbol or with
+a `text` parameter:
+
+    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
+    \[[!traillink some_other_page text="Click here to start the trail"]]
+
+[[!meta robots="noindex, follow"]]