doc/todo/wikitrails.mdwn

   1 ## summary
   2 at times it is useful to have a guided tour or trail through a subset of the pages of a wiki; in pmwiki, this is implemented as [wikitrails](http://www.pmwiki.org/wiki/PmWiki/WikiTrails).
   3
   4 ### smcv's implementation
   5
   6 ... is the out-of-tree [[plugins/trail]] plugin, see there for details.
   7
   8 > And will be the one landing in ikiwiki. So, I'm closing this bug report. [[done]] --[[Joey]]
   9
  10 ### chrysn's implementation
  11
  12 i'm working on a python xmlrpc plugin for ikiwiki to support wikitrails, both as a navigation feature (have "forward" and "back" links based on a sequence) and a modified inline that includes all pages in the trail with appropriate modifications (suitable for printing if necessary).
  13
  14 the current status is published on `git://prometheus.amsuess.com/ikiwiki-plugins`; as of now, i don't have a public demo of it.
  15
  16 feedback on both the concept and the code is very much appreciated by [[discussion]] or [email](mailto:chrysn@fsfe.org).
  17
  18 > update as of 2013: this implementation is kept in said ikiwiki-plugins directory for historical reference only; with the implementation nowadays available in ikiwiki, my implementation is obsolete. --[[chrysn]]
  19
  20 #### usage
  21
  22 two preprocessor commands are provided:
  23
  24 ##### \[[!trail index="my_indexpage"]]
  25
  26 embeds a navigation object with forward and back links as well as an indicator of the current position in the trail.
  27
  28 if index is not specified, a suitable page up the path is used.
  29
  30 this works very well together with the [[sidebar|plugins/sidebar]] plugin if the pages in a directory are roughly the same as the pages in the trail and the `index` is directory index page; just put the \[[!trail]] in the sidebar.
  31
  32 ##### \[[!trailinclude index="my_indexpage"]]
  33
  34 all pages linked from the index page are included in the same way as \[[!inline]] does, but in the proper sequence, with headings according to the indent in the source page and adoptions for the headings inside the page (a level 2 heading in a page that is a sub-sub-chapter in the whole trail will become a level 5 heading when trailincluded).
  35
  36 #### the index page
  37
  38 the index page is parsed as markdown; numbered lists and "`*`" bulleted lists are discovered.
  39
  40 #### current issues
  41
  42  * rebuilding --- currently, there is no propper rebuilding of pages (will use `will_render` and `add_depends`). care has to be taken of how not yet created pages play into this.
  43  * inline recursion --- there is simply no guard yet
  44  * navigation layout --- has to be both flexible and usable-by-default
  45  * heading shifting
  46   * currently only works for markdown
  47   * can break the limit of html's six heading levels
  48  * search for index page is currently next to hardcoded
  49  * reading the index --- markdown syntax parsing is currently on a it-can-use-what-i-produce level; maybe integrate with existing mdwn parser
  50  * uses undocumented titlepage command
  51    > Don't worry about that, titlepage isn't going anywhere, and will probably before a formal part of the api next time I consider api changes. --[[Joey]]