[BUG] Address the markdown lint errors in markdown files

[alanhargreaves]

Describe the Bug

Markdown lint is not happy with a lot of our *.md files. This bug is to do a general tidy up and make it a little happier.

---

73!