Markdown Code Blocks: Languages, Highlighting, and Tips

Code blocks are the backbone of technical documentation. Done right, they make your content instantly credible and easy to follow.

Fenced vs. Indented

Always use fenced — it supports language identifiers for syntax highlighting:

markdown
```javascript
const hello = "world";

Indented blocks (4 spaces) are legacy — avoid them.

## Language Identifiers

### Web
`html`, `css`, `javascript`/`js`, `typescript`/`ts`, `jsx`, `tsx`

### Backend
`python`/`py`, `ruby`/`rb`, `go`, `rust`, `java`, `kotlin`, `csharp`/`cs`, `php`

### Data & Config
`json`, `yaml`/`yml`, `toml`, `xml`, `sql`

### Shell
`bash`, `sh`, `zsh`, `powershell`

### Special
`diff` (shows + / - highlighting), `markdown`/`md`, `text` (no highlighting)

## Diff Blocks

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

Lines with - highlight red, + highlight green.

Inline Code

Use backticks for single values, function names, file paths:

markdown
Call `authenticate()` before making requests.
The config lives in `~/.config/myapp/settings.json`.
Set `NODE_ENV=production` before deploying.

Use inline code for: function names, variables, file names/paths, CLI commands, env variables, HTTP methods, status codes

Don't use for: technology names (React, Node.js), general emphasis

Writing Good Examples

Use Realistic Values

typescript
// Bad
const user = getUser("user_id");

// Good
const user = await getUser("usr_8f3kA9xm");

Show Expected Output

bash
npm run build

text
✓ Compiled successfully
✓ 24 pages generated
✓ Build complete in 3.2s

Comment the Non-Obvious

bash
# Decode a base64-encoded Kubernetes secret
echo "c2VjcmV0" | base64 --decode

Common Mistakes

Missing language identifier — always specify. An unspecified block renders as plain text.

Nesting backticks — if your code contains backticks, use more fences:

markdown

Code with backticks inside

Real credentials in examples — never put API keys or passwords. Use YOUR_API_KEY placeholders.

Quick Reference

Preview your code blocks live in MarkGenie — syntax highlighting renders in real time.