Markdown code block types: fences and indents
Use fenced blocks for new multiline examples and indented blocks when maintaining existing literal text. The two Markdown code block types differ in how they start and how surrounding text affects them: fences mark explicit boundaries, while indented blocks depend on whitespace and paragraph boundaries. Inline code is a separate form that stays inside a sentence. A list adds another constraint because it consumes indentation before the snippet becomes a block.
Classify Markdown code block types
Choose the form by where the code belongs and whether its line breaks must survive.
| What you are writing | How to recognize the case | Form to use |
|---|---|---|
| An identifier or short command inside a sentence | In the HTML, the code stays inside the paragraph without a preformatted wrapper | Inline code span |
| A standalone snippet, log or configuration example | Opening and closing fence markers occupy separate lines, and the HTML has a preformatted code wrapper | Fenced code block |
| An existing example delimited by leading spaces | At the document root, content lines have at least four leading spaces and a blank line separates them from preceding prose | Indented code block |
| A snippet inside an instruction list | Inspect the HTML for a preformatted wrapper inside the list item | A fence supported inside that renderer's list container, or the tested indented form |
Backticks and tildes are alternative delimiters for the fenced form. A language name after the opening fence describes its content. Neither choice creates another structural type. 18
A snippet from a PDF to Markdown converter may need its paragraph boundary restored or its surrounding indentation adjusted before it can become a code block. Adding a language label cannot perform either repair.
Use fences for standalone snippets
Use fences for standalone examples whose line breaks must remain in rendered output.
Put the opening and closing delimiters on their own lines. For ordinary snippets, use matching runs of backticks around the content. GitHub's authoring documentation recommends blank lines around the block for source readability. That recommendation is distinct from the CommonMark parsing rule, which permits a fence to interrupt a paragraph. 21
Markdown input from our standalone sample, unedited:
```python
print("alpha")
print("beta")
```
markdown-it-py output from our standalone sample, unedited:
<pre><code class="language-python">print("alpha")
print("beta")
</code></pre>
The markdown-it-py output has a preformatted wrapper around the code. Its escaped quotation marks decode to the original characters, and the statements remain on separate lines. This is a block even without colored tokens. In this configuration, the renderer's highlighting callback is absent, so it escapes the content and attaches the language class. 611
Tildes serve the same purpose when the content contains backticks. Our tilde-delimited input retained the same statements as the backtick-delimited input across the tested configurations. The fence parser accepts either marker through the same parsing routine. Keep the marker consistent between the opening and closing line. 811
To teach fence syntax, enclose the example in a longer outer fence. The inner delimiter then becomes content. This is different from putting a code block inside a list: the inner example is literal text inside the outer block, so it does not need container support. 2
Markdown input from our fence-within-an-example sample, unedited:
````markdown
```python
print("alpha")
print("beta")
```
````
The outer block preserved the inner fence as visible source in every tested configuration. For a document shared between these renderers, matching the opening and closing length also avoids a documented difference: Python-Markdown's built-in extension requires an exact match, while CommonMark permits a longer closer. 3111
| Fence symptom | What it points to | Repair |
|---|---|---|
| The block is present but has no token colors | The language label reached the output without an active highlighter | Configure highlighting for the destination |
| The inner example closes the surrounding block | The outer delimiter also matches an inner closing line | Lengthen both outer delimiters or use the other marker |
| Literal backticks appear inside an unlabeled block | The entire fenced example may have become indented code | Remove unintended indentation around the whole example |
Keep indented blocks clear of paragraphs
A blank line decides whether indented text starts a block after prose.
At the document root, indent every content line by at least four spaces. The parser removes the code indentation and preserves what remains as literal content. This form has no fence header for a language label. 114
The preceding paragraph changes the result even when the code indentation stays identical. Our attached sample placed indented statements immediately after an ordinary sentence. Each tested renderer kept them in a paragraph. Adding a blank line created a code block in every configuration. 11
markdown-it-py output from our paragraph-attached sample, unedited:
<p>Run this:
print("alpha")
print("beta")</p>
While continuing an existing paragraph, the markdown-it-py paragraph parser treats a more deeply indented line as a continuation and advances to the next line. An empty line ends that paragraph, allowing the code-block rule to handle the following indented content. Adding spaces without ending the paragraph leaves the same parser branch active. 513
Indenting an entire fenced example produces an indented block containing the fence markers. In our output, the opening marker and its language name appeared alongside the statements. The fence parser explicitly declines a line already classified as code indentation. 811
A source line break inside a CommonMark code span becomes a space. Our inline sample therefore joined the words inside the sentence. Use a block for a command sequence or configuration where separate lines carry meaning. A monospace font alone does not establish that the source became a preformatted block. 111
| Source context | Observed output | Editing decision |
|---|---|---|
| Indented statements attached to prose | Paragraph text without a code wrapper | Insert a paragraph break before the statements |
| The same statements after a blank line | A preformatted code block | Keep the indentation if this is the intended form |
| A fenced example indented as a whole | A code block containing literal fence markers | Remove the outer indentation to activate the fence |
| A line break inside an inline span | Inline code with normalized whitespace in the CommonMark configuration | Switch to a block when the line boundary matters |
Keep list indentation separate from code indentation
A list consumes indentation before the code parser sees the snippet.
Inside a list, leading spaces first associate content with the item. Additional indentation can then create a code block. Copying the indentation of a standalone example into a list therefore changes its role. For a fence, the delimiter and its content must stay within the item, and the renderer must support fences there. 18
We placed the same fenced example inside a bullet item. markdown-it-py and Pandoc retained a code block inside that item. Python-Markdown with its built-in fenced-code extension emitted inline code instead, including the language name as content. 11
Python-Markdown output from our list-fence sample, unedited:
<ul>
<li>
<p>Run:</p>
<p><code>python
print("alpha")
print("beta")</code></p>
</li>
</ul>
The Python-Markdown extension searches for a fence at the document root during preprocessing. The indented opener does not match that search, leaving an inline element instead of the requested preformatted block. 3410
For the same input, Pandoc retained the list item and emitted token markup inside a preformatted block. Its HTML writer highlights supported languages. 711
Pandoc output from our list-fence sample, unedited:
<ul>
<li><p>Run:</p>
<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><span class="bu">print</span>(<span class="st">"alpha"</span>)</span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="bu">print</span>(<span class="st">"beta"</span>)</span></code></pre></div></li>
</ul>
For the tested Python-Markdown configuration, removing the fence and adding deliberate code indentation retained a block inside the list. That is an available fallback when language metadata is unnecessary. The official documentation also points to SuperFences for nested fences, but that extension was not executed for this guide. 311
| List symptom | What the output distinguishes | Route |
|---|---|---|
| A preformatted block remains inside the item | Container placement and block recognition both succeeded | Keep the source structure |
| Inline code contains the language name | The fence was not recognized as a block in that context | Use the tested indented form or a renderer with nested-fence support |
| The example belongs outside the list | Container indentation is unnecessary for the intended document | Move the example outside the item and use a standalone fence |
Choose fences for new standalone examples and keep deliberate indented blocks when their boundaries are already correct. When a snippet changes after pasting, repair the paragraph boundary or list context that changed its interpretation. In the tested Python-Markdown list case, an indented block preserved the snippet where the built-in fence extension did not.
How we tested
The tests isolate block parsing and list containment in local renderers, with synthetic Markdown inputs and saved HTML text outputs. They do not test GitHub.com, VS Code, browser styling, execution of the displayed Python statements, PDF conversion, or Markovo rendering capabilities.
The run used Python 3.11.14 on 2026-11-07. Installed versions and options were:
| Configuration | Version | Exact options |
|---|---|---|
| markdown-it-py CommonMark | markdown-it-py 4.0.0 | MarkdownIt('commonmark'), no highlighting callback |
| Python-Markdown fenced | Markdown 3.10.2 | markdown.markdown(source, extensions=['tables', 'fenced_code']), no CodeHilite |
| Pandoc GFM | Pandoc 3.11 | pandoc -f gfm -t html, default HTML highlighting |
The upstream generic matrix remains in lab/renderers/results.json; the focused experiment below is recorded separately.
Run this complete command from the repository root:
.venv/bin/python runs/2026-11-07-markovo-markdown-code-block-types/lab/renderers/types_probe.py
The runner contains every input and invocation. It writes the inputs, HTML outputs and result JSON beside itself. The source audit records the installed parsing and rendering modules with SHA-256 hashes. The source diagnosis follows the paragraph continuation branch, the fence parser's indented-code early return, and Python-Markdown's root-level preprocessing matcher. 45891213
The corpus and count summary cover only the code-structure cases. Each result cell links its unedited output. The tuple is pre / code / pre-in-li: counts of opening pre tags, all opening code tags including inline code, and pre tags with a li ancestor. The Python standard library's HTMLParser supplies these structural counts. Decoded block and inline text, source hashes and output hashes are also stored in the result JSON. Counts measure structure, not visual quality or syntax correctness. 11
| Input and represented shape | markdown-it-py CommonMark | Python-Markdown fenced | Pandoc GFM |
|---|---|---|---|
| types-inline.md: Inline span crossing a source newline | 0/1/0 | 0/1/0 | 0/1/0 |
| types-backticks.md: Standalone backtick fence | 1/1/0 | 1/1/0 | 1/1/0 |
| types-tildes.md: Standalone tilde fence | 1/1/0 | 1/1/0 | 1/1/0 |
| types-indented.md: Standalone indented code | 1/1/0 | 1/1/0 | 1/1/0 |
| types-indented-attached.md: Indented lines attached to prose | 0/0/0 | 0/0/0 | 0/0/0 |
| types-indented-separated.md: Same lines after a blank line | 1/1/0 | 1/1/0 | 1/1/0 |
| types-fenced-attached.md: Fence attached to prose | 1/1/0 | 1/1/0 | 1/1/0 |
| types-overindented.md: Entire fenced example indented | 1/1/0 | 1/1/0 | 1/1/0 |
| types-list-fenced.md: Fence inside a bullet item | 1/1/1 | 0/1/0 | 1/1/1 |
| types-list-indented.md: Indented block inside a bullet item | 1/1/1 | 1/1/1 | 1/1/1 |
| types-nested-example.md: Literal inner fence inside a longer outer fence | 1/1/0 | 1/1/0 | 1/1/0 |
The list-fence case reproduces the root-only limitation discussed in Python-Markdown issue 53 on the installed version with the stated extensions. It is a new minimal example of that limitation, not a replay of every historical attachment. SuperFences was not executed for this guide. No PDF scorer or OCR scores apply to this Markdown-rendering experiment. 31011
Sources
- CommonMark 0.31.2: indented blocks, fences and code spans
- GitHub: creating and highlighting code blocks
- Python-Markdown: fenced code blocks extension
- Python-Markdown 3.10.2: fenced-code preprocessor
- markdown-it-py 4.0.0: paragraph parser
- markdown-it-py 4.0.0: HTML renderer
- Pandoc User Guide: syntax highlighting
- markdown-it-py 4.0.0: fence parser
- markdown-it-py 4.0.0: indented-code parser
- Python-Markdown issue 53: fenced blocks in lists and blockquotes
- Focused rendering results, structure counts and hashes
- Reproduction script for block-structure probes
- Installed source snapshots with per-module hashes
- Original Markdown syntax: code blocks


