Welcome to 2019
[ikiwiki.git] / 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 * "`glob(someglob)`" - matches pages and other files that match the given glob.
28   Just writing the glob by itself is actually a shorthand for this function.
29 * "`page(glob)`" - like `glob()`, but only matches pages, not other files
30 * "`link(page)`" - matches only pages that link to a given page (or glob)
31 * "`tagged(tag)`" - matches pages that are tagged or link to the given tag (or
32   tags matched by a glob)
33 * "`backlink(page)`" - matches only pages that a given page links to
34 * "`creation_month(month)`" - matches only files created on the given month
35   number
36 * "`creation_day(mday)`" - or day of the month
37 * "`creation_year(year)`" - or year
38 * "`created_after(page)`" - matches only files created after the given page
39   was created
40 * "`created_before(page)`" - matches only files created before the given page
41   was created
42 * "`internal(glob)`" - like `glob()`, but matches even internal-use 
43   pages that globs do not usually match.
44 * "`title(glob)`", "`author(glob)`", "`authorurl(glob)`",
45   "`license(glob)`", "`copyright(glob)`", "`guid(glob)`" 
46   - match pages that have the given metadata, matching the specified glob.
47 * "`user(username)`" - tests whether a modification is being made by a
48   user with the specified username. If openid is enabled, an openid can also
49   be put here. Glob patterns can be used in the username. For example, 
50   to match all openid users, use `user(*://*)`
51 * "`admin()`" - tests whether a modification is being made by one of the
52   wiki admins.
53 * "`ip(address)`" - tests whether a modification is being made from the
54   specified IP address. Glob patterns can be used in the address. For
55   example, `ip(127.0.0.*)`
56 * "`comment(glob)`" - matches comments to a page matching the glob.
57 * "`comment_pending(glob)`" - matches unmoderated, pending comments.
58 * "`postcomment(glob)`" - matches only when comments are being 
59   posted to a page matching the specified glob
60
61 For example, to match all pages in a blog that link to the page about music
62 and were written in 2005:
63
64         blog/* and link(music) and creation_year(2005)
65
66 Note the use of "and" in the above example, that means that only pages that
67 match each of the three expressions match the whole. Use "and" when you
68 want to combine expression like that; "or" when it's enough for a page to
69 match one expression. Note that it doesn't make sense to say "index and
70 SandBox", since no page can match both expressions.
71
72 More complex expressions can also be created, by using parentheses for
73 grouping. For example, to match pages in a blog that are tagged with either
74 of two tags, use:
75
76         blog/* and (tagged(foo) or tagged(bar))
77
78 Note that page names in PageSpecs are matched against the absolute
79 filenames of the pages in the wiki, so a pagespec "foo" used on page
80 "a/b" will not match a page named "a/foo" or "a/b/foo". To match
81 relative to the directory of the page containing the pagespec, you can
82 use "./". For example, "./foo" on page "a/b" matches page "a/foo".
83
84 To indicate the name of the page the PageSpec is used in, you can
85 use a single dot. For example, `link(.)` matches all the pages
86 linking to the page containing the PageSpec.