Update link syntax throughout lesson

[emcaulay]

As mentioned by @tobyhodges in the review of PR #106, there is a standard practice for linking and providing references at the end of each Markdown file. Adopting this across this lesson would improve its usability and clarity.

[emcaulay]

Here was the detail from @tobyhodges (many thanks, Toby, for the guidance!)

For the sake of completeness, and because you may very well see both forms used elsewhere in Carpentries lessons (sometimes together in the same page/lesson), the

[GitHub's instructions for keeping your email address private][git-privacy] syntax is also valid, if you include a link reference later in the file, e.g.

[GitHub's instructions for keeping your email address private][git-privacy]

[git-privacy]: https://help.github.com/articles/keeping-your-email-address-private/ It is standard practice to include all such link references at the very bottom of the Markdown file. These "reference-style" links in Markdown are particularly useful for URLs that are linked to in multiple locations throughout the document: that way, if the address of the target page changes, you only need to modify the URL in a single location to update all the relevant links.

To be clear, I am not suggesting that you need to take this approach here, but adding the information because it may be helpful when reading/contributing to other repositories.

[doingarchives]

@emcaulay Left a similar comment in PR#106 (more on Slack). Markdown reference?

[doingarchives]

@tobyhodges Like the comment above - but not finding a Git / GitHub reference to this statement 'It is standard practice ...' < https://bit.ly/3xFVKJH >. Do you have an authority or citation for the standard?

[tobyhodges]

I call it standard practice because I have observed it being done in many places, but "good practice" would have been more accurate*. See, for example, this style guide for Markdown in another open source project, this set of tips for writing Markdown, and the section on links in the CommonMark tutorial (you will need to click on the little red + button next to the link reference/definition in the example on that page).

In The Carpentries, we often take this one step further with the {% include links.md %} added at the end of each episode in many of our lessons. When the HTML page is being built from the source Markdown, this first inserts all the link references - stored in the _includes/links.md file - at the end of the page, allowing us to reuse a single set of link references throughout the whole lesson. This is my preferred method when working with the lesson template but, while it makes the lesson more maintainable, it can be argued that the added complexity/abstraction makes it less easy for newcomers to contribute to. This is a call for the lesson Maintainers to make, in this issue thread or if/when the PR is submitted.

* Your question made me go looking and, interestingly, the original author of Markdown states that they tend to put the link references at the end of each paragraph. So clearly there is some variation in how this is being done and I will be more careful about what I call "standard practice" in future!