Consider moving to CommonMark

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 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

The issue names RedCarpet and CommonMark but no files or tests; start by locating the current Markdown renderer and reviewing issue 281. Compare the existing rendering behavior with CommonMark, then define the compatibility, opt-in or SemVer requirements before implementation.