Including reference links in markdown as bullet point list on GitHub

Question

Currently I'm using this markdown text inside the README.md file of a project on GitHub:

See the docs of [testthat][3] on how to write unit tests.

Links
-----

- http://www.rstudio.com/products/rpackages/devtools/
- https://github.com/hadley/testthat
- http://r-pkgs.had.co.nz/tests.html

---

[1]: http://www.rstudio.com/products/rpackages/devtools/
[2]: https://github.com/hadley/testthat
[3]: http://r-pkgs.had.co.nz/tests.html

I don't like this duplication, but I don't see what choice I have. If I remove the explicit bullet point lists, then GitHub won't display the reference links. If I remove the reference links, then GitHub shows the bullet point list (of course), but the embedded links like "testthat" above don't work.

Is there a better way than duplicating? What am I missing?

Answer 1

Inspired by @mb21, I suppose this would be the right way to do it:

See the docs of [testthat][2] on how to write unit tests.

Links
-----

- [RStudio Devtools][1]
- [testthat][2]
- [More unit test examples][3]

[1]: https://stackoverflow.com/users/214446/mb21
[2]: https://github.com/hadley/testthat
[3]: http://r-pkgs.had.co.nz/tests.html

That is, it's not a good practice to include links verbatim and without a meaningful title. I should keep the link URLs only in the reference links section at the bottom, and in the bullet point list use meaningful titles.

When you view this on GitHub, the URLs shouldn't really matter, and if you really want to know you can move the mouse over. When you view this in plain text, now the links have meaningful titles, which is useful additional information about the URLs.