TLDR: Don’t use shortcut references for Markdown link and image destinations. Use collapsed references instead.
When adding links and images to your Markdown documents, you can choose from four different formats. Each has its own benefits, but some are better than others, especially for long-term use.
Here’s a quick look at the four ways to format links and images, along with their syntax:
-
Inline – This is the most common format. It places the link’s text and URL right next to each other within the paragraph. This is great for quick, one-off links.
[link](https://example.com)  -
Reference – This format separates the link text from the URL, which is defined at the bottom[1] of the document. This is useful for keeping your prose clean and organized, especially if you’re linking to the same URL multiple times. There are a few types of reference links:
-
Full reference – Uses a unique label to connect the link text to the URL.
[link text][label] [label]: https://example.com -
Collapsed reference – Uses the link text itself as the label, followed by empty brackets (
[]). This is a great balance between clean prose and clear syntax.[link text][] [link text]: https://example.com -
Shortcut reference – A simplified version that uses the link text as the label, but omits the empty brackets (
[]). While it looks clean, it can cause problems, which we’ll discuss below.[link text] [link text]: https://example.com
-
The problem with shortcut references
Many writers, including myself, have favored shortcut references because they make the text easy to read and edit. For example:
Accustomed to reach whatever place I started for, I was
going up [the mountain] alone to camp, and wait the
coming of the party next day.
[the mountain]: https://example.com
The issue arises when the reference link at the bottom of the document is accidentally deleted. The text [the mountain] remains in the paragraph, but it’s no longer a working link. Instead, it’s just text surrounded by brackets. This can be a headache, as it’s not always obvious that a link is broken. A link checker or Markdown linter won’t catch this.
Use collapsed references instead
A much better approach is to use collapsed references. They provide the same benefit of keeping your prose clean but also add a crucial safety net.
Accustomed to reach whatever place I started for, I was
going up [the mountain][] alone to camp, and wait the
coming of the party next day.
[the mountain]: https://example.com
Notice the key difference: the empty brackets [] after the link text. This small addition tells any Markdown linter that the text is supposed to be a link. If the corresponding URL definition is missing or deleted, the linter will immediately flag it as an error, saving you from broken links.
Popular Markdown linters, such as markdownlint, have specific rules to detect these kinds of issues. For example, rules MD052 (Reference links and images should use a label that is defined) and MD053 (Link and image reference definitions should be needed) are designed to prevent this exact problem.
Markdown linting
The Hugo documentation site uses a GitHub Action to perform Markdown linting:
https://github.com/gohugoio/hugoDocs/blob/master/.github/workflows/markdownlint.yml
This is the configuration file:
https://github.com/gohugoio/hugoDocs/blob/master/.markdownlint-cli2.yaml
The configuration file also works with this VS Code extension:
https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
Replacing shortcut references using VS Code
This regular expression is a good starting point for replacing shortcut references with collapsed references in your VS Code project, but it requires careful, manual inspection of each match.
- Find:
(?<![\[\]^]|:\s)\[([^\[\]!][^\[\]]+)\](?!\s*\[|\s*\(|\s*:) - Replace:
[$1][]
Although it is common to place link references at the bottom of the document, you can actually place them anywhere. For long documents, it’s often more practical to put them just before the next heading or immediately after the paragraph where they are used. ↩︎