Section 36.2 CommonMark, Tables, Mathematics, Renderers

Markdown began as a loose collection of conventions, and renderers came to disagree about the fine points. CommonMark is the careful specification that resolved this, and it is the contract this conversion honors: the output is valid CommonMark, and an escaping layer guarantees that punctuation you author can never be mistaken for markup. What a particular renderer does beyond the specification is its own affair, and so everything in this section is subject to your renderer of choice.

Tables are the notable case. CommonMark itself has no table syntax; the nearly-universal extension is the pipe table, where cells of a row are separated by vertical bars. A <tabular> of simple cells is emitted in this form, and virtually every renderer—repository-hosting websites, editors, notebook interfaces—will display a real table. A strict CommonMark renderer without the extension shows the same content as readable pipe-separated lines, so nothing is lost.

Mathematics is authored LaTeX riding between dollar signs, the convention MathJax-enabled renderers recognize. Each page of a markdown build opens with an invisible block of macro definitions, so your macros, and PreTeXt’s, work throughout the page. With a MathJax-capable renderer (many repository-hosting websites and editors qualify) the mathematics simply renders; anywhere else it reads as the LaTeX you wrote, which is the long-standing convention for mathematics in plain text anyway. The plain text conversion does exactly that, and nothing more, on the same reasoning.

Finally, images and their layout use a small amount of raw HTML, as do the invisible anchors that cross-reference links land on. Raw HTML is legal CommonMark, and renderers overwhelmingly accept these particular tags, but an aggressively-sanitizing renderer may strip them.