Do not use Markdown/CommonMark for documentation. Use more expressive and configurable format like ASCIIDoc.
This is absolutely trend that I cannot understand. Markdown was designed for writing blogposts with almost not typesetting. Yet for some reason people thought that it will be a great format for documenting code, which need few more additional stuff, that was never a plan for MD (cross document references, math, graphs, tables, definition lists, etc.). Just stop and use ASCIIDoc for gods sake.