Plugin: trail
Author: Simon McVittie
Included in ikiwiki: yes
Enabled by default: no
Included in goodstuff: no
Currently enabled: no

This plugin provides the trailoptions, traillink, trailitem, and trailitems directives.

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 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 trailoptions directive sets options for the entire trail.

Pages can be included in a trail in various ways:

• The inline directive with trail="yes" 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:

    [[!inline  pages="page(./posts/*) and !*/Discussion" archive=yes
      feedshow=10 quick=yes trail=yes]]
  

  This only works if the trail and inline plugins are both enabled.

• The 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 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 WikiLink for things like the link() PageSpec item.

• The 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 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 ]]).