Internal and External Links with Hugo

The Markdown syntax for creating a link is straightforward, but you likely need to make sure that you are not creating any dead links at least internally to your site. You might also want to customize how different links behave. For instance, you may want the external links to open in a new tab, so that you site visitor stays at your site.

Internal Links

Referencing pages of the same site is done with two shortcodes, ref and relref. A shortcode is a variable that is mapped to a template, but is meant to be used within a Markdown file. You can refer to the full path of a page (that is, relative to your domain) like this:

{{< ref "/PATH/TO/PAGE" >}}

Do not use a trailing slash, it will result in an error.

The relref, by contrast, uses the path relative to the current page. Place the shortcode into your Markdown where you would put the URL, and you are done. If the path is invalid, Hugo server will display an error, no matter which page you are at.

Links to the same content in a different language are covered here

Read the official documentation for more details.

Customizing Link Behavior

The Markdown syntax for creating a link is this:

[Link text](URL "Link title")

… which translates into this HTML:

<a href="URL" title="Link title">Link text</a>

You might need more than that. For instance, as mentioned above, you might want to add a target="_blank" attribute to external links, so that it opens in a new tab or window, and your users won’t leave your site. The internal links, on the other hand, should probably open in the same window.

Hugo allows you to create markup hooks to your links, images, and headings. A markup hook is a Hugo template that sits under layouts/_markup subdirectory either in your project tree or under a theme tree. This template receives the entire page context as {{.Page}} variable (not {{.}}, as in normal templates), and a number of other variables, referring to Markup parameters. To implement the desired behavior, create a themes/<NAME>/layouts/_default/_markup/render-link.html file with the following content:

<a href="{{ .Destination }}" {{ with .Title }} title="{{ . }}"{{ end }} {{ if strings.HasPrefix .Destination "http" }} target="_blank"{{ end }}>{{ .Text }}</a>

The gory details are officially documented here , but they do not lie exactly on the surface.