Links

A link element rendered using standard markdown link syntax and alternative shortcode {{< link >}}.

Features#

• Supports standard Markdown link syntax [text](url) and alternative shortcode {{< link >}}.
• Automatically detects external links (absolute URLs) and opens them in a new tab with rel="external" and target="_blank".
• Adds a visual external-link indicator icon next to external URLs.
• Supports tooltip text via the optional title attribute.
• Allows adding custom CSS classes via the class attribute (shortcode only).

Syntax#

[link text](url "optional tooltip title")

{{< link
        url="url"
        text="link text"
        title="optional tooltip title"
        class="custom-class"
>}}

Parameters#

Link Text / text

(required) The visible, clickable text of the link.

URL / url

(required) The destination URL. Can be one of:

• Internal path: a relative or root-relative path within the site (e.g., /guide/markdown-syntax/)
• External URL: an absolute http:// or https:// URL (e.g., https://gohugo.io) — automatically opens in a new tab
• Page anchor: a fragment pointing to a heading on the same page (e.g., #features)

Title / title

(optional) Tooltip text displayed on hover.

class (shortcode only)

(optional) One or more CSS classes to apply to the <a> element (default: fr-link).

Note: The class attribute is not available in markdown syntax due to a goldmark limitation — inline elements do not support attribute blocks {...}. use shortcode if you need custom classes.

Theming#

The link component uses the CSS custom property,

• --color-link for its normal color,
• --color-accent for on hover and active states.

{
  :root {
    // ...
    --color-link: #0000ee;
    --color-accent: #01827c;
    
    // ...
  }

  @media (prefers-color-scheme: dark) {
    :root {
      // ...
      --color-link: #66aaff;
      --color-accent: #00fff2;
      // ...
    }
  }
}

Refer to the Theme Customization guide, for guidance on how to customize these properties for your site.

Examples#

Example 1: Basic Internal Link#

[Theme Customization](/guide/theme-customization/)

{{< link url="/guide/theme-customization/" text="Theme Customization" >}}

Theme Customization

Example 2: External Link#

External links are detected automatically when the URL is an absolute http(s):// address. They open in a new tab and display a small external-link icon.

[Hugo Documentation](https://gohugo.io/documentation/)

{{< link url="https://gohugo.io/documentation/" text="Hugo Documentation" >}}

Hugo Documentation

Example 3: Link with Tooltip Title#

Pass an optional title to show a tooltip on hover.

[Hugo Documentation](https://gohugo.io/documentation/ "Official Hugo Docs")

{{< link url="https://gohugo.io/documentation/" text="Hugo Documentation" title="Official Hugo Docs" >}}

Hugo Documentation

Example 4: Page Anchor Link#

Link to a specific heading on the same page using a #fragment.

[Back to Features](#features)

{{< link url="#features" text="Back to Features" >}}

Back to Features

Example 5: Link with Custom Class (shortcode only)#

Use the class parameter to apply custom CSS classes. This is only possible via the shortcode — markdown inline links do not support attribute blocks.

{{< link url="https://gohugo.io/documentation/" text="Hugo Documentation" class="my-custom-link" >}}