Move trail out of the contrib directory in preparation for eventual merge

[ikiwiki.git] / doc / plugins / trail.mdwn

diff --git a/doc/plugins/trail.mdwn b/doc/plugins/trail.mdwn
new file mode 100644 (file)
index 0000000..406d402
--- /dev/null
+++ b/doc/plugins/trail.mdwn
@@ -0,0 +1,76 @@
+[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
+[[!tag type/chrome]]
+
+This plugin provides the [[ikiwiki/directive/trailoptions]],
+[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
+[[ikiwiki/directive/trailitems]]
+and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]].
+
+It's sometimes useful to have "trails" of pages in a wiki where each
+page links to the next and/or previous page. For instance, you could use
+this for a guided tour, sequence of chapters, or sequence of blog posts.
+
+In this plugin, a trail is represented by a page, and the pages in the
+trail are indicated by specially marked links within that page, or by
+including groups of pages with a [[ikiwiki/directive]].
+
+If using the default `page.tmpl`, each page automatically displays the
+trails that it's a member of (if any), with links to the trail and to
+the next and previous members. HTML `<link>` tags with the `prev`,
+`next` and `up` relations are also generated.
+
+The [[ikiwiki/directive/trailoptions]] directive sets options for the
+entire trail.
+
+Pages can be included in a trail in various ways:
+
+* The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]],
+  and at the same time adds the matching pages (from `pages` or `pagenames`)
+  to the trail. One use is to navigate through all posts in a blog:
+
+        \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
+          feedshow=10 quick=yes]]
+
+  This directive only works if the [[!iki plugins/inline desc=inline]]
+  plugin is also enabled.
+
+* The [[ikiwiki/directive/trailitems]] directive has optional `pages` and
+  `pagenames` options which behave the same as in [[inline]], but don't
+  produce any output in the page, so you can have trails that don't list
+  all their pages.
+
+* The [[ikiwiki/directive/traillink]] directive makes a visible link
+  and also adds the linked page to the trail. This will typically be
+  used in a bullet list, but could also be in paragraph text:
+
+        * [[!traillink Introduction]]
+        * [[!traillink "Chapter 1"]]
+        * [[!traillink Chapter_2]]
+        * [[!traillink Appendix_A]]
+
+  or
+
+        To use this software you must \[[!traillink install]] it,
+        \[[!traillink configuration text="configure it"]],
+        and finally \[[!traillink running|run_it]].
+
+  This also counts as a [[ikiwiki/WikiLink]] for things like the `link()`
+  [[ikiwiki/PageSpec]] item.
+
+* The [[ikiwiki/directive/trailitem]] directive adds a page to the trail
+  like `traillink`, but produces an invisible link, rather like `\[[!tag]]`:
+
+        To use this software you must \[[!traillink install]] it,
+        \[[!trailitem installing_from_packages]]
+        \[[!trailitem installing_from_source]]
+        \[[!traillink configuration text="configure it"]],
+        and finally \[[!traillink running|run_it]].
+        \[[!trailitem troubleshooting]]
+
+  Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
+  there's no visible link.
+
+You can mix several of these directives in one page. The resulting
+trail will contain all of the pages matched by any of the directives,
+in the same order that the directives appear (unless you use the `sort` or
+`reverse` options on `\[[!trailoptions]]`).