Linking rules

Upstream rules

Ikiwiki haw LinkingRules to specify which page a link targets.

To link to or from a SubPage, you can normally use a regular WikiLink that does not contain the name of the parent directory of the SubPage. Ikiwiki descends the directory hierarchy looking for a page that matches your link.

For example, if FooBar/SubPage links to “OtherPage”, ikiwiki will first prefer pointing the link to FooBar/SubPage/OtherPage if it exists, next to FooBar/OtherPage and finally to OtherPage in the root of the wiki.

Note that this means that if a link on FooBar/SomePage to “OtherPage” currently links to OtherPage, in the root of the wiki, and FooBar/OtherPage is created, the link will change to point to FooBar/OtherPage. On the other hand, a link from BazBar to “OtherPage” would be unchanged by this creation of a SubPage of FooBar.

You can also specify a link that contains a directory name, like “FooBar/OtherPage” to more exactly specify what page to link to. This is the only way to link to an unrelated SubPage.

You can use this to, for example, to link from BazBar to “FooBar/SubPage”, or from BazBar/SubPage to “FooBar/SubPage”.

You can also use “/” at the start of a link, to specify exactly which page to link to, when there are multiple pages with similar names and the link goes to the wrong page by default. For example, linking from “FooBar/SubPage” to “/OtherPage” will link to the “OtherPage” in the root of the wiki, even if there is a “FooBar/OtherPage”.

Also, if the wiki is configured with a userdir, you can link to pages within the userdir without specifying a path to them. This is to allow for easy linking to a user’s page in the userdir, to sign a comment. These links are checked for last of all.

Experimentation

I created a toy site with several pages:?

index.mdwn
a.mdwn
b.mdwn
c.mdwn
cc.mdwn
d.mdwn

Each contained a wiki link to c. On pages b, cc, and d, the link was resolved to the page c. On c, it was resolved as a self-link. On index and a, it was not resolved.

My re-phrasing

A relative link on a page refers to a direct subpage, if it exists, or to a sibling page, if that exists, or to an ancestor, if one exists, or to a page at the root of the site, if that exists.

An absolute link (starts with /) is always relative to the root of the site.

Test cases

Assume a site with the following pages (as paths relative to the root of the site):

foo
foo/bar
foo/bar/xyzzy
foo/bar/xyzzy/yo
foo/yo
foo/yo/xyzzy
bar
yo

A link bar on each of these pages is resolved as in the table below.

Resolving a relative link `bar` on page
page	link resolves to	relative from page	note
`foo`	`foo/bar`	`bar`	direct subpage
`foo/yo`	`foo/bar`	`../bar`	sibling
`foo/bar`	`foo/bar`	`../../bar`	self link
`foo/bar/xyzzy`	`foo/bar`	`../bar`	ancestor
`foo/bar/xyzzy/yo`	`foo/bar`	`../../bar`	ancestor
`foo/yo/xyzzy`	`bar`	`../../../bar`	root
`bar`	`bar`	`bar`	self link
`yo`	`bar`	`bar`	sibling

In the table above, on the first two rows a subpage or a sibling exists. In the rest, neither exists, so the link resolves to the top level bar.

Question: should the link on foo/bar resolve to itself?

markdown and HTML files and relative HTML links
markdown	HTML page	`href` on page
`foo.md`	`foo/index.html`	`bar/`
`foo/yo.mdwn`	`foo/yo/index.html`	`../bar/`
`foo/bar.md`	`foo/bar/index.html`	`./`
`foo/bar/xyzzy`	`foo/bar/xyzzy/index.html`	`../../bar/`
`foo/bar/xyzzy/yo`	`foo/bar/xyzzy/yo/index.html`	`../../../bar/`
`foo/yo/xyzzy.md`	`foo/yo/xyzzy/index.html`	`../../../bar/`
`bar.md`	`bar/index.html`	`./`
`yo.md`	`yo/index.html`	`bar/`