Fix broken reference links in shortcodes

[travisbeckham]

There are still a few docs with broken reference links that were not fixed in PR #2068

The Problem

Reference links can not be shared between Markdown in a Hugo shortcode and Markdown in the main document. This is because the shortcode is rendered in a different context than the main document. For example, the reference link in the note shortcode will be rendered as plain text:

See: [reference link][1]
 
{{< note >}}

See: [reference link][1]

{{< /note >}}

[1]: https://example.com

Because Hugo renders the shortcode in a different context, the reference could technically be duplicated inside in the shortcode. For example:

See: [reference link][1]
 
{{< note >}}

See: [reference link][1]

[1]: https://example.com

{{< /note >}}

[1]: https://example.com

However, Markdownlint is not aware of Hugo's rendering context and will output the following linting error:

MD053/link-image-reference-definitions: Link and image reference definitions should be needed [Duplicate link or image reference definition: "1"]

The Solution

Unfortunately, Markdownlint will not be able to catch these broken reference links.

With this PR, all reference links inside a shortcode have been replaced with regular links, or with self-contained reference links that use names that are not used in the main document.

Testing

I searched for every note and warning shortcode and verified that the content did not share reference links with the main document.

I searched for "][" in the Hugo public directory, and none of the results were broken reference links.

[kflynn]

Ship it! Thanks for figuring this out. 🙂