Markdown Code Blocks

Use Markdown code blocks whenever formatting matters. They're commonly used for source code, terminal commands, configuration files, API requests, SQL queries, JSON responses, and documentation examples.

Unlike normal paragraphs, code blocks preserve indentation, spacing, and special characters without applying Markdown formatting. This makes examples easier to read, copy, and reuse.

Most Markdown editors support fenced code blocks, including GitHub Flavored Markdown (GFM), GitLab, VS Code, Obsidian, Discord, and many static site generators.

Markdown provides two ways to display code, depending on how much content you need to show.

Inline Code#

Use inline code for short commands, filenames, variables, keyboard shortcuts, or small code snippets that appear inside a sentence.

Example

Run `npm install` before starting the project.

Output

Fenced Code Blocks#

Use fenced code blocks whenever your example spans multiple lines. Wrap the content with three backticks on separate lines.

Example

```bash
npm install
npm run dev
```

Fenced code blocks are the preferred choice for programming tutorials, API documentation, configuration files, scripts, HTML snippets, SQL queries, JSON examples, and GitHub README files.

💡 Pro Tip: Use inline code for individual commands or keywords. Switch to fenced code blocks as soon as the example requires multiple lines or preserved indentation.

Create a fenced code block by placing three backticks before and after your content.

Example

```text
Hello World
```

Output

Hello World

Markdown treats everything inside the fence as literal text. Characters such as #, *, _, and [] are displayed exactly as written instead of being interpreted as Markdown formatting.

If your Markdown editor supports syntax highlighting, you can specify the programming language immediately after the opening backticks. The next section explains how that works.

Most modern Markdown renderers can highlight keywords, strings, comments, and other language-specific syntax automatically. To enable highlighting, add a supported language identifier immediately after the opening three backticks.

General syntax

```language
Your code here
```

Without a language identifier, the code still renders correctly, but many editors display it as plain text.

Common Language Identifiers#

The language identifier tells the Markdown renderer which syntax highlighting rules to apply.

Most documentation only needs a handful of language identifiers. If a language isn't recognized, the code is still displayed but may not receive syntax highlighting.

The following examples cover the formats developers use most often in GitHub README files, developer documentation, tutorials, and API references.

JavaScript#

function greet(name) {
  console.log(`Hello ${name}`);
}

greet("MDConvertHub");

Bash#

npm install
npm run dev

JSON#

{
  "success": true,
  "message": "User created successfully",
  "id": 123
}

YAML#

name: Build

on:
  push:
    branches:
      - main

README Installation#

npm install
npm run dev

API Response#

{
  "success": true,
  "message": "User created successfully",
  "id": 123
}

Dockerfile#

FROM node:20

WORKDIR /app

COPY . .

RUN npm install

CMD ["npm", "start"]

Code Blocks Inside Lists#

Indented fenced code blocks work correctly inside list items.

1. Install dependencies.

   ```bash
   npm install
   npm run dev
   ```

2. Start the development server.

If you need to include code inside a Markdown table, use inline code where possible. Most Markdown renderers don't support fenced code blocks inside standard table cells.

💡 Workflow Tip: Need to see how fenced code blocks render in a webpage? Open the Markdown to HTML converter to preview the generated HTML while preserving your Markdown source.

Indented Code Blocks#

Markdown also supports code blocks created with four leading spaces.

Example

    function hello() {
        console.log("Hello");
    }

Indented code blocks are valid, but fenced code blocks are generally easier to edit, support syntax highlighting, and work more consistently across Markdown editors.

Escaping Triple Backticks#

If you need to display a fenced code block inside another fenced code block, wrap the outer example with four backticks instead of three.

Example

````markdown
```javascript
console.log("Hello");
```
````

Using a longer outer fence prevents Markdown from closing the inner code block too early.

Using Tildes Instead of Backticks#

Many Markdown parsers also support tildes (~~~) as an alternative fence.

~~~python
print("Hello, World!")
~~~

This is especially useful when your example already contains multiple backticks.

💡 Pro Tip: Choose one fence style and use it consistently throughout the document. Mixing backticks and tildes can make long documentation harder to maintain.

Most modern Markdown editors support fenced code blocks, but the available features can vary depending on the Markdown renderer.

💡 Pro Tip: If your documentation will be published on multiple platforms, preview the rendered output before publishing. Syntax highlighting and supported languages may differ between renderers.

A few simple habits make Markdown code blocks easier to read and maintain.

• Use fenced code blocks instead of indented blocks whenever possible.
• Specify the programming language to enable syntax highlighting.
• Keep each code block focused on a single concept.
• Use descriptive variable names in examples.
• Keep indentation consistent throughout the block.
• Separate unrelated examples into different code blocks.
• Use inline code for commands, filenames, variables, and short snippets.
• Preview the rendered output before publishing.

💡 Workflow Tip: After writing documentation, preview it in the Markdown Editor to verify formatting before exporting with the Markdown to PDF tool.

Most rendering problems are caused by small formatting errors.