lexmag / elixir-style-guide

An opinionated Elixir style guide

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Use markdown headers instead of explicit link

esambo opened this issue · comments

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.

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! 💟