Skip to main content

Creating Markdown Files with Code Blocks

tip

Well-formatted code blocks in markdown make your documentation more readable and maintainable.

Basic Code Blocks​

Inline Code​

Use single backticks for inline code:

  • Single word: variable
  • Multiple words: function parameter
  • With symbols: npm install package-name

Fenced Code Blocks​

Use triple backticks for multi-line code:

This is a basic code block
No syntax highlighting

Language-specific Highlighting​

Add the language name after the opening backticks:

const greeting = 'Hello, World!';
console.log(greeting);
def greet(name):
    print(f"Hello, {name}!")

Advanced Formatting​

Line Numbers​

Some markdown processors support line numbers:

// This line is highlighted
const x = 1;
// These lines are highlighted
// As well
const y = 2;

Title Bars​

Add titles to your code blocks:

app.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

Diff Blocks​

Show code changes with diff syntax:

- const oldCode = 'to be removed';
+ const newCode = 'to be added';
  const unchanged = 'stays the same';

MDX Features​

Interactive Code Blocks​

// JavaScript example
function add(a, b) {
  return a + b;
}

Live Code Examples​

function Button() {
  return (
    <button onClick={() => alert('Clicked!')}>
      Click me
    </button>
  );
}

Common Languages​

Web Development​

index.html
<!DOCTYPE html>
<html>
<head>
    <title>Example</title>
</head>
<body>
    <h1>Hello World</h1>
</body>
</html>
styles.css
body {
    font-family: Arial, sans-serif;
    margin: 0;
    padding: 20px;
}
app.ts
interface User {
    name: string;
    age: number;
}

const user: User = {
    name: "John",
    age: 30
};

Backend Development​

Main.java
public class Main {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
query.sql
SELECT users.name, orders.order_date
FROM users
JOIN orders ON users.id = orders.user_id
WHERE orders.status = 'completed';

Best Practices​

1. Consistent Formatting​

✅ Do:

# Title

## Section

\```javascript
// Code here
\```

❌ Don't:

#Title
##Section
\```javascript
//Code here
\```

2. Clear Language Specification​

✅ Do:

\```python
def example():
    pass
\```

❌ Don't:

\```
def example():
    pass
\```

3. Proper Indentation​

✅ Do:

- List item
  \```javascript
  const x = 1;
  \```

❌ Don't:

- List item
\```javascript
const x = 1;
\```

Special Cases​

Shell Commands​

For command line instructions:

# Command with output
$ npm install package
Installing package...
Done!

Environment Variables​

.env
API_KEY=your_api_key_here
DATABASE_URL=postgres://user:pass@localhost:5432/db

Configuration Files​

package.json
{
  "name": "project",
  "version": "1.0.0",
  "scripts": {
    "start": "node index.js"
  }
}

Troubleshooting​

Common Issues​

  1. Backticks Inside Code Blocks

    \`\`\`
    Use \` for inline code
    \`\`\`

  2. Line Breaks

    This needs two spaces  
    to create a line break

  3. Escaping Characters

    \* Not a list item
    \` Not inline code

Editor Integration​

Cursor Shortcuts​

ActionShortcut
Code BlockCtrl + Shift + K
Inline CodeCtrl + `
PreviewCtrl + Shift + V

Extensions​

Recommended markdown extensions:

  • Markdown All in One
  • markdownlint
  • Markdown Preview Enhanced
tip

Use the Cursor markdown preview feature to check your formatting in real-time!