Doc consistency

[Gadgetoid]

❗ This changeset depends upon merging #174. The diff will be very big and noisy until #174 is merged.

This PR, #174 and others to follow aim to replace the mess in #170 with a series of documented commits that correct linebreaks, markdown consistency, spelling and - finally - rephrasing, in turn.

This changeset enforces some style rules in the name of consistency:

• All pages have a title
• Bulleted lists use -, numbered use N.
• Bulleted lists of links separated by linebreaks
• One line-break before and after titles, lists and tables
• All titles use markdown title syntax
• Titles start with level 2, website uses h1 in header
• Lists of links are always bulleted
• Lead-in to lists ends with semi-colon

These "rules" are somewhat arbitrary, but informed by the HTML rendered to the website and for ease of reading/editing.

There are no typo fixes or re-wording in this PR- I will do a pass on typos once this and #174 are merged.

Titles

Pages without a lead-in title look weird, examples - https://tech.microbit.org/latest-revision/announcement/ and https://tech.microbit.org/bluetooth/apps-and-examples/ - since the top-margin is not equal to the left/right margins.

Since the page template steals the H1 tag, titles should ideally start at ## Title which is H2. That said- the semantic meaning of H tags has been somewhat lost in the noise of the web. Pages seemed to start with/use one or the other, so I've erred on the side of technically correct and used H2+.

I have replaced some **strong** titles with #### H4 titles without knowing if the site will correctly generate this markup. However I have confirmed that <h4> does have appropriate CSS to be used in these cases- fingers crossed!

Lists of links

Lists of links that are not bulleted tend to parse as sentences/paragraphs rather than individual, unrelated units. Adding bullets makes them clearly, intentional lists. Contrast the following:

To before:

Additionally, lists of links have been moved up the heading (and TOC-tree) heirachy to H2 and titled "Further information" (though this could be "More information" or otherwise) to clarify in the TOC exactly what type of links they are.

[Gadgetoid]

Rebased! I don't know what happened there, but it should be good to go now.

I've made some educated assumptions about how my changes will affect the actual website- is there any way I can build the website locally to check I haven't broken anything?

[microbit-mark]

Thanks @Gadgetoid . I've given this a cursory review and looks good. I've also built it locally and can't see anything broken. let's merge and build to see if there are any issues in CI. I'll post a preview here when done.

The developer site is closed source at present, so their isn't a way to build locally outside The Foundation

[microbit-mark]

Should eventually build at doc-consistency.review.tech.microbit.org.s3-website-eu-west-1.amazonaws.com

Looks good to me as far as the content goes @Gadgetoid. What do you think?

[Gadgetoid]

I haven't spotted any eggegious errors or breakage.

I'm already seeing things I want to fix 😆

Chiefly:

1. Overview appearing in TOC tree
2. Some longer pages without a TOC
3. No title/padding above images on hardware pages
4. The template on /software/other-languages/ probably needs put in backticks- if we can backtick backticks... or linked out somewhere. This page is a bit confusing!