Repository navigation
Make it explicit that the brackets around the version numbers are markdown links #621
Description
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.
Activity
fkuersch commentedon Jun 15, 2024
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.
CommonMark compliant renderers like mistletoe or marko render the example file above as follows:
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:
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 commentedon Aug 12, 2024
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)