Managing links

tl;dr: Has anyone figured out a good way to single source links?

I use Hugo to manage a documentation site. My content is filled with links to other pages within the site. Many of these links are replicated across multiple pages. Fixing a broken or changed link can be tedious due to this duplication.

For example, many of my doc pages link to a Downloads page. I use the ref shortcode to link to the page: [Download]({{< ref "download.md" >}}). If I decided to change the file name, to downloads.md for example, I would need to update all of the links that point to it.

Instead of duplicating link definitions on each page that uses a link, is there a way to single source the link definitions? In other words, can I define my links a single time and reuse those links throughout the docs?

At one point I tried to solve this with the setup below, but it didn’t work.

  1. Created a single links.md page that defined my links using reference-style markdown links, like so: [Link-Download]: {{< ref "download.md" >}}.
  2. Used the readFile function to read the links.md content into the top of other .md content pages.
  3. Inserted links into the .md content pages like so: [Downloads][Link-Download]

I think the problem I ran into is the order in which markdown links are resolved; none of the links worked.

Has anyone figured out a good way to single source links?

I’m also having the same problem on a documentation site. Was wondering if Hugo offers some built-in way to manage these internal links, for example: can I link to a page using some kind of ID, maybe from the front matter, instead of the path?

The closest thing we have to a “link manager” is the menu system.

1 Like