Markdown code block languages: choose a tag

Put a destination-supported language tag after the opening fence of a Markdown code block, and leave the closing fence bare. Four output states determine the repair: broken block structure, a missing language label, a preserved label without highlighting, or generated highlighting markup that still needs styling.

Match the output to the repair

Repair the earliest failed stage before changing the language name. The same Python snippet produced different HTML when we changed the parser configuration. 8

What you see How to identify it Repair path
Backticks or a compressed inline snippet Generated HTML has a paragraph or inline code, without a preformatted block Fix the fence syntax or enable fence support
A code block with no usable language label The block exists, but its language class is absent or contains the attribute syntax itself Use the destination's accepted tag syntax
A language label with uncolored code The label survives, but this build emits no token markup Configure a highlighter and its grammar
Token markup with no visible color Generated HTML contains separately marked code tokens Inspect the theme and computed styles. Browser styling was outside our tests

Inspect the HTML before browser scripts modify it when diagnosing the converter itself. A client-side highlighter can add token markup later, so its absence from the initial fragment describes that build stage. A label such as language-python only tells you that a name reached the HTML. A parser can preserve a made-up name through the same mechanism.

When the block exists, a supported plain-text label can express that coloring is unnecessary. When the fence has become inline code or ordinary prose, changing the label to plain text does not restore the missing block. Our unconfigured Python-Markdown path demonstrated that second failure with an otherwise ordinary Python fence. 8

Choose a Markdown code block language for the destination

Choose tags from the destination's documented names, because Markdown has no universal registry of highlighted languages. The text after an opening fence is called its info string. CommonMark leaves its interpretation to implementations, while the first word conventionally identifies the language. 1

This was the Markdown input shared by our local paths:

```python
        name = "alpha"
        print(name)
        print("done")
        ```
        

The tag belongs on the opening line. The closing line contains only the fence. Putting the word Python inside the block makes it sample content.

Content Starting tag What supports this choice
Python source python Our fence-enabled local paths preserved the block. Pandoc also generated token markup
Python source using a short alias py Our Pandoc build normalized it to Python. The other fence-enabled paths only preserved the name
JavaScript for MDN documentation js MDN's authoring rules require this identifier and disallow javascript there
Plain output or a transcript text, if the destination accepts it Our fence-enabled paths kept a code block without token markup. MDN instead documents plain

GitHub points authors to Linguist's language definitions for accepted names. Pandoc exposes the languages supported by its installed highlighter through its command line. MDN publishes its own authoring list. These are separate contracts: an accepted alias in an export tool does not establish that a documentation site's linter accepts it. 267

Use a lower-case spelling from the destination's list when the document will also become a GitHub Pages page, as GitHub recommends. For a document that moves between a repository and a documentation build, use a spelling accepted by both. Keep titles and other display options out of the shared fence line unless both builds explicitly support that syntax. 2

An unknown label is useful for diagnosing the handoff, but cannot establish language support. In our test, not-a-language survived as a class in markdown-it-py and fence-enabled Python-Markdown. Pandoc kept the content as a block without generating highlighted tokens. 8

Separate a language label from highlighted tokens

A parsed fence can preserve its language label without performing syntax highlighting. Our local paths separated these jobs in their output, so a correct label did not justify changing the sample's code to chase colors. 8

markdown-it-py: a label without a highlighter

The CommonMark preset kept the Python label and escaped the quotation marks. It did not add token markup in this configuration.

Output from our plain Python sample, unedited:

<pre><code class="language-python">name = &quot;alpha&quot;
        print(name)
        print(&quot;done&quot;)
        </code></pre>
        

The renderer's fence method takes the first word of the info string as the language name. It calls a highlighting callback only when one is configured. Otherwise it escapes the content and adds a language class. The same class-building branch accepts an invented name, which explains why a plausible-looking class cannot prove that a grammar was loaded. 4

Python-Markdown: enable fences before adding color

Python-Markdown without extensions interpreted the matched backticks as inline code. The language word became visible content inside a paragraph.

Output from our plain Python sample, unedited:

<p><code>python
        name = "alpha"
        print(name)
        print("done")</code></p>
        

Enabling fenced_code restored the preformatted block and language class, without adding token markup.

Output from our plain Python sample, unedited:

<pre><code class="language-python">name = &quot;alpha&quot;
        print(name)
        print(&quot;done&quot;)
        </code></pre>
        

The extension documentation treats highlighting as a separate CodeHilite/Pygments integration. A theme alone cannot turn the default inline result into a block. Fence parsing must succeed before a highlighter can process the block through that extension. CodeHilite/Pygments highlighting was not executed for this guide. 3

Pandoc: highlighted HTML from the same input

Pandoc's GFM-to-HTML path generated marked tokens for assignment, strings, and function calls. Its shorter Python alias produced the same Python language class as the full name. 8

Output from our plain Python sample, unedited:

<div class="sourceCode" id="cb1"><pre
        class="sourceCode python"><code class="sourceCode python"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>name <span class="op">=</span> <span class="st">&quot;alpha&quot;</span></span>
        <span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="bu">print</span>(name)</span>
        <span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="bu">print</span>(<span class="st">&quot;done&quot;</span>)</span></code></pre></div>
        

This is evidence of token markup, without a browser color test. Pandoc's HTML writer uses its highlighting machinery after reading the input. Selecting GFM as the reader does not select GitHub.com's rendering service. A page still needs styles that target the emitted classes. 6

Tested configuration Useful behavior observed Failure boundary observed
markdown-it-py, CommonMark preset Keeps a labeled block Does not generate highlighting tokens without a callback
Python-Markdown, no extensions Keeps the text in an inline span Does not produce a fenced block
Python-Markdown with fence extension Restores a labeled block Rejects opening-line text outside its supported syntax
Pandoc, GFM reader to HTML Emits highlighted Python tokens Unknown labels keep the block without those tokens

Keep extra info and closing fences portable

For a document shared across these implementations, keep only the language on the opening line and use an identical, bare fence to close it. Extra display instructions and unequal fence lengths triggered different parsing behavior in our local paths. 8

A Python language label followed by a filename attribute still formed a Python block in markdown-it-py and Pandoc. In the tested Python-Markdown fence extension, it fell back to inline code. Its opening-line matcher accepts specific language or brace-delimited attribute forms. Arbitrary text after the language does not fit that alternative. 5

An info string of {.python} supplied a Python language class to the Python-Markdown extension. The CommonMark preset preserved the braces inside its language class, while Pandoc's tested GFM path emitted an unlabeled block. Moving the filename into the sentence before the block avoids requiring these parsers to agree on attribute syntax. 8

Under CommonMark, the closing fence uses the opening character and may be longer, but it cannot carry a language or other trailing text. A missing valid close leaves the rest of the containing block inside the code. That explains why adding a language to both fence lines can swallow a following heading. 1

The fence extension's source adds a narrower constraint: its matcher uses the captured opening fence again at the close. Our longer-close sample became ordinary prose in Python-Markdown, while markdown-it-py and Pandoc kept the block. Matching the opening and closing lengths avoids that implementation difference. 58

Symptom after moving the document Distinguishing evidence Concrete change
Adding a title turns the sample inline A bare language works in the same configuration Put the filename in surrounding prose
A braced language becomes an odd label HTML contains the braces as part of the language class Use a bare tag supported by that destination
A heading below the sample becomes code The supposed closing line has a language attached Remove the language from the closing line
A longer closing fence stops forming a block Equal-length fences work with the same content Match both fence lengths

When cleaning up PDF to Markdown output, restore the code's indentation and quotation marks against the source excerpt before adding language tags. A fence preserves the text it receives. Changing its language cannot recover punctuation lost during extraction.

If the block and label already survive, change the highlighting configuration at the stage that lacks token markup or styling.

How we tested

These results establish local parsing and token-markup behavior for the recorded configurations. They do not measure browser colors, accessibility, execution of arbitrary code, or the behavior of GitHub.com or VS Code.

We ran Python 3.11.14 with markdown-it-py 4.0.0, Python-Markdown 3.10.2, and pandoc 3.11 on 2026-11-07. The earlier upstream lab/renderers/results.json supplied a basic code-block example. This guide added only language-related cases, leaving its unrelated table, list, checkbox, and line-break matrix outside the article.

Input file Case represented
lab/renderers/language-python.md Bare Python label with a matched fence
lab/renderers/language-py-alias.md Short Python alias
lab/renderers/language-unknown.md Invented language label
lab/renderers/language-plain-text.md Explicit text label
lab/renderers/language-unlabeled.md No info string
lab/renderers/language-extra-info.md Language followed by a title attribute: python title="input.py"
lab/renderers/language-braced-language.md Brace-delimited language class
lab/renderers/language-long-close.md Closing fence longer than opening
lab/renderers/language-tagged-close.md Language appended to the attempted close

Every case used the same code body and a following heading, After code. We ran all cases through these configurations:

Path Exact configuration
markdown-it-py MarkdownIt("commonmark").render(source), no highlight callback
Python-Markdown default markdown.markdown(source), no extensions
Python-Markdown fenced markdown.markdown(source, extensions=["fenced_code"]), no CodeHilite
Pandoc pandoc -f gfm -t html, source on standard input, no filters, custom grammar, or theme

Reproduce from this repository's root with its installed dependencies:

env PYTHONDONTWRITEBYTECODE=1 .venv/bin/python runs/2026-11-07-markovo-markdown-code-block-language/lab/code-language.py --lab runs/2026-11-07-markovo-markdown-code-block-language/lab
        pandoc --list-highlight-languages
        

The runner writes the exact Markdown inputs and raw HTML fragments as UTF-8 text. It also executes the shared Python sample, whose output is saved in lab/renderers/language-python-execution.txt. Source inputs are rendered as text. The renderer does not execute code fences. 9

The machine-readable results contain every input/output filename, SHA-256, configuration, and count. For each HTML fragment, the runner counts pre elements, code elements, h2 elements, and span elements with a nonempty class. A code element can be inline, so its presence alone does not establish a fenced block. Class-bearing spans indicate emitted token markup. They do not score grammar correctness or visual quality. These definitions come from this syntax runner, not the PDF-specific scorer. 8

Each cell below is preformatted blocks / class-bearing token spans / following headings. Zeros are measured counts. The table includes every tested language-related case, including failures.

Sample markdown-it-commonmark python-default python-fenced pandoc-gfm
python 1/0/1 0/0/1 1/0/1 1/5/1
py-alias 1/0/1 0/0/1 1/0/1 1/5/1
unknown 1/0/1 0/0/1 1/0/1 1/0/1
plain-text 1/0/1 0/0/1 1/0/1 1/0/1
unlabeled 1/0/1 0/0/1 1/0/1 1/0/1
extra-info 1/0/1 0/0/1 0/0/1 1/5/1
braced-language 1/0/1 0/0/1 1/0/1 1/0/1
long-close 1/0/1 0/0/1 0/0/1 1/5/1
tagged-close 1/0/0 0/0/1 0/0/1 1/6/0

Raw outputs follow lab/renderers/language-<case>--<path>.txt. For the excerpts above, the case is python and the paths are markdown-it-commonmark, python-default, python-fenced, and pandoc-gfm. The installed Pandoc language list is lab/renderers/language-pandoc-registry.txt. The source audit records the inspected functions, installed file hashes, and links to versioned upstream source. 10

The tests used no browser, third-party highlighting plugins, or Markovo conversion API. They provide no OCR, accuracy, speed, or product-ranking measurements.

Sources

  1. CommonMark 0.31.2: fenced code blocks
  2. GitHub: creating and highlighting code blocks
  3. Python-Markdown: fenced code blocks extension
  4. markdown-it-py 4.0.0: RendererHTML.fence
  5. Python-Markdown 3.10.2: fence matcher
  6. Pandoc: syntax highlighting
  7. MDN: example code blocks
  8. Local rendering results and output hashes
  9. Reproduction runner
  10. Versioned source audit