doc/ikiwiki/pagespec.mdwn

   1 [[!meta robots="noindex, follow"]]
   2 To select a set of pages, such as pages that are locked, pages
   3 whose commit emails you want subscribe to, or pages to combine into a
   4 blog, the wiki uses a PageSpec. This is an expression that matches
   5 a set of pages.
   6
   7 The simplest PageSpec is a simple list of pages. For example, this matches
   8 any of the three listed pages:
   9
  10         foo or bar or baz
  11
  12 More often you will want to match any pages that have a particular thing in
  13 their name. You can do this using a glob pattern. "`*`" stands for any part
  14 of a page name, and "`?`" for any single letter of a page name. So this
  15 matches all pages about music, and any [[SubPage]]s of the SandBox, but does
  16 not match the SandBox itself:
  17
  18         *music* or SandBox/*
  19
  20 You can also prefix an item with "`!`" to skip pages that match it. So to
  21 match all pages except for Discussion pages and the SandBox:
  22
  23         * and !SandBox and !*/Discussion
  24
  25 Some more elaborate limits can be added to what matches using these functions:
  26
  27 * "`link(page)`" - match only pages that link to a given page (or glob)
  28 * "`backlink(page)`" - match only pages that a given page links to
  29 * "`creation_month(month)`" - match only pages created on the given month
  30 * "`creation_day(mday)`" - or day of the month
  31 * "`creation_year(year)`" - or year
  32 * "`created_after(page)`" - match only pages created after the given page
  33   was created
  34 * "`created_before(page)`" - match only pages created before the given page
  35   was created
  36 * "`glob(someglob)`" - match pages that match the given glob. Just writing
  37   the glob by itself is actually a shorthand for this function.
  38 * "`internal(glob)`" - like `glob()`, but matches even internal-use
  39   pages that globs do not usually match.
  40 * "`title(glob)`", "`author(glob)`", "`authorurl(glob)`",
  41   "`license(glob)`", "`copyright(glob)`" - match pages that have the given
  42   metadata, matching the specified glob.
  43 * "`user(username)`" - tests whether a modification is being made by a
  44   user with the specified username. If openid is enabled, an openid can also
  45   be put here.
  46 * "`admin()`" - tests whether a modification is being made by one of the
  47   wiki admins.
  48 * "`ip(address)`" - tests whether a modification is being made from the
  49   specified IP address.
  50 * "`postcomment(glob)`" - matches only when comments are being
  51   posted to a page matching the specified glob
  52
  53 For example, to match all pages in a blog that link to the page about music
  54 and were written in 2005:
  55
  56         blog/* and link(music) and creation_year(2005)
  57
  58 Note the use of "and" in the above example, that means that only pages that
  59 match each of the three expressions match the whole. Use "and" when you
  60 want to combine expression like that; "or" when it's enough for a page to
  61 match one expression. Note that it doesn't make sense to say "index and
  62 SandBox", since no page can match both expressions.
  63
  64 More complex expressions can also be created, by using parentheses for
  65 grouping. For example, to match pages in a blog that are tagged with either
  66 of two tags, use:
  67
  68         blog/* and (link(tag/foo) or link(tag/bar))
  69
  70 Note that page names in PageSpecs are matched against the absolute
  71 filenames of the pages in the wiki, so a pagespec "foo" used on page
  72 "a/b" will not match a page named "a/foo" or "a/b/foo". To match
  73 relative to the directory of the page containing the pagespec, you can
  74 use "./". For example, "./foo" on page "a/b" matches page "a/foo".
  75
  76 ## Old syntax
  77
  78 The old PageSpec syntax was called a "GlobList", and worked differently in
  79 two ways:
  80
  81 1. "and" and "or" were not used; any page matching any item from the list
  82    matched.
  83 2. If an item was prefixed with "`!`", then no page matching that item
  84    matched, even if it matched an earlier list item.
  85
  86 For example, here is the old way to match all pages except for the SandBox
  87 and Discussion pages:
  88
  89         * !SandBox !*/Discussion
  90
  91 Using this old syntax is still supported. However, the old syntax is
  92 deprecated and will be removed at some point, and using the new syntax is
  93 recommended.