Use markdown headers instead of explicit link
esambo opened this issue · comments
E. Sambo commented
Nice guide, but is there a reason to add all the links at the end of the bullet points?
GitHub markdown automatically creates deep links for headers if you change the format a bit from:
## Linting
* <a name="pipeline-operator"></a>
Favor the pipeline operator `|>` to chain function calls together.
<sup>[[link](#pipeline-operator)]</sup>
to:
## Linting
### Pipeline Operator
Favor the pipeline operator `|>` to chain function calls together.
Andrea Leopardi commented
That would look differently when the Markdown is rendered and the current way ensures that:
- we can have the nice
[link]
as a supertext. - we can decouple the name of the section with the text of the section, which is useful when you want to change the text of a section but keep the link for existing links referencing it. Your way would mean that changing the title of a section would mean changing the anchor to it.
- we don't have to give each section a title :)
Thanks for the proposal though! 💟