Correct anchors in README.md #21166
Merged
Correct anchors in README.md #21166
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 2 commits
March 26, 2017 10:09
Alternative approach to make GitHub correctly render the `README.md` headlines by simply moving the manual anchors to below the headlines. Since current manual anchors are uppercase, this keeps external links valid.
The `README.md` is currently rendered incorrectly on GitHub since it includes manual HTML anchors for headlines. However, since several years, GitHub automatically includes these anchors. Considering the anchors in the README.md have been added some six years ago, the GitHub feature is probably younger. This removes all the manual anchors, for which all match the exact headline pattern anyway, except the following which differ slightly: - `<a name="Editor-Terminal-Setup"/>` - `<a name="Platform-Specific-Notes"/>` - `<a name="Required-Build-Tools-External-Libraries"/>` If referenced from somewher externally, these would need to be updated. Links within this README to anchors are also corrected. The automatically generated anchors on GitHub follow the pattern of replacing all spaces with `-` and everything being lowercase, e.g. `## This is a Title` automatically gets the anchor equivalent to `<a name="this-is-a-title"/>` to be referenced in markdown with `[Link to a title](#this-is-a-title)`.
StefanKarpinski
approved these changes
Mar 26, 2017
Member
StefanKarpinski
left a comment
StefanKarpinski
left a comment
There was a problem hiding this comment.
Thanks for doing this!
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The README.md is currently not rendered correctly on GitHub due to the manual HTML anchors preceding the headlines. This effectively prevents the rendering engine from recognising the headlines. Since those anchors have been added some six years ago, and before GitHub introduced the feature of automatically creating anchors, they are now somewhat redundant.
This pull request contains two commits: 1) The first corrects the rendering by moving the manual anchors to below the headlines but keeps them for external sites; 2) the second commit completely removes these anchors and corrects links inside the README.md.
Main reason for the two commits is that the GitHub automatic anchors use lowercase only, the manually added however are mixed case. I'm unsure if and how generation of docs is affected and which external sites might require these anchors.