Markdown codeblocks - cheatsheet and how to use examples

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

Markdown codeb blocks

Markdown code blocks are a way to 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 less common 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!")
```

Then the rendered text would look like:

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

Best Practices for Using 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 can highlight 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).

OutTake

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.

Diff Syntax Highlighting

To effectively use diff syntax highlighting in Markdown code blocks, follow these steps:

• Use fenced code blocks with triple backticks (```) to start and end your block.
• Specify diff as the language identifier immediately after the opening backticks. This enables syntax highlighting for differences, similar to what you see in Git commit messages or pull requests.

Example:

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

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

Best practices:

• Use this format to clearly communicate code changes, fixes, or suggestions in documentation, code reviews, or technical blogs.
• 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:
This method is widely supported on platforms like GitHub, GitLab, and many Markdown renderers, making it a reliable choice for sharing code changes visually.

Supported languages

Markdown code blocks support a wide variety of languages for syntax highlighting, but the exact set of supported languages depends on the renderer or platform you are using. Markdown itself does not define which languages are supported; it simply passes the language identifier to the rendering engine, which then applies the appropriate syntax highlighting. Markdown code fences themselves do not define a fixed set of officially supported programming languages. Instead, the list of supported languages depends on the Markdown renderer or platform you are using (such as GitHub, GitLab, VS Code, Typora, Quarto, etc.).

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

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programming: python (py), java, c, c++, 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 visualizations 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: Use the language name immediately after the opening triple backticks:

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

The following languages are widely supported across MOST Markdown renderers:

Note: The actual identifier can vary (e.g., js vs. javascript). Most renderers are case-insensitive for language names.

Finding the full list of supported languages:

• GitHub: Uses Linguist for highlighting, 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.

Key points:

• Most platforms support all major programming, scripting, and markup languages.
• Some platforms also support diagram and data formats (like mermaid, geojson).
• The language identifier is typically case-insensitive but should be in lower case for best compatibility.
• If you use an unsupported language identifier, the code block will render as plain text.

Specifying filename in Markdown code block

To specify a filename in a Markdown code block, you have several options, but the method depends on the platform and renderer:

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

Some Markdown engines (such as certain static site generators, documentation tools, and blogging 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 will display the filename (e.g., app.js) above or alongside the code block, depending on the renderer. And this website’ hugo renderer doesn’t do that:

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

Note: This is not supported on all platforms (e.g., GitHub-flavored Markdown does not currently support this feature).

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 a heading or bold inline code:

**`app.js`**

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

Or:

#### `app.js`

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

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

3. Filename as a Comment in the Code

Alternatively, you can include the filename as a comment inside the code block itself:

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

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

Summary and Best practice

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

Useful links

• Markdown Cheatsheet - Most useful structures and commands
• Hugo Cheat Sheet
• Bash Cheat Sheet - Most useful bash commands
• LaTeX Cheat Sheet
• Most popular themes for Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks