Use Fenced Code Blocks with Language Tags in Markdown

Problem and takeaway

You paste shell commands or source code into a Markdown file, but the rendered page shows italicized words, missing angle brackets, or plain text instead of syntax-highlighted code. This happens when the parser treats the text as inline Markdown or HTML rather than a code block.

The practical takeaway is to wrap code in a fenced code block with an info string, then confirm that your renderer exposes the language identifier. Fenced blocks are a CommonMark and GitHub Flavored Markdown (GFM) feature; an info string is the short tag immediately after the opening backticks, such as python or shell.

Desired outcome

• The parser emits a code-block element, not a paragraph or inline text.
• The info string appears as a language class or attribute, for example language-python.
• Code content stays literal: asterisks, angle brackets, and backticks inside the block are not interpreted as Markdown or HTML.

Prerequisites

• A Markdown file and a plain-text editor.
• A renderer that implements CommonMark or GFM. CommonMark is a standardized specification for Markdown parsing; GFM is GitHub's variant, which extends CommonMark with table and task-list syntax.
• Control over the source text only. Syntax highlighting itself depends on the renderer's CSS, JavaScript, or integrated highlighter.

Procedure

1. Place the opening fence at column zero, or indented by no more than three spaces. Indenting more than three spaces can cause the parser to treat the block as an indented code block instead.
2. Type three or more backtick characters (`).
3. Immediately add an info string, such as python, javascript, or text. Do not add trailing spaces after the info string.
4. Write the code verbatim on the following lines.
5. Close the block with a fence of the same character and the same length or longer than the opening fence.

Concrete example

```python
def greet(name):
    print(f"Hello, {name}")
    if :
        return name
```

In this example, the opening fence is three backticks followed by python. The closing fence is also three backticks. Inside the block, the angle brackets around name and the quotation marks remain literal text rather than HTML tags or Markdown emphasis.

When the code itself contains backticks

If your code sample includes a sequence of three backticks, a three-backtick opening fence will end prematurely. Use a longer opening fence and match it at the close:

````
output = """
```python
print("nested fence")
```
"""
````

Here the opening fence is four backticks, so the triple-backtick sequence inside the code does not terminate the block.

Expected checks

• Render the file and inspect the generated HTML or abstract syntax tree (AST). Look for a pre or code element whose class or attribute matches the info string, such as language-python.
• Confirm that code containing *emphasis*, <tag>, and `backticks` appears unchanged in the output.
• Verify that the closing fence ends the block and that subsequent Markdown headings or lists render normally.

Diagnostic decision: fence length and renderer support

Situation	Recommended fence	Check
Ordinary code sample	Three backticks plus info string	Renderer emits a language class
Code contains triple backticks	Four or more backticks	Block does not close early
Older or minimal Markdown parser	Indented code block (four spaces)	Fenced block may render as literal text
Unknown or disallowed language	Use text or omit the info string	Renderer falls back to plain code block

Recovery and fallback

If the block breaks or highlighting is missing:

1. Check that the closing fence is the same character and equal to or longer than the opening fence.
2. Check that no trailing spaces follow the info string.
3. Check that the opening fence is indented at most three spaces.
4. Confirm the renderer supports fenced blocks and info strings. Legacy Markdown.pl may not support them at all.
5. Fallback: convert the fenced block to an indented code block by prefixing every line with four spaces, or use a longer opening fence such as four backticks.

Because this procedure only edits a text file, there is no system state to roll back. If a change causes rendering problems, revert the Markdown source to the previous version or replace the fenced block with an indented block.

Practical verification

Render a sample file with your target parser and inspect the output. For example, on a system with the cmark CommonMark reference implementation installed, run from a terminal:

cmark sample.md > rendered.html
grep -n 'language-python' rendered.html

Where to run: a local terminal or CI job. Permissions: read access to sample.md; no elevated privileges required. Placeholders: replace sample.md with your file name. Expected check: grep returns a line containing the language class. Risk: if cmark is not installed, the command fails; this does not damage the source file. This example is illustrative and has not been executed by this document.

Limitations

• An info string is metadata, not an executable directive. A renderer may ignore unknown languages or sanitize class names.
• Class naming varies: some renderers use language-python, others use python, and some require an allow-listed set of languages.
• Fenced code blocks are not part of the original Markdown specification. Older or minimal parsers may render them as literal text or paragraphs.
• Syntax highlighting requires the renderer to load a highlighter and corresponding CSS; the Markdown source alone cannot force it.

Behavior described here assumes CommonMark 0.31 or GitHub Flavored Markdown. If you must support legacy Markdown.pl, test in that parser before relying on fenced blocks or info strings.