doc/plugins/contrib/trail.mdwn

   1 [[!tag type/chrome patch]]
   2 [[!template id=gitbranch branch=smcv/trail author="[[smcv]]"]]
   3
   4 Available from [[smcv]]'s git repository, in the `trail` branch. This
   5 plugin aims to solve [[todo/wikitrails]] in a simpler way.
   6
   7 Joey: what do you think of this plugin? If you like the general approach
   8 and are likely to include it in ikiwiki, I'll try to modify
   9 [[plugins/contrib/album]] to be based on it, rather than partially
  10 reinventing it.
  11
  12 This plugin can benefit from
  13 [[another_of_my_branches|todo/inline_plugin:_specifying_ordered_page_names]]
  14 but does not require it.
  15
  16 Bugs:
  17
  18 * \[[!inline pages="..." trail=yes]] currently tries to work out
  19   what pages are in the trail, and their order, at scan time. That
  20   won't work, because matching a pagespec at scan time is
  21   unreliable - pages we want might not have been scanned yet! I
  22   haven't worked out a solution for this. I think
  23   \[[!inline pagenames="..." trail=yes]]
  24   ([[patch_required|todo/inline_plugin:_specifying_ordered_page_names]])
  25   would be safe, though.
  26
  27 ----
  28
  29 [[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
  30
  31 It's sometimes useful to have "trails" of pages in a wiki, as a guided
  32 tour, sequence of chapters etc. In this plugin, a trail is represented
  33 by a page, and the pages in the trail are indicated by specially marked
  34 links within that page.
  35
  36 If using the default `page.tmpl`, each page automatically displays the
  37 trails that it's a member of (if any), with links to the trail and to
  38 the next and previous members.
  39
  40 The `traillink` [[ikiwiki/directive]] is used to record which pages
  41 are in a trail, and simultaneously link to them. Alternatively, the
  42 [[ikiwiki/directive/inline]] directive can be used with `trail=yes`
  43 to record the inlined pages as part of the trail, in the order in
  44 which they are inlined.
  45
  46 ## Directives
  47
  48 (These will go to the appropriate pages in [[ikiwiki/directive]] if this
  49 plugin is included in ikiwiki.)
  50
  51 ### traillink
  52
  53 The `traillink` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
  54 plugin. This directive appears on the page representing a trail. It acts
  55 as a visible [[ikiwiki/WikiLink]], but also records the linked page as
  56 a member of the trail.
  57
  58 Various syntaxes can be used:
  59
  60     \[[!traillink Badgers]]
  61     \[[!traillink How_to_find_mushrooms_using_badgers|badgers]]
  62     \[[!traillink badgers text="How to find mushrooms using badgers"]]
  63
  64 ### trailoptions
  65
  66 The `trailoptions` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
  67 plugin. This directive appears on the page representing a trail, and
  68 produces no output.
  69
  70 Currently, the only option supported is `[[!trailoptions circular=yes]]`,
  71 which adds links between the first and last pages, turning the trail into
  72 a circle.