Links

How to create internal, external, and anchor links in Hugo Markdown — with relative paths, autolinks, and linking best practices.

Basic Links

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")

Link text · Link with title

Internal (Relative) Links

Always use relative paths for links within your site. This ensures links work in previews, forks, and across environments.

[About page](../about/)
[Blog post](../blog/my-post/)
[Section on this page](#section-heading)

Use relative links like [Link](../page) instead of absolute URLs like [Link](https://mysite.com/page). Relative links are portable and won't break when your domain changes.

Anchor Links

Link to any heading on the same page using its auto-generated ID:

[Jump to Best Practices](#best-practices)

Heading IDs are generated by lowercasing the heading text and replacing spaces with hyphens. For example:

Heading	Anchor
`## My Section`	`#my-section`
`## Code & Syntax`	`#code--syntax`
`### 3. Advanced`	`#3-advanced`

Autolinks

URLs and email addresses in angle brackets are automatically linked:

<https://example.com>
<[email protected]>

https://example.com

Reference-Style Links

For cleaner Markdown, define link targets at the bottom of your file:

Read the [installation guide][install] and [configuration docs][config].

[install]: /start/cli/
[config]: /guides/configuration/

External Link Behavior

External links open in the same tab by default. To open in a new tab, use HTML:

<a href="https://example.com" target="_blank" rel="noopener noreferrer">External Link</a>

Or use the button shortcode with new_tab="true" for styled external links.

Best Practices

Use relative links for internal pages — they survive domain changes and work in previews
Add descriptive link text — avoid "click here"; use meaningful descriptions like "see the configuration guide"
Link to headings with anchor links for long pages
Use Page Bundles so links to sibling content files just work: [Link](../sibling-page/)