(no commit message)
[ikiwiki] / 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 Bugs:
13
14 * \[[!inline pages="..." trail=yes]] currently tries to work out
15   what pages are in the trail, and their order, at scan time. That
16   won't work, because matching a pagespec at scan time is
17   unreliable - pages we want might not have been scanned yet! I
18   haven't worked out a solution for this. I think
19   \[[!inline pagenames="..." trail=yes]] would be safe, though.
20
21 ----
22
23 [[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
24
25 It's sometimes useful to have "trails" of pages in a wiki, as a guided
26 tour, sequence of chapters etc. In this plugin, a trail is represented
27 by a page, and the pages in the trail are indicated by specially marked
28 links within that page.
29
30 If using the default `page.tmpl`, each page automatically displays the
31 trails that it's a member of (if any), with links to the trail and to
32 the next and previous members.
33
34 The `traillink` [[ikiwiki/directive]] is used to record which pages
35 are in a trail, and simultaneously link to them. Alternatively, the
36 [[ikiwiki/directive/inline]] directive can be used with `trail=yes`
37 to record the inlined pages as part of the trail, in the order in
38 which they are inlined.
39
40 ## Directives
41
42 (These will go to the appropriate pages in [[ikiwiki/directive]] if this
43 plugin is included in ikiwiki.)
44
45 ### traillink
46
47 The `traillink` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
48 plugin. This directive appears on the page representing a trail. It acts
49 as a visible [[ikiwiki/WikiLink]], but also records the linked page as
50 a member of the trail.
51
52 Various syntaxes can be used:
53
54     \[[!traillink Badgers]]
55     \[[!traillink How_to_find_mushrooms_using_badgers|badgers]]
56     \[[!traillink badgers text="How to find mushrooms using badgers"]]
57
58 ### trailoptions
59
60 The `trailoptions` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
61 plugin. This directive appears on the page representing a trail, and
62 produces no output.
63
64 Currently, the only option supported is `[[!trailoptions circular=yes]]`,
65 which adds links between the first and last pages, turning the trail into
66 a circle.