Links and cross-references

Share via

Generate internal links and external links using a combination of Markdown and Hugo shortcodes.

Hugo provides the shortcode ref to link to another page within the site. The shortcode returns an absolute path. You can provide the document path as input. If you omit the leading /, the page is first resolved relative to the current page, then to the remainder of the site. Review Hugo’s documentation  for more examples and advanced options.

[Tables]({{<ref "tables" >}})

[About]({{<ref "credits" >}})

Similar to the ref shortcode, Hugo provides the shortcode relref to return a path relative to the current page.

[Tables]({{<relref "tables" >}})

[About]({{<relref "credits" >}})


When using Markdown document types, Hugo generates element IDs for every heading on a page. Spaces are replaced with -. For example:

## An example reference

produces the following HTML:

<h2 id="an-example-reference">An example reference</h2>

You can add a cross-reference to the section heading by specifying the generated ID as input for the ref and relref shortcodes, preceded by a #.

[Reference]({{< ref "#reference" >}})

[Reference]({{< relref "#reference" >}})

Hugo supports basic Markdown to create links to external websites. The following sections explain the various options.

Hugo supports basic Markdown to create links to external websites. To create a link, enclose the link text in brackets (e.g., [Duck Duck Go]) and then follow it immediately with the URL in parentheses (e.g., (

My favorite search engine is Duck Duck Go.
My favorite search engine is [Duck Duck Go](

URLs and email addresses

To quickly turn a URL or email address into a link, enclose it in angle brackets.



Instead of using parentheses, you can use brackets to link to a predefined address. The following example uses a named reference to link to the website of Font Awesome.

[Font Awesome][fontawesome]


Hinode uses config/default/params.toml to manage links to external addresses in a single place. You can use the link shortcode generate a managed link. The following snippet of config/default/params.toml defines the link address for fontawesome:

    fontawesome = ""

You can then use the following statement to generate the link.

{{< link fontawesome />}}

You can configure the behavior of managed links in the /config/_default/params.toml file in the main.externalLinks section.

Last updated: August 23, 2023 • Fix linting errors (786a957)