Make it explicit that the brackets around the version numbers are markdown links

[runevision]

I see a lot of changelogs following keep-a-changelog which puts each version in brackets but don't specify the sources at the bottom of the documents. So instead of the versions appearing as links in the rendered markdown output, they just appear as version numbers in brackets.

This was the case for all the official Unity packages I spot-checked, for example:
https://github.com/Unity-Technologies/InputSystem/blob/develop/Packages/com.unity.inputsystem/CHANGELOG.md

It seems that many people just assume it's part of the standard that the version numbers should be written in brackets, without looking into why. It would be good if the keep-a-changelog project would make it explicit somewhere that it's because it's links, and (I assume) that there is no reason to put the version numbers in brackets if they are not used as links. After all, version numbers don't appear in brackets in the rendered output in the correctly formatted changelogs.

Now, markdown links where the source is specified separate from the link is a standard part of the markdown format, and you could argue people should know that and not have to be told. But it doesn't appear to work that way in practice, so a mroe explicit note about it might help more changelogs out there be formatted better.

If there already is a note about it, I missed it despite deliberately looking for it (and clearly others have missed it too), so if so, it's arguably not visible enough.

I don't know where the note should be displayed exactly. I couldn't find any actual documentation of the format. But I'm sure there's a fitting place to put it.

[fkuersch]

tl;dr: I support your suggestion and I'd like to add a note that keep-a-changelog is CommonMark based (since the reference-style version links in a keep-a-changelog document are not Markdown 1.0.1 compliant).

Interesting. Despite working with markdown almost daily, I didn't know either that reference-style markdown links even exist.

So I rendered the following 3 different reference-style links in several markdown renderers with varying results.

- [link 1][1]
- [link 2][]
- [link 3]

[1]: https://example.org
[link 2]: https://example.org
[link 3]: https://example.org

CommonMark compliant renderers like mistletoe or marko render the example file above as follows:

<ul>
<li><a href="https://example.org">link 1</a></li>
<li><a href="https://example.org">link 2</a></li>
<li><a href="https://example.org">link 3</a></li>
</ul>

I tired GitHub, JetBrains (IntelliJ, PyCharm, ...) and several online markdown editors. They all look something like this:

Renderers that follow the original 2004 markdown syntax don't support the third link in the list. According to the original markdown specs, a reference-style link requires two pairs of square brackets. A single pair of square brackets is not sufficient:

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:
This is [an example][id] reference-style link.
(...)
The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets — e.g., to link the word “Google” to the google.com web site, you could simply write:
[Google][]
And then define the link:
[Google]: http://google.com/

So, the reference-style version links in a keep-a-changelog document are not Markdown 1.0.1 compliant.

As a side note, my favorite markdown editor Typora doesn't support the single-bracket reference link and additionally renders the footnotes/references:

[UnicodeTreason]

Thanks for the info fkuersch, you explained my small mystery of "Why doesn't this work in Gitlab"

Keen to hear other perspectives on this.
We've just gone to inline links internally as our resolution.

## [Unreleased](https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...HEAD)