3.4. File syntax 3.4.6. Links: 3.4.5. Headers
« Previous; 3.4.7. Images
Next »

3.4.6. Links

Markdown allows to insert links to other sites in three ways: directly in the text (linear), by a reference and automatically. The first and the second one use the square brackets [ ] to surround the text that will be changed into the link.

Directly in the text

Here, we insert normal brackets right after the square ones where we write an URL. Markdown allows to specify the link title (to the title attribute in HTML). We specify it after the address and inside double quotes:

TypeFriendly was written by [Invenzzia](http://www.invenzzia.org)

TypeFriendly was written by [Invenzzia](http://www.invenzzia.org "Invenzzia")

TypeFriendly was written by Invenzzia

TypeFriendly was written by Invenzzia

By reference

The reference uses another square brackets written after the first ones. It is used to specify the link label. Optionally, the square brackets can be separated with one space:

This is an [example][id] of reference links.

This is an [example] [id] of reference links.

The reference definition looks like this:

[id]: http://www.example.org/ "Optional title"

The reference elements are:

Square brackets with the label
Colon
At least one space or tabulation
URL that the reference points to
Optional link title written in double quotes, single quotes or brackets. It can be placed in the same line or in the new one, justified with spaces or tabulations.

The following lines give exactly the same result:

[id]: http://www.example.org/ 'Optional title'
[id]: http://www.example.org/ (Optional title)
[id]: http://www.example.org/ 
      "Optional title"

Markdown allows to surround the link with angle brackets (< >):

[id]: <http://www.example.org/>

The reference definitions are for Markdown internal use only. They are removed from the output document.

The reference labels can use letters, numbers, spaces, punctuation marks, however they are case-insensitive.

Those two lines refer to the same label:

[some text][a]
[some text][A]

You can also ignore the label by writing empty square brackets []. Markdown will use the link name as a label then.

Example:

[Invenzzia][]

And the definition:

[Invenzzia]: http://www.invenzzia.org

This allows to produce longer labels with whole sentences, too!

[Invenzzia group][]

[Invenzzia group]: http://www.invenzzia.org

The reference definitions can be placed anywhere in the document, but they must be separated from the block elements (paragraphs, lists, etc.) with empty lines. You can write them after the paragraph where they have been used or at the end of the document.

Sample reference use:

We have 10 times more net traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

In fact, [Google][1] is the most popular search engine.

 [1]: http://www.google.com
 [2]: http://www.yahoo.com
 [3]: http://search.msn.com

With auto-labels:

We have 10 times more net traffic from [Google][] than from [Yahoo][] or [MSN][].

 [google]: http://www.google.com
 [yahoo]:  http://www.yahoo.com
 [msn]:    http://search.msn.com

Why should we use references?

References make the source text easier to read and manage. Especially, very long URLs can be quite annoying when they are mixed with the content. References allow to throw them somewhere else.

Automatic links

Sometimes we want to display an exact URL in the text. Markdown offers a simple solution. We write the URL in the angle brackets and that's it:

Visit our website: <http://www.invenzzia.org/>

Visit our website: http://www.invenzzia.org/

This works also for e-mails. However, in this case Markdown will try to obfuscate the output HTML with entities.

Contact address: <company@example.org>

Contact address: company@example.org

Links to the other chapters

TypeFriendly registers in Markdown default references that point to all the chapters of your manual with their identifiers as labels. For example, to refer to the someClass description in api.classes.some-class, we write:

See also [this chapter][api.classes.some-class]

Links to anchors

Since TypeFriendly 0.1.3 it is allowed to make a link to anchors in the other chapters.

The syntax is the same as to a chaper and an anchor #anchor is located after the chapter id.

Check [this part of a chapter][api.classes.some-class#anchor]

To make a link to an anchor in the same chapter it is still required to use the above syntax and not to use [link](#anchor). It is because TypeFriendly adds a prefix: h:chapter_id: to each header anchor to make them unique in the whole documentation.

3.4.6. Links 3.4. File syntax: « Previous
3.4.5. Headers; Next »
3.4.7. Images