Markdown Code Blocks: Non-Coder Guide

Why non-coders need this

You do not have to write code to need code blocks. Ever emailed someone a command like ipconfig /flushdns and had your email client "helpfully" capitalize the word or turn the slash into a curly one? That is the problem code blocks fix. Code formatting tells every renderer — email client, chat app, browser, AI tool — to leave this exactly as typed. No auto-correct, no smart quotes, no hidden reformatting.

This applies to file paths, Wi-Fi passwords, database identifiers, API keys, config values, command-line snippets, and any bit of text where a single wrong character means nothing works. If you send someone C:\Users\jchen\Documents without code formatting, some apps will eat the backslashes. Inside a code block, those characters survive intact. For the full list of syntax, see the syntax reference.

Inline code: single backticks

For a word, a short phrase, or a single command, wrap it in single backticks. The backtick is the character on the same key as the tilde (~), usually top-left on a US keyboard.

Run `npm install` in the project folder.
The config lives in `/etc/nginx/nginx.conf`.
Update the `DATABASE_URL` environment variable.
Your login is `jchen@acme.com`.

Inline code renders in a monospace font, usually with a subtle background. It is the single most common formatting move in technical documentation. If you are writing anything where precision matters — SKUs, product codes, email addresses, phone numbers with extensions, IP addresses — code formatting signals "copy this character-for-character".

Backticks inside inline code

To include a literal backtick inside an inline code span, wrap the whole thing in two backticks (or more) instead of one. The renderer matches the outer fence.

Use ``git log --oneline ``` for a compact history.

Fenced code blocks: triple backticks

For anything longer than a single line — a whole command sequence, a config file, a block of JSON, a SQL query — use a fenced code block. Three backticks on a line by themselves open the block, and three more close it.

To get set up, run these three commands:

```
git clone https://github.com/acme/dashboard.git
cd dashboard
npm install
```

That's it.

git clone https://github.com/acme/dashboard.git
cd dashboard
npm install

Everything between the fences is treated as literal. No Markdown formatting is applied inside. Asterisks stay as asterisks. Pipes stay as pipes. Line breaks stay exactly where you put them.

Language hints for syntax highlighting

Add a language name right after the opening three backticks and most renderers will color the code. This is a visual nicety for humans and a structural hint for AI tools — it tells the model which language you are about to show it.

```python
def calculate_tip(bill, percent=18):
    return bill * (percent / 100)

print(calculate_tip(47.50))
```

def calculate_tip(bill, percent=18):
    return bill * (percent / 100)

print(calculate_tip(47.50))

The common language hints, even if you do not write code:

• bash or sh — terminal commands
• json — JSON data, API responses, config files
• yaml — YAML config files (docker-compose, GitHub Actions)
• sql — database queries
• html, css, javascript — web content
• python, ruby, go, java, rust — programming languages
• diff — showing changes between two versions
• text or plain — no highlighting, just monospace

Real example: quoting an email signature

A common non-code use for fenced blocks — sharing a multi-line string where spacing matters:

Here's the standard email footer. Copy this exactly:

```text
Jane Chen
Senior Product Manager | Acme Corp
jchen@acme.com · +1 (415) 555-0192
acme.com · @acme
```

Jane Chen
Senior Product Manager | Acme Corp
jchen@acme.com · +1 (415) 555-0192
acme.com · @acme

Real example: a JSON API response

If you are pasting an API response into a bug report or a question for ChatGPT, wrap it in a JSON fenced block. The model sees the structure immediately instead of treating it as prose.

The API returns this on a successful lookup:

```json
{
  "user_id": "u_4821",
  "email": "jchen@acme.com",
  "plan": "pro",
  "seats": 12,
  "trial_ends_at": null
}
```

{
  "user_id": "u_4821",
  "email": "jchen@acme.com",
  "plan": "pro",
  "seats": 12,
  "trial_ends_at": null
}

Real example: a YAML config

Drop this into `.github/workflows/ci.yml`:

```yaml
name: CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test
```

name: CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

How syntax highlighting varies by platform

Not every renderer highlights the same way, and some do not highlight at all. Here is the rough landscape in 2026:

• GitHub, GitLab, Bitbucket. Excellent highlighting, hundreds of languages supported. The gold standard.
• ChatGPT, Claude, Gemini. Clean highlighting for the common languages. Unfamiliar ones fall back to plain monospace.
• Slack, Discord. Basic highlighting for a handful of languages. Some language hints are silently ignored.
• Notion. Good highlighting once you pick the language from a dropdown; the text-level hint is sometimes overridden.
• Obsidian. Full highlighting via plugins. Works out of the box for common languages.
• VS Code preview. Highlights whatever your installed language extensions support — usually everything.

The point: do not depend on colors to communicate meaning. Colors are a bonus. The monospace font and preserved spacing — the things that actually matter — work everywhere.

The four-space code block (legacy)

Before fenced blocks, you could create a code block by indenting every line four spaces. It still works in every renderer, but it has two downsides: no language hint (so no syntax highlighting), and it is easy to trigger by accident when you indent a paragraph for other reasons. Fenced blocks are better in every way. Use them.

Normal paragraph.

    This is a code block — indented four spaces.
    Second line of the same block.

Back to normal.

This is a code block — indented four spaces.
Second line of the same block.

Code inside lists and tables

Inline code works inside list items and table cells. Fenced code blocks inside list items work in most modern renderers (GitHub, Obsidian, Notion) — you need to indent the fence to match the list level.

1. Open the terminal
2. Navigate to your project:
   ```bash
   cd ~/Documents/my-project
   ```
3. Start the server with `npm run dev`

When not to use a code block

A code block is the wrong choice for: multi-paragraph explanations that happen to mention code, tables of data (use a Markdown table instead), and quotes from books or articles (use a blockquote). Code blocks visually separate content from the surrounding prose — use them when that separation is the right signal, and skip them when the content is just prose that mentions a technical term.

Try it

The free Markdown editor renders fenced blocks live, including language-specific coloring — handy for checking that your language hint is working. If you have an existing technical document you want to convert, the HTML to Markdown converter preserves inline code and code blocks cleanly. For context on how code blocks fit alongside the rest of the syntax, jump back to the syntax reference. If you want the deeper case for Markdown as a format, read why Markdown works best for AI.