Should fenced code blocks always remain visible as source?

[andrewvelez]

I started thinking about this after trying to save a Mermaid diagram from a GitHub README as an image. The diagram was written inside a fenced code block, but GitHub had replaced the source with the rendered diagram.

That is convenient, but it seems to cross an important boundary.

If I put JavaScript in a code block, the JavaScript is the content I expect the reader to see. Syntax highlighting might change its appearance, but it remains source code.

If I put Mermaid source in a code block and the renderer replaces it with a diagram, the source is no longer the content. It has become an implementation used to generate the actual content. In that case, I think the diagram should be rendered separately as an SVG or PNG and included using Markdown’s existing image syntax. The Mermaid source can remain in a separate .mmd file, or it can be shown in a code block when the source itself is relevant.

The same distinction applies to Graphviz, PlantUML, Vega specifications, LaTeX used solely to generate graphics, notebook instructions, serialized binary data, and other text-encoded formats.

Markdown’s defining strength is that its source remains recognizably readable as the document. A code fence lightly annotates literal text; it should not silently turn that text into instructions for producing different content.

The specification gap

CommonMark says that fenced-code contents are treated as literal text and are not parsed as inline Markdown. However, it intentionally does not prescribe how parsed elements are rendered. In an earlier discussion, this was interpreted to mean that replacing a specially marked code block with a diagram remains compatible with the specification:

Proposal to relax fenced blocks definition

The spec calls them “code blocks,” but never says they’re “for code only.” All it says is that “the content is treated as literal text, not parsed as inlines.” This is incompatible with one of your examples (“wrapper with some attributes for inner markdown”). And I wouldn’t want to change that: it would create too much confusion if sometimes the contents were parsed as markdown, and sometimes not. But it is compatible with many uses other than code. Remember, the spec doesn’t prescribe how t…

GitHub now performs exactly this replacement for fenced blocks marked mermaid:

Creating diagrams - GitHub Docs

This may be compatible with the current parsing specification, but it undermines the document model that “literal text” naturally communicates.

The slippery slope has no limiting principle

Mermaid appears benign because diagrams are useful and its syntax is familiar. But once an information string is permitted to select an interpreter that replaces literal source with generated output, there is no principled boundary at diagrams.

If mermaid may invoke a diagram renderer, then by the same rule:

• latex may invoke a mathematical or document renderer.
• vega may invoke a charting runtime.
• sql may execute a query and display its current results.
• python may execute code and replace it with generated output.
• A notebook language may produce an interactive computation.
• A UI language may instantiate controls or an application.
• A remote-content language may retrieve and render external resources.
• Any third-party plug-in may assign arbitrary behavior to another information string.

At that point, the information string is no longer primarily a language identifier for displayed source. It is an interpreter selector, and the fenced body is its payload.

Markdown then becomes an unspecified polyglot host or build format. Understanding the document requires knowing which interpreters, versions, plug-ins, permissions, network resources, and security policies a particular renderer provides. Two nominally conforming renderers can present fundamentally different documents from identical source. A raw Markdown file is no longer the document; it is merely input to an open-ended execution environment.

This is not a hypothetical security argument needed to reject one dangerous extension while retaining the others. It is a structural problem: the current interpretation supplies no criterion by which Mermaid is legitimate but the next embedded language is not. Each addition makes the next one easier to justify.

Proposed requirement

I suggest adding rendering-conformance language along these lines:

A conforming Markdown renderer MUST present the contents of a fenced code block as literal text. The information string MAY influence source-oriented presentation, including syntax highlighting, line numbering, or textual annotation. It MUST NOT cause the contents to be executed or interpreted and replaced by generated non-text output. Generated non-text content MUST be incorporated using explicit resource-reference or embedding syntax.

If CommonMark intends to remain strictly parser-focused, the same rule could be introduced as a strict-rendering conformance profile or an explicit design principle for downstream specifications such as GFM.

Implementations could still offer executable or generative fences, but they should label them as extensions outside strict Markdown conformance rather than allowing them to redefine what a standard code block means.

This preserves a durable boundary:

• Code fences display source.
• Image and resource syntax display finished artifacts.
• Links reference external material.
• Extension systems remain explicitly extensions.

Without that boundary, Markdown’s ability to contain arbitrary text gradually becomes a justification for making it contain arbitrary languages, runtimes, and applications. That reverses its original purpose: keeping a structured document readable as plain text.

[vas]

See also Mermaid - Generation of diagrams and flowcharts from text in a similar manner as markdown