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.
- Created a single
links.md
page that defined my links using reference-style markdown links, like so:[Link-Download]: {{< ref "download.md" >}}
. - Used the
readFile
function to read thelinks.md
content into the top of other .md content pages. - 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?