Consider moving to CommonMark

[jamietanna]

Sounds like a plan re using our version :+1:

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 https://github.com/alphagov/tech-docs-gem/issues/281#issuecomment-966234478

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:

https://github.com/alphagov/learn-to-code/issues/56