Complete Guide to Markdown Code Blocks - Syntax, Examples & Best Practices

Markdown code blocks are essential for displaying code snippets in documentation, README files, and technical writing. This comprehensive guide covers everything you need to know about markdown code formatting.

What are Markdown Code Blocks?

Markdown code blocks allow you to display code with proper formatting and syntax highlighting. They preserve spacing, indentation, and special characters while making your code easy to read.

Inline Code

For short code snippets within text, use single backticks:


```
Use `console.log()` to print output in JavaScript.
```

Result: 

Use `console.log()` to print output in JavaScript.

Fenced Code Blocks

For multi-line code, use triple backticks (```) or triple tildes (~~~):

Basic Syntax

```
function greet(name) {
    return "Hello, " + name + "!";
}
```

With Language Specification

```javascript
function greet(name) {
    return "Hello, " + name + "!";
}
```

Popular Language Identifiers

Common language identifiers for syntax highlighting:

  • javascript or js - JavaScript
  • python or py - Python
  • java - Java
  • cpp or c++ - C++
  • html - HTML
  • css - CSS
  • json - JSON
  • xml - XML
  • bash or shell - Shell scripts
  • sql - SQL
  • php - PHP
  • ruby - Ruby
  • go - Go
  • rust - Rust
  • typescript or ts - TypeScript

Advanced Examples

JavaScript Example

```javascript
// Function to calculate factorial
function factorial(n) {
    if (n <= 1) return 1;
    return n * factorial(n - 1);
}

console.log(factorial(5)); // Output: 120
```

Python Example

```python
# List comprehension example
numbers = [1, 2, 3, 4, 5]
squares = [x**2 for x in numbers]
print(squares)  # Output: [1, 4, 9, 16, 25]
```

HTML Example

```html
<!DOCTYPE html>
<html>
<head>
    <title>Sample Page</title>
</head>
<body>
    <h1>Welcome to My Website</h1>
    <p>This is a paragraph.</p>
</body>
</html>
```

Best Practices

1. Always Specify Language

Always include the language identifier for better syntax highlighting:

Good:

```javascript
const message = "Hello World";
```

Avoid:

```
const message = "Hello World";
```

2. Keep Code Readable

  • Use proper indentation
  • Include comments when necessary
  • Break long lines appropriately

3. Context Matters

Provide context around your code blocks:


```javascript
// This function validates email addresses
function isValidEmail(email) {
    const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return regex.test(email);
}
```

Alternative Syntax

Indented Code Blocks

You can also create code blocks by indenting lines with 4 spaces or 1 tab:

    function example() {
        return "This is indented code";
    }

Tilde Fences

Use tildes instead of backticks:


~~~javascript
const alternative = "Using tildes";
~~~

Escaping Backticks

To display backticks within code blocks, use more backticks for the fence:


````
```
This code block contains backticks
```
````

Common Issues and Solutions

Issue 1: Code Not Highlighting

Problem: Code appears without syntax highlightingSolution: Check the language identifier spelling and ensure it's supported

Issue 2: Backticks Not Working

Problem: Backticks appear as text instead of creating code blocksSolution: Ensure you're using three backticks and they're on separate lines

Issue 3: Special Characters

Problem: Special characters not displaying correctlySolution: Code blocks automatically escape special characters, but ensure proper encoding

Platform-Specific Notes

GitHub

  • Supports extensive language highlighting
  • Renders code blocks in README files
  • Supports diff highlighting with diff language

GitLab

  • Similar to GitHub with additional features
  • Supports mermaid diagrams in code blocks

Discord

  • Limited language support
  • Single-line code with single backticks
  • Multi-line code with triple backticks

Code blocks might seem basic, but they make a huge difference in how readable your documentation becomes. The language identifier is probably the most important part - it turns plain text into properly highlighted, professional-looking code.

Most of the time you'll stick with fenced blocks using backticks, but it's good to know about the alternatives when you need them.