markdownlint
markdownlint copied to clipboard
DavidAnson
MD051: Add an option to ignore case for automatically-generated heading identifiers
The example from the documentation reports MD051/link-fragments: Link fragments should be valid [Expected #heading-name; Actual: #Heading-Name]
# Heading Name
[Link](#Heading-Name)
I expect the behavior as described in the example. The actual logic appears to have a bug.
The documentation you link explains why the example you show is reported as a violation:
Link fragments may be handled case-sensitively, so this rule requires fragments to exactly match the GitHub heading algorithm.
Why is this example wrong? It exactly matches the case, so when the link anchor is treated case-sensitive than an exactly matching case should be valid and no violation! Is there a way to change the behaviour of this rule to ignore case or match case exactly??
As noted above, this rule matches the GitHub algorithm and that algorithm converts heading text to lower case. Work could be done here to allow mIxEd CaSe, but that would permit inconsistency without adding any functionality.
I understood that it implements the GitHub algorithm but the wording in the documentation that Link fragments may be handled case-sensitively is misleading. For me this reads like this because link fragments can be handled either case sensitive or case insensitive we implemented the GitHub algorithm which handles everyting case sensitive
I will add some background why we stumbled upon this:
We write documentation in markdown and then we use mark to upload the documentation to Atlassian Confluence. Because Confluence is handling anchor links case sensitive this is a bit of a problem because we can't meet both requirements. I already added an issue to mark maybe they can transform the links on generation
The parsers we use are also case-sensitive, so that enhancement would help. But they also handle whitespace differently, so maybe not sufficiently...
However I had indeed read this documentation wrong, I read it as different markdown implementations handle case sensitivity differently, so we support both, this was reinforced by may of the other examples being correct markdown and this one being incorrect. Maybe some ✅ and ❌ in the docs could help accentuate when something is valid/invalid?