diff options
Diffstat (limited to 'doc/plugins/trail.mdwn')
-rw-r--r-- | doc/plugins/trail.mdwn | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/doc/plugins/trail.mdwn b/doc/plugins/trail.mdwn new file mode 100644 index 000000000..14b97e35a --- /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]], +and [[ikiwiki/directive/trailitems]] [[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/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 [[!iki plugins/inline desc=inline]] + plugins are both 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]]`). |