ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / todo / alias_directive.mdwn
1 An alias directive could work like an inverse redirect, but in a more
2 maintainable way. Currently, a page might have several redirects leading to it,
3 without an easy way of enumerating them. Therefore, the following directive is
4 suggested for addition (possibly by means of a plugin):
5
6 > The `alias` and `aliastext` directives implicitly create
7 > redirect pages to the page they are used on. If two or more pages claim a
8 > non-existing page to be an alias, a disambiguation page will automatically
9 > generated. If an existing page is claimed as an alias, it will be prefixed
10 > with a note that its topic is also an alias for other pages.
11 >
12 > All aliases to a page are automatically listed below the backlink and tag
13 > lists at the bottom of a page by default. This can be configured globally by
14 > setting the `alias_list` configuration option to `false`, or set explicitly
15 > per alias by specifying `list=true` or `list=false`.
16 >
17 > Similar to the `taglink` directive, `aliastext` produces the alias name as
18 > well as registering it.
19 >
20 > ## Usage example
21 >
22 > `Greece.mdwn`:
23 >
24 > >     Greece, also known as \[[!aliastext Hellas]] and officially the
25 > >     \[[!aliastext "Hellenic Republic"]], is a …
26 > >     
27 > >     <!-- there are so many people who misspell this, let's create a redirect -->
28 > >     \[[!alias Grece list=false]] 
29 >
30 > This page by itself will redirect from the "Hellas", "Hellenic Republic" and
31 > "Grece" pages as if they both contained just:
32 >
33 > >     \[[!meta redir="Greece"]]
34 >
35 > If, on the other hand, `Hellas Planitia` also claims `[[!alias Hellas]]`, the
36 > Hellas page will look like this:
37 >
38 > >     **Hellas** is an alias for the following pages:
39 > >
40 > >     * \[[Greece]]
41 > >     * \[[Hellas Planitia]]
42
43 The proposed plugin/directive could be extended, eg. by also including
44 old-style redirects in the alias list, but that might introduce unwanted
45 coupling with the meta directive.
46
47 -----------------
48
49 On second thought, implementing this might have similarities with
50 [[todo/auto-create tag pages according to a template]] -- the auto-created
51 pages would, if the way of the alias directive is followed, not create physical
52 files, though, but be created just when someone edits them.
53
54 If multiple plugins do such a trick, they would have to fight over who comes
55 first. If, for example, we have a setup where not yet created tag pages are
56 automatically generated as "\[[!inline  pages="link(<TMPL_VAR TAG>)"
57 archive="yes"]]" and aliases are enabled, and a non-tag pages grabs a tag as an
58 alias (as to redirect all taglinks of the tag to itself), there are two
59 possibilities:
60
61 * The autotag plugin comes first:
62     * autotag sees the missing tag and creates its "\[[!inline" stuff
63     * alias sees that there is already content and adds its prefix
64 * The alias plugin comes first (this is the prefered way):
65     * alias sees the empty page, sees it is not contested by other alias
66       directives and creates its "\[[!meta" redirect
67     * autotag sees there is already content and doesn't do anything
68
69 That issue could be handled with "priority number" on the hook, with plugins
70 with a lower number being called first.
71
72 [[!tag wishlist]]