For best results, be sure to test your links before posting them. Use Preview for links in nodes or /msg yourself for links to be posted in the Chatterbox.

Specifying Link Des‎crip‎tion

To specify the text shown for your link, enter the text (actually HTML)
after a | (pipe) character in your []'s. For example,
[http://perlmonks.org/|The <em>Perl</em> Monastery] is displayed as
The Perl Monastery.

If you do not specify a des‎crip‎tion, your link's criteria is used.
For example, [perldoc://perlfaq] is rendered as
perlfaq and [http://www.perl.com/] as
www.perl.com. Some link types (http://, https://, ftp://, and
isbn://) include the link type in the default des‎crip‎tion. Exceptions
include:

The [id://] tag display the node's title if you do not
provide a des‎crip‎tion. For example, [id://42269] is
displayed as 42269.

The [pad://] tag constructs a des‎crip‎tion if you do not
provide one. For example: [pad://vroom] returns vroom.

Footnotes:

1 - While you can use <a href=...> tags to link to pages within the Monastery, it's best to use different approaches for internal links. If you must use an <a href=...> tag, then be sure to use relative URL's (e.g. do not include the "http://www.permonks.(org|com)/index.pl". Otherwise, your link may appear to log people out. Instead start the URL simply with a question mark: <a href="?node_id=...">.

2 - You can locate the ID of many nodes by opening them from Search results, Super Search results, Newest Nodes, or even the author's User Search results. Check the node's URL. If you see a node_id parameter, that's the value you need. If you don't see that parameter, search for the node and then open it. (It may help to include a nonsense word in your search, e.g. "plugh")

3 - This is the same as entering your search terms into the Search box at the top of most nodes.

4 - You can also use [kobe://XML::Parser] (no "s"). This was the original method and there are no plans to stop supporting it.

5 - For best results, verify the ISBN number using FatBrain's search facility, as ISBN number change in new editions. And, yes, the Monastery receives a small kickback if the book is purchased from the link. (If you like, you can provide kickbacks to the Monastery for books ordered from your own web pages).

Advanced options

These link shortcuts come in two forms: [TITLE|DESC] and
[WORD://DATA;PARAMS|DESC]. Some special rules and processing
apply to each part of a shortcut.

You can not have a literal [ nor ] in any of the parts.

|DESC and ;PARAMS are optional.

TITLE is interpretted as text except it cannot contain
[, ], nor | and must not match m[^\w+://]. To link
to a node that contains [, ], or | in the title, use
[title://...] or [id://...].

DESC is interpretted as HTML except that &lsb; and
&rsb; become [ and ] (respectively).

WORD must be one of the supported link types or else the
entire [WORD://...] construct is simply displayed as a
literal string. Upper- vs. lower-case is ignored in WORD.

DATA is a string that is processed to produce a URL based on
WORD. There are several character sequences that you can
use in DATA to represent metacharacters (see below).

PARAMS adds characters on the end of the URL generated from
WORD://DATA.

[pm://...] is unusual in that it takes no DATA so
you can do [pm://images/usermonkpics/ovidmonk.gif] or
[pm://?op=message;...].

In DATA;PARAMS, the following special sequences are processed:

String

Result

;

In DATA, it ends DATA and starts PARAMS. In PARAMS, separates parameters.

&amp;m[&amp\b;?]i

In DATA, it ends DATA and starts PARAMS. In PARAMS, separates parameters.

?

In DATA, it ends DATA and starts PARAMS (and is changed to ; if needed).
In PARAMS, adds "?" to the string.

/

In DATA, it ends DATA and starts PARAMS. In PARAMS, adds "/" to the string.

#

Indicates that an anchor name is next which tells where in the
linked-to page to jump to.

|

Ends DATA and PARAMS, starts DESC.

=

In DATA, adds "=" to DATA (same as \= would). In PARAM, separates param
name from value.

%XXm[%([\da-f]{2})]i

Adds pack("C",hex($1)) to the string.

\\ \; \& \? \/ \# \| \= \%

Adds the second (escaped) character to the string.

\*m[\\(\W)]

Adds "\\$1" to the string.

\Am[\\(\w)]

Adds $1 to the string.

%

Is treated like \% if it isn't follow by two valid hex characters
(it adds a "%" to the string).

&lt;m[&lt\b;?]i

Adds '<' to the string.

&gt;m[&gt\b;?]i

Adds '>' to the string.

&quot;m[&quot\b;?]i

Adds '"' to the string.

&lsb;m[&lsb\b;?]i

Adds '[' to the string.

&rsb;m[&rsb\b;?]i

Adds ']' to the string.

&#91;m[&#(\d+);?]

Adds pack("C",$1) to the string.

&

Is treated like &amp; if it doesn't start one of the
above HTML escapes (ends DATA or separates parameters).

Examples

Here are some examples showing how the above (rather complex) rules are
designed to be do-what-I-mean when constructing links:

[user://turnstep#Cplusplus|Chatterbox FAQ++] becomes
Chatterbox FAQ++. Note how it jump down
to the <a name="Cplusplus">Chatterbox FAQ++</a> point
of turnstep's home node.

Note that [turnstep#Cplusplus] doesn't start with WORD://
and so # is not recognized as being special and so this tries to search
for nodes having "turnstep#Cplusplus" in their title and so probably
finds nothing: turnstep#Cplusplus.

[title://turnstep#Cplusplus] (probably) also works since we
don't (shouldn't) have any nodes titled "turnstep" except for the user:
turnstep#Cplusplus.

If you want to find a node with # in the title, you can use
[Using # inside qw()] (Using # inside of qw()) or
[title://Using \# inside qw()] (Using \# inside qw()).
Note how the # has to be escaped as \# when using WORD:// links.

This is useful if you want to specify extra options in the link. For
example [title://Using \# inside qw();displaytype=xml]
(Using \# inside qw();displaytype=xml) will give you the XML
version of that node.

Even better would be to not rely on the title of the node never changing
and link to it via the node ID instead:
[id://94698;displaytype=xml] (94698;displaytype=xml).

Similarly, you can't use [P(erl|ython)] to link to
the node with that titles since it becomes ython) and there
is no way to escape | if you aren't using the WORD:// type of link.

To link to that node use [title://P(erl\|ython)]
(P(erl\|ython)), [title://P(erl\|ython)|cool obfu]
(cool obfu), or [id://31015]
(31015), etc.