Consider moving to CommonMark

[jamietanna]

Sounds like a plan re using our version 👍

That's fair - I think if it were me, I'd potentially be using this OpenAPI description with different tools (i.e. it may go onto the API Catalogue or other internal/external tooling, such as rendering inside tools like JIRA, or an IDE) and I'd be expecting a consistent formatting across all of those.

It's unlikely that many users will be affected, but the reason CommonMark became a thing is because so many Markdown flavours are inconsistent, so it's possible that people will be affected by quirks that RedCarpet has.

I agree that it'd be odd to write a doc page that doesn't render the same as the API docs, and to that I wonder if maybe we should look at using CommonMark everywhere?

Originally posted by @jamietanna in #281 (comment)

Notes:

• GitHub previews won't necessarily match the site's view of content, so may make it less easy for folks just reviewing through GitHub
• Would require a SemVer major bump, as it would introduce chance of breakage, unless made opt-in

[lfdebrux]

This would be useful for the Learn to Code repo, which has an issue because Redacarpet doesn't support Markdown in HTML in the same way CommonMark does:

alphagov/learn-to-code#56