Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples

Here I’m reviewing Codeblock options in Markdown—how to specify the programming language, diff formatting and code block filename.

This guide is part of our Documentation Tools in 2026: Markdown, LaTeX, PDF & Printing Workflows hub.

Markdown Code Blocks Overview

Markdown code blocks display code or preformatted text within Markdown documents, preserving formatting and optionally enabling syntax highlighting. There are two main types of code formatting in Markdown: inline code and code blocks.

Types of Markdown Code Blocks

Key Differences

• Inline code uses single backticks (`) and is for short code within a sentence.
• Indented code blocks use four spaces or a tab at the start of each line. They do not support syntax highlighting and are uncommon in modern Markdown.
• Fenced code blocks use triple backticks (```) or tildes (~~~) before and after the code. This is the preferred method, especially on platforms like GitHub, because:
  • They are easier to read and write.
  • You can specify the programming language immediately after the opening backticks for syntax highlighting.
  • They preserve formatting and support multi-line code.

Example of a fenced code block with syntax highlighting:

When we have the following Markdown-formatted text:

```python
def hello():
    print("Hello, world!")
```

The rendered output looks like:

def hello():
    print("Hello, world!")

Best Practices for Markdown Code Blocks

• Use fenced code blocks (triple backticks) for multi-line code to ensure clarity and compatibility across platforms.
• Specify the language after the opening backticks for syntax highlighting (e.g., ```python).
• Use inline code for short snippets or commands within text.
• Avoid indented code blocks unless required for legacy compatibility, as they do not support syntax highlighting and can be less readable.
• Place a blank line before and after fenced code blocks to improve readability in raw Markdown.

Special Features

• Some platforms support additional language identifiers such as diff for showing code changes, which highlights added or removed lines in code reviews.
• To display backticks inside a code block, wrap the block in a higher number of backticks (e.g., four backticks to display three backticks inside).

Quick Reference Summary

Use fenced code blocks with a language identifier for the best readability and syntax highlighting. Reserve inline code for short snippets, and avoid indented blocks unless necessary for compatibility.

Code blocks pair naturally with tables in Markdown to build well-structured technical documentation.

Diff Syntax Highlighting

Diff syntax highlighting lets you show code changes clearly — useful in documentation, code reviews, and technical blogs.

• Use fenced code blocks with triple backticks (```) to start and end your block.
• Specify diff as the language identifier immediately after the opening backticks.

Example:

- old line that will be removed
+ new line that will be added
  unchanged line

• Lines starting with - are highlighted as deletions (usually red).
• Lines starting with + are highlighted as additions (usually green).
• Lines without a prefix are not specially highlighted.

Best practices:

• Place a blank line before and after your code block for better readability in raw Markdown.
• Note that diff highlighting only colors entire lines based on the leading character; it does not highlight inline changes within a line.

Tip: Diff highlighting is widely supported on GitHub, GitLab, and most Markdown renderers, making it a reliable choice for communicating code changes.

Supported Languages for Syntax Highlighting

The exact set of supported languages depends on the renderer or platform you use. Markdown passes the language identifier to the rendering engine, which applies the appropriate syntax highlighting. This matters when converting HTML to Markdown with Python, since <code> tags carrying language class attributes (e.g. class="language-python") map directly to these identifiers in the fenced block.

Commonly supported languages on major platforms (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programming: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Data & Query: sql, r, matlab
• Markup & Config: markdown, ini, toml, dockerfile, makefile
• Special: diff, mermaid, geojson, topojson, stl (for diagrams and data visualisations on GitHub)
• Others: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, and many more

How to specify a language:

```python
def hello():
    print("Hello, world!")
```

Language identifiers supported across most renderers:

Note: Most renderers are case-insensitive for language names. If you use an unsupported identifier, the code block renders as plain text.

Finding the full list of supported languages:

• GitHub: Uses Linguist, supporting hundreds of languages.
• VS Code & many web renderers: Use highlight.js or Pygments—see their documentation for exhaustive lists.
• Bitbucket: Refers to CodeMirror modes and Pygments lexers.

Specifying a Filename in a Markdown Code Block

Displaying the filename alongside a code block helps readers identify which file a snippet belongs to. Support varies by platform.

1. Filename in the Code Block Label (Meta Syntax)

Some Markdown engines (certain static site generators and documentation platforms) support a meta syntax where you append the filename after the language, separated by a colon:

```js:app.js
console.log("Hello, world!");
```

This displays the filename above or alongside the code block. This site’s Hugo renderer does not support it:

console.log("Hello, world!");

Note: This is not supported on GitHub-flavored Markdown.

2. Manual Filename Heading or Inline Code

For universal compatibility (including GitHub, Stack Overflow, and most Markdown renderers), place the filename above the code block using bold inline code:

**`app.js`**

```js
console.log("Hello, world!");
```

Or with a heading:

#### `app.js`

```js
console.log("Hello, world!");
```

This works everywhere and visually associates the filename with the code block.

3. Filename as a Comment Inside the Code

Include the filename as a comment within the code block itself:

```js
// app.js
console.log("Hello, world!");
```

This is especially useful when you want the filename to be visible when copying the code.

Compatibility Summary

Use bold inline code above the code block for maximum compatibility, and consider a comment inside the code for clarity when sharing across platforms.

Escaping Backticks Inside Code Blocks

To display backtick fences inside a code block — for example when writing documentation about Markdown itself — nest the block in a higher number of backticks:

````markdown
```python
# This triple-backtick fence is inside a four-backtick fence
print("hello")
```
````

Using four backticks as the outer fence lets you show triple-backtick examples inside, which is handy for Markdown tutorials and cheatsheets.

Hugo-Specific: The Highlight Shortcode

If you use Hugo, the built-in highlight shortcode offers more control than plain fenced blocks, including line numbers and highlighted lines:

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

Options:

• linenos=true — show line numbers
• hl_lines=2 4 — highlight lines 2 and 4
• linenostart=10 — start line numbering at 10

This is particularly useful in tutorials or documentation where you want to draw attention to specific lines. See the Markdown Cheatsheet for more formatting features, and the Hugo Cheat Sheet for a broader reference on Hugo commands and templates.

Useful Links

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks