Markdown: Link

Link#


Classic syntax#

To define a link, use the following syntax:

  • [Link_text](Link_URL)
MarkdownHTMLRendering
[I'm a relative link to another page (in the same folder) of the website](image/)
<a href="/markdown/image/">I'm a relative link to another page (in the same folder) of the website</a>
I’m a relative link to another page (in the same folder) of the website
[I'm a relative link to another page (parent page) of the website](./)
<a href="/markdown/">I'm a relative link to another page (parent page) of the website</a>
I’m a relative link to another page (parent page) of the website
[I'm an absolute link to another page of the website](/markdown/image/)
<a href="/markdown/image/">I'm an absolute link to another page of the website</a>
I’m an absolute link to another page of the website
[I'm an absolute link to a static resource of the website](/images/favicon.png)
<a href="/images/favicon.png">I'm an absolute link to a static resource of the website</a>
I’m an absolute link to a static resource of the website
[I'm a link to a title ID](#link)
<a href="#link">I'm a link to a title ID</a>
I’m a link to a title ID
[I'm a link to the homepage](/)
<a href="/">I'm a link to the homepage</a>
I’m a link to the homepage
[I'm a link to the homepage in another language](/fr/)
<a href="/fr/">I'm a link to the homepage in another language</a>
I’m a link to the homepage in another language
[I'm an external link](https://www.google.com)
<a href="https://www.google.com">I'm an external link</a>
I’m an external link

Links that does not contain a URL scheme are all prefixed depending on the baseURL configuration.
For example:

baseURLMarkdownRendering
/[](/markdown/link/)href="/markdown/link/"
http://myWebsite.com/subpath/[](/markdown/link/)href="/subpath/markdown/link/"
Links to the homepage using / is relative to the actual website lang.
Absolute links to resources using /<RESOURCE_PATH> is not relative to the actual website lang.

Classic syntax with title#

To define a link with a title, use the following syntax:

  • [Link_text](Link_URL "Link_title")
MarkdownHTMLRendering
[I'm a link](#classic-syntax-with-title "And I'm its title")
<a title="And I'm its title" href="#classic-syntax-with-title">I'm a link</a>
I’m a link

Alternative syntax#

To define an external link it is possible to use alternative syntaxes:

  • Write the link URL (rendering will be automatically made by the markdown converter).
  • Surround the link URL between the lower-than (<) and greater-than (>) characters.
MarkdownHTMLRendering
https://www.google.com
<a href="https://www.google.com">https://www.google.com</a>
https://www.google.com
<https://www.google.com>
<a href="https://www.google.com">https://www.google.com</a>
https://www.google.com
<foo@bar.com>
<a href="mailto:foo@bar.com">foo@bar.com</a>
foo@bar.com
Warning, for a user-friendly rendering (using Markdown Render Hooks ) it is recommended to use the classic syntax.

To escape a link (display a URL as a text) and avoid its automatic rendering by the markdown converter, it is possible to use alternative syntaxes:

  • Add a backtick (`) before and after the link URL (Define link as a code fragment).
  • Escape the first slash (/) of the link URL.
MarkdownHTMLRendering
`https://www.google.com`
<p>https://www.google.com</p>
https://www.google.com
https:\//www.google.com
<p>https://www.google.com</p>
https://www.google.com

To emphasize a link, surround the markdown code of the link with the chosen emphasis code. In case of a code fragment link, place backticks (`) inside the link text (between the brackets).

MarkdownHTMLRendering
*[I'm an italic link](/markdown/link/)*
<em><br><a href="/markdown/link/">I'm an italic link</a> </em>
I’m an italic link
**[I'm a bold link](/markdown/link/)**
<strong><br><a href="/markdown/link/">I'm a bold link</a> </strong>
I’m a bold link
***[I'm an italic and bold link](/markdown/link/)***
<em><strong><br><a href="/markdown/link/">I'm an italic and bold link</a> </strong></em>
I’m an italic and bold link
[`I'm a code fragment link`](/markdown/link/)
<a href="/markdown/link/"> <code>I'm a code fragment link</code> </a>
I'm a code fragment link

To define a link whose URL is referenced (therefore reusable), it must be formatted in 2 parts.

  • First part (link text)

    To define the first part of the link, which corresponds to the text that will be rendered and a reference to be defined in the second part, use the following syntax:

    • [Link_text][Link_URL_reference]
    The link URL reference is not case sensitive and may contain alphanumeric characters, spaces, and punctuation.
  • Second part (link reference)

    To define the second part of the link, which is the link between the link URL reference defined in the first part, and the value of the URL, use one of the following syntaxes:

    • [Link_URL_reference]: Link_URL
    • [Link_URL_reference]: Link_URL "Link_title"
    • [Link_URL_reference]: Link_URL 'Link_title'
    • [Link_URL_reference]: Link_URL (Link_title)
    • <[Link_URL_reference]>: Link_URL "Link_title"
    • <[Link_URL_reference]>: Link_URL 'Link_title'
    • <[Link_URL_reference]>: Link_URL (Link_title)
    The second part of the link can be placed anywhere in the document. For example all references of a document can be grouped together at the end of a document for readability and simplicity reasons.
MarkdownHTMLRendering
[I'm a link][Reference A]

[I'm a second link][Reference A]

I'm a lonely text

[Reference A]: #referenced-link
<a href="#referenced-link">I'm a link</a> <a href="#referenced-link">I'm a second link</a> <p>I'm a lonely text</p>

I’m a link

I’m a second link

I’m a lonely text

[I'm a link][Reference A]

[I'm a second link][Reference A]

I'm a lonely text

[Reference A]: #referenced-link "And I'm its title"
<a title="And I'm its title" href="#referenced-link">I'm a link</a> <a title="And I'm its title" href="#referenced-link">I'm a second link</a> <p>I'm a lonely text</p>

I’m a link

I’m a second link

I’m a lonely text

[I'm a link][Reference A]

[I'm a second link][Reference A]

I'm a lonely text

[Reference A]: #referenced-link 'And I\'m its title'
<a title="And I'm its title" href="#referenced-link">I'm a link</a> <a title="And I'm its title" href="#referenced-link">I'm a second link</a> <p>I'm a lonely text</p>

I’m a link

I’m a second link

I’m a lonely text

[I'm a link][Reference A]

[I'm a second link][Reference A]

I'm a lonely text

[Reference A]: #referenced-link (And I'm its title)
<a title="And I'm its title" href="#referenced-link">I'm a link</a> <a title="And I'm its title" href="#referenced-link">I'm a second link</a> <p>I'm a lonely text</p>

I’m a link

I’m a second link

I’m a lonely text

[I'm a link][Reference A]

[I'm a second link][Reference A]

I'm a lonely text

[Reference A]: <#referenced-link> "And I'm its title"
<a title="And I'm its title" href="#referenced-link">I'm a link</a> <a title="And I'm its title" href="#referenced-link">I'm a second link</a> <p>I'm a lonely text</p>

I’m a link

I’m a second link

I’m a lonely text

[I'm a link][Reference A]

[I'm a second link][Reference A]

I'm a lonely text

[Reference A]: <#referenced-link> 'And I\'m its title'
<a title="And I'm its title" href="#referenced-link">I'm a link</a> <a title="And I'm its title" href="#referenced-link">I'm a second link</a> <p>I'm a lonely text</p>

I’m a link

I’m a second link

I’m a lonely text

[I'm a link][Reference A]

[I'm a second link][Reference A]

I'm a lonely text

[Reference A]: <#referenced-link> (And I'm its title)
<a title="And I'm its title" href="#referenced-link">I'm a link</a> <a title="And I'm its title" href="#referenced-link">I'm a second link</a> <p>I'm a lonely text</p>

I’m a link

I’m a second link

I’m a lonely text

To define a link whose URL contains spaces, encode the URL with the associated percentage code of the space character (%20).

MarkdownHTMLRendering
[Hugo themes](https://www.google.com/?query=Hugo%20themes)
<a href="https://www.google.com/?query=Hugo%20themes">Hugo themes</a>
Hugo themes

To define a link ID, write a link following the classic syntax with title . The ID is automatically added to the link (using the theme) and its value is the output of Hugo’s anchorize function with the link title as input value:

  • [Link_text](Link_URL "Link_title")
MarkdownHTMLRendering
[I'm a link](#link-id-theme-specific "And I'm its title")
<a id="and-im-its-title" title="And I'm its title" href="#link-id-theme-specific">I'm a link</a>
I’m a link

Ref/Relref#

To define a link using the ref or relref, follow the associated default built-in Hugo shortcodes syntax .

MarkdownHTMLRendering
[I'm a ref link]({{%/* ref "image/" */%}})
<a href="<baseURL>/markdown/image/">I'm a ref link</a>
I’m a ref link
[I'm a ref link with named parameters]({{%/* ref path="image/" lang="fr" outputFormat="html" */%}})
<a href="<baseURL>/fr/markdown/image/">I'm a ref link with named parameters</a>
I’m a ref link with named parameters
[I'm a relref link]({{%/* relref "image/" */%}})
<a href="/markdown/image/">I'm a relref link</a>
I’m a relref link
[I'm a relref link with named parameters]({{%/* relref path="image/" lang="fr" outputFormat="html" */%}})
<a href="/fr/markdown/image/">I'm a relref link with named parameters</a>
I’m a relref link with named parameters