Markdown Code Blocks: Fences & Syntax Highlighting

```typescript
interface Note {
  id: string;
  content: string;
}
```

Multi-line code blocks are fundamental for software engineers, data scientists, DevOps practitioners, and technical authors who write tutorials, document APIs, record configuration files, or archive shell scripts.

In Markdown, multi-line code blocks preserve exact indentation, whitespace, and formatting without interpreting any Markdown or HTML syntax.

CommonMark defines two methods for creating code blocks: modern fenced code blocks (recommended) and legacy indented code blocks.

Fenced code blocks (Recommended)

Fenced code blocks are created by enclosing a block of text between lines containing three or more backticks (```) or tildes (~~~):

```
// Plain text code block without language highlighting
function greet() {
  console.log("Hello, world!");
}
```

Fenced code blocks compile to the HTML <pre><code>...</code></pre> structure.

Syntax highlighting with language identifiers

To enable color syntax highlighting, append a language identifier (info string) directly after the opening fence:

```typescript
interface VaultConfig {
  vaultPath: string;
  autoSaveInterval: number;
  enableVAD: boolean;
}

export function initializeVault(config: VaultConfig): void {
  console.log(`Mounting vault at: ${config.vaultPath}`);
}
```

Supported language identifiers

Most modern Markdown renderers, including Oyma, support hundreds of language identifiers:

Escaping code blocks inside code blocks

If you are writing a Markdown tutorial that explains how to write fenced code blocks, you need a way to wrap three backticks inside an outer block.

In CommonMark, you achieve this by using more backticks on the outer fence than on the inner fence:

````markdown
```python
def calculate_metrics(values):
    return sum(values) / len(values)
```
````

Because the outer fence has four backticks, the inner block with three backticks is treated as raw text content rather than closing the block.

Alternatively, you can use triple tildes (~~~) as the outer fence:

~~~markdown
```bash
echo "Hello from nested backticks"

```

## Legacy 4-space indented code blocks

Before fenced code blocks were standardized, early Markdown relied on four-space indentation:

```markdown
    // Indented code block
    SELECT * FROM notes WHERE title LIKE '%sprint%';
```

Every line indented by at least four spaces (or one tab) following a blank line is treated as code.

### Why indented code blocks are discouraged

1. **No language highlighting:** Indented blocks cannot specify a language tag.
2. **Accidental indentation bugs:** Accidentally indenting regular text or lists can convert paragraphs into code blocks unexpectedly.
3. **Refactoring friction:** Indenting and outdenting 50 lines of code requires tedious whitespace manipulation.

Modern best practice is to always use fenced code blocks with backticks.

## Advanced code block types in Oyma

In Oyma, code blocks also power interactive visual diagrams and mathematical formulas:
- ```` ```mermaid ````: Renders dynamic interactive flowcharts, architecture diagrams, and sequence charts directly in your note.
- ```` ```math ```` or `$$...$$`: Renders LaTeX / KaTeX mathematical equations.

## Writing code blocks in Oyma

In Oyma on macOS:
- Type ```` ```typescript ```` and press Return to instantly spawn a syntax-highlighted code block.
- Enjoy a dedicated monospace font stack, subtle background container, and automatic copy-to-clipboard button.
- Your code blocks remain 100% standard CommonMark on your Mac's filesystem.

Frequently asked questions

What is the difference between fenced code blocks and indented code blocks?

Fenced code blocks use triple backticks (` ``` `) or triple tildes (`~~~`) to enclose multi-line code and support language identifiers for syntax highlighting. Indented code blocks require four leading spaces on every line and do not support language syntax highlighting tags.

How do I specify a programming language for syntax highlighting?

Append the language identifier immediately after the opening backticks without spaces: ` ```typescript `, ` ```python `, ` ```bash `, ` ```json `.

Can I use triple tildes (~~~) instead of backticks for code blocks?

Yes. CommonMark standardizes triple tildes (`~~~`) as an equivalent fenced code delimiter. Tildes are particularly useful when you need to embed a fenced backtick code block inside another code block.

How does Oyma render code blocks in notes?

Oyma formats code blocks with full syntax highlighting, line numbering, monospace typography, and a native one-click copy button, preserving raw plain text on disk.