Links

(:Summary: PmWiki group header. Includes styles and trail.:)

(:Summary:Linking within and between wiki pages:) (:Audience: authors (basic) :) A key feature of Wiki Wiki Webs is the ease of creating hyper links in the text of a document. PmWiki provides multiple mechanisms for creating such links.

Links to other pages in the wiki

To create a link to another page, simply enclose the name of the page inside double square brackets, as in [[wiki sandbox]] or [[installation]]. These result in links to wiki sandbox and installation, respectively.

PmWiki creates a link by using the text inside the double brackets. It does this by removing spaces between words, and automatically capitalizing words following spaces or other punctuation (like ~). Thus [[Wiki sandbox]], [[wiki sandbox]], and [[WikiSandbox]] all display differently but create the same link to the page titled WikiSandbox.

In other words, PmWiki will automatically create the link path name using title case as a rule, but link text will display in the format you have entered it.

A suffix can also be added to the end of a link, which becomes part of the link text but not the target. Thus [[wiki sandbox]]es is a link to WikiSandbox but displays as wiki sandboxes.

Link text in (parentheses) will not be not displayed, so that [[(wiki) sandbox]] links to WikiSandbox and displays as sandbox.

Finally, you can specify the link text via a vertical brace, thus [[WikiSandbox | a play area]], which links to WikiSandbox but displays as a play area. You can use an arrow (->) to reverse the order of the text and target, as in [[a play area -> WikiSandbox]] (a play area).

Some sites also recognize WikiWord links, in which a camel case (capitalised) WikiWord appearing in the text is automatically treated as a link to a page of the same name.

Link shortcuts

Use of special characters in title is not a problem for PmWiki, but sometimes the character set is different from your computer and the server computer or the client computer that is used to read your wiki. Specially UTF-8 gives some problems. So it's better not to use these and keep ASCII characters if possible. Any page can have a (:title <name>:) directive to display a localized title instead of the page file name. In this case, the following tip is important and usefull.

[[PageName|+]] creates a link to PageName and uses that page's title as the link text, eg [[PmWiki.BasicEditing|+]] where the page Installation has the directive (:title BasicEditing:)=] gives Basic PmWiki editing rules.

[[PageName|#]] creates a reference link as shown below^[1].

[[!PageName]] creates a link to the PageName in the group called Category. See Categories.

[[~Author]] link creates a link to the page in the page called Author in the Profiles group. PmWiki will automatically generate that link for the current Author when it encounters three tilde characters (~) in a row (~~~). Adding a fourth tilde (~~~~) appends the current date and time.

Links to specific locations within a page -- "anchors"

To define a location within a page to which you may jump directly, use the markup [[#name]]. This creates an "anchor" that uniquely identifies that location in the page. Then to have a link jump directly to that anchor, use one of

• [[#name|link text]] within the same page, or
• [[PageName#name]] or [[PageName#name|link text]] for a location on another page
• The form [[PageName(#name)]] may be useful for hiding the anchor text in a link.

For example, here's a link to the Intermaps section, below.

Notes:

• the anchor itself must begin with a letter, not a number
• a link to an anchor must have the same capitalization as the anchor itself.
• Spaces are not allowed in an anchor: "[[#my anchor]]" won't work, "[[#myanchor]]" will.

Links outside the wiki

Links to external sites (URLs)

Links to external sites simply begin with a prefix such as 'http:', 'ftp:', etc. Thus http://google.com/ and [[http://google.com/]] both link to Google. As with the above, an author can specify the link text by using the vertical brace or arrow syntax, as in [[http://google.com/ | Google]] and [[Google -> http://google.com]].

If the external link includes (parentheses), escape these using %28 for "(" and %29 for ")" :

[[http://en.wikipedia.org/wiki/Wiki_%28disambiguation%29 | link to "Wiki
(disambiguation)" ]]

Links to intranet (local) files

You can link to a file system by including the prefix 'file:///' (for Internet Explorer at least). So file:///S:\ProjPlan.mpp and [[Shared S drive->file:///S:\]] are both valid links. On a Windows file system you may want to use network locations (eg \\server1\rootdirectory\subdirectory) rather than drive letters which may not be consistent across all users. Not all browsers will follow such links.

Link characteristics

Links as References

Links may also be specified as References, so the target appears as an anonymous numeric reference rather than a textual reference. The following markup is provided to produce sequential reference numbering within a PmWiki page:

Formatting the link as: [[http://google.com |#]] produces: [2] as the link.

Subsequent occurrence of the reference link format on the same page will be incremented automatically as per the following example: Entering [[http://pmwiki.com |#]] produces [3], [[#intermaps |#]] produces [4], and so on for further reference links.

Intermaps

Inter Map links are also supported (see Inter Map). In particular, the Path: InterMap entry can be used to create links using relative or absolute paths on the current site (e.g., Path:../../somedir/foo.html or Path:/dir/something.gif).

Links to pages in other wiki groups

See Wiki Group.

Links that open a new browser window

To have a link open in another window, use %newwin%:

• %newwin% http://pmichaud.com produces http://pmichaud.com
• %newwin% [[http://google.com/ | Google]] produces Google
• %newwin% Main.WikiSandbox produces Main.WikiSandbox

You can also specify that links should open in a new window via the target attribute:

%target=_blank% Any links on this line
like http://pmichaud.com 
will open in a new window.

Links that are not followed by robots

Prefix a link with %rel=nofollow% to advise robots and link checkers not to follow it.

Links and CSS Classes

PmWiki automatically gives classes to several types of links. Among other things, this enables you to format each type differently.

Note: This may be an incomplete list.

.selflink

A link to the current page. Useful in sidebars to show "you are here".

.wikilink

A link to another page within the wiki.

.urllink

A link to a page outside the wiki.

You can create a the class .anchor for anchor links
[[#target]], aka <A name='target'></A>
by putting the following in config.php :

 Markup('[[#','<[[','/(?>\\[\\[#([A-Za-z][-.:\\w]*))\\]\\]/e',
    "Keep(TrackAnchors('$1') ? '' : \"<a name='$1' id='$1' class='anchor'></a>\", 'L')");

Notes

Note: The default behavior of "+" above can be overridden to display the spaced title, rather than simply the title by adding the following to config.php:

## [[target |+]] title links
Markup('[[|+', '<[[|',
  "/(?>\\[\\[([^|\\]]+))\\|\\s*\\+\\s*]]/e",
  "Keep(MakeLink(\$pagename, PSS('$1'),
                 PageVar(MakePageName(\$pagename,PSS('$1')), '\$Titlespaced')
                ),'L')");

%newwin%http://example.com/

* mailto:myaddress@example.com
* [[mailto:myaddress@example.com]]
* [[mailto:myaddress@example.com | email
me]]
*
[[mailto:myaddress@example.com?subject=Some
subject&body=Body text | email me]]

[[http://example.com/ | WikiWord]]
[[WikiWord -> http://example.com/]]

(:pagelist link=SomePage list=all:)   -- show all links to SomePage
(:pagelist link={$FullName} list=all:)  -- show all links to the current page