ikiwiki/doc/plugins/trail.mdwn

77 lines
3.2 KiB
Plaintext
Raw Normal View History

2011-11-10 00:43:00 +01:00
[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
[[!tag type/chrome]]
2011-06-05 19:11:32 +02:00
This plugin provides the [[ikiwiki/directive/trailoptions]],
2011-11-10 00:43:00 +01:00
[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
and [[ikiwiki/directive/trailitems]] [[directives|ikiwiki/directive]].
2009-07-18 19:46:55 +02:00
2011-11-10 00:43:00 +01:00
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.
2011-06-05 19:11:32 +02:00
2011-11-10 00:43:00 +01:00
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]].
2009-07-18 19:46:55 +02:00
2011-11-10 00:43:00 +01:00
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.
2009-07-18 19:46:55 +02:00
The [[ikiwiki/directive/trailoptions]] directive sets options for the
entire trail.
2011-11-10 00:43:00 +01:00
Pages can be included in a trail in various ways:
2011-06-05 19:11:32 +02:00
* 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:
2009-07-18 19:46:55 +02:00
\[[!inline pages="page(./posts/*) and !*/Discussion" archive=yes
feedshow=10 quick=yes trail=yes]]
2009-07-18 19:46:55 +02:00
This only works if the trail and [[!iki plugins/inline desc=inline]]
plugins are both enabled.
2011-06-05 19:11:32 +02:00
* The [[ikiwiki/directive/trailitems]] directive has optional `pages` and
2011-11-10 00:43:00 +01:00
`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.
2011-06-05 19:11:32 +02:00
2011-11-10 00:43:00 +01:00
* 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:
2011-06-05 19:11:32 +02:00
2011-11-10 00:43:00 +01:00
* [[!traillink Introduction]]
* [[!traillink "Chapter 1"]]
* [[!traillink Chapter_2]]
* [[!traillink Appendix_A]]
2011-06-05 19:11:32 +02:00
2011-11-10 00:43:00 +01:00
or
2011-06-05 19:11:32 +02:00
2011-11-10 00:43:00 +01:00
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]]`:
2011-06-05 19:11:32 +02:00
2011-11-10 00:43:00 +01:00
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]]
2011-06-05 19:11:32 +02:00
2011-11-10 00:43:00 +01:00
Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
there's no visible link.
2011-06-05 19:11:32 +02:00
You can mix several of these directives in one page. The resulting
2011-11-10 00:43:00 +01:00
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]]`).