%audience% authors (basic)
The WikiTrails feature allows wiki authors to create "trails" through sequences of pages in the wiki.

!!Creating a trail

Before you can use a trail through a group of pages, you have to create a "trail index" on a separate page, which we will call the "trail index page". On that trail index page, you simply create a numbered or bulleted list of links. (So every numbered or bulleted list of links implicitly creates a trail.) It is important that each page name (link) be the first item following each bullet.

An example trail index page: a list like

    [@
    * [[TrailPage1]]
    * Some text. (This won't be in the trail.)
    * [[TrailPage2]]
    ** [[TrailPage3]]
    ** [[TrailPage4]] some other text [[IrrelevantWikiPage]]
    ** Yet some other text. [[AnotherIrrelevantWikiPage]]. (This won't be in the trail.)
    ** %center%[[would-beTrailPage]] (This won't be in the trail.)
    @]

creates the following "wikitrail":

[= TrailPage1 <-> TrailPage2 <-> TrailPage3 <-> TrailPage4 =]

Observations:

# In general, indentation levels in the page list don't matter -- trails are a linear sequence of pages.
# A page is part of the trail only if the page link immediately follows the list markup.

!!Using the trail

What makes a trail "work" is adding ''trail markup'' on the pages in the trail (i.e. the pages that are listed in the bullet/numbered list on the trail index page).

To build a trail, add  ''trail markup'' like [@<<|[[TrailIndexPage]]|>>@] to a page, where `TrailIndexPage is the page, described above, containing the bulleted list of pages in the trail.  PmWiki will display the trail markup with links to any previous and next pages in the trail. 

The trail markup can be placed anywhere in a page, and a page can contain multiple trail markups.  If you are adding a trail to every page in a group, consider setting the trail markup in the [[Group Headers | GroupHeader]] or GroupFooter pages instead of on every individual page in your group.

PmWiki defines 2 trail markups:

* [@<<|[[TrailIndexPage]]|>>@] displays as "[=<< PreviousPage | TrailIndexPage | NextPage >>=]".

* [@<|[[TrailIndexPage]]|>@] displays as "[=< PreviousPage | TrailIndexPage | NextPage >=]", except the appropriate arrow is omitted at the beginning and end of the trail.

!!Path trail 

[@^|[[TrailIndexPage]]|^@] treats the list levels as a hierarchy and displays the "path" to reach the current page (i.e., a "breadcrumb" trail).  In the example trail above, the markup [@^|TrailIndexPage|^@] on [@TrailPage4@] would display as "[=TrailIndexPage | TrailPage2 | TrailPage4=]".

Wiki administrators can change the trail separator of the "path" trail ( [@^|[[TrailIndexPage]]|^@] ) from the default | by setting the variable $TrailPathSep in the ''config.php'' file. For instance $TrailPathSep = ' > '; will output "[=TrailIndexPage > TrailPage2 > TrailPage4=]".

!!Circular trails

Typically, a trail is a linear list with a first and a last page. However, the trail can be made "circular" by repeating the first page as the last item in the trail index:

    [@
    * [[TrailPage1]]
    * [[TrailPage2]]
    ...
    * [[TrailPageN]]
    * [[TrailPage1]]
    @]

If the trail index page is intended to be read by others, the last item can be made invisible using [@%item comment%@]:

    [@
    * [[TrailPage1]]
    * [[TrailPage2]]
    ...
    * [[TrailPageN]]
    * [[TrailPage1]] %item comment%
    @]

!! Cross Group Trails

Trail pages on both sides of group boundaries must be fully qualified with group names.


!!Other notes

The [@%trail%@] markup that is used in many of PmWiki's documentation pages is just a [[WikiStyle(s)]] that creates a grey background, and is not required for WikiTrails to work. It's defined in the [[PmWiki.GroupHeader]] page.

To get it to work, you must create the index page for the trail and the trail pages as stated above. Then you must define the wikistyle you want in the groupheader of the group you want it to appear in. Then you must refer or call to it with the [@%trail%@] markup from the trail pages.

%trail%<<|[[DocumentationIndex]]|>>