Syntax Highlighting

On this page 34

BunPress provides beautiful syntax highlighting for code blocks powered by ts-syntax-highlighter. This guide covers configuration and customization options.

Basic Usage

Use fenced code blocks with language identifiers:

```typescript
const greeting = 'Hello, World!'
console.log(greeting)
```

Supported Languages

BunPress supports 100+ programming languages including:

JavaScript, TypeScript, JSX, TSX
Python, Ruby, Go, Rust
HTML, CSS, SCSS, Less
JSON, YAML, TOML
Bash, Shell, PowerShell
SQL, GraphQL
Markdown, MDX

Themes

Built-in Themes

// bunpress.config.ts
export default {
  markdown: {
    syntaxHighlightTheme: 'github-dark', // default
  },
}

Available themes:

github-dark (default)
github-light
one-dark-pro
dracula
nord
vitesse-dark
vitesse-light

Dual Themes (Light/Dark)

export default {
  markdown: {
    syntaxHighlightTheme: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
}

Line Numbers

Enable Globally

export default {
  markdown: {
    features: {
      codeBlocks: {
        lineNumbers: true,
      },
    },
  },
}

Per Block

```typescript:line-numbers
const a = 1
const b = 2
const c = 3
```

Starting Line Number

```typescript:line-numbers=10
// This starts at line 10
const value = 'example'
```

Line Highlighting

Highlight Specific Lines

```typescript {2,4-6}
const a = 1
const b = 2  // highlighted
const c = 3
const d = 4  // highlighted
const e = 5  // highlighted
const f = 6  // highlighted
```

Focus Lines

```typescript focus={2-3}
// dimmed
const important = true  // focused
const alsoImportant = true  // focused
// dimmed
```

Diff Highlighting

Show code changes with diff markers:

```typescript
const oldValue = 'old'
const newValue = 'new'
```

Or use standard diff syntax:

```diff

- const oldValue = 'old'
- const newValue = 'new'

```

Error/Warning Markers

Highlight errors and warnings:

```typescript
const valid = true
const error = null
const warning = undefined
```

Word Highlighting

Highlight specific words:

```typescript /greeting/
const greeting = 'Hello'
console.log(greeting)
```

File Names

Display file names above code blocks:

```typescript [src/utils.ts]
export function helper() {
  return true
}
```

Custom Languages

Register Languages

export default {
  markdown: {
    customLanguages: [
      {
        id: 'myLang',
        scopeName: 'source.mylang',
        grammar: require('./mylang.tmLanguage.json'),
      },
    ],
  },
}

Aliases

export default {
  markdown: {
    languageAliases: {
      js: 'javascript',
      ts: 'typescript',
      py: 'python',
    },
  },
}

Transformers

Built-in Transformers

export default {
  markdown: {
    features: {
      codeBlocks: {
        lineNumbers: true,
        lineHighlighting: true,
        focus: true,
        diffs: true,
        errorWarningMarkers: true,
      },
    },
  },
}

Custom Transformers

export default {
  markdown: {
    codeTransformers: [
      {
        name: 'custom-transform',
        pre(node) {
          // Transform the pre element
          this.addClassToHast(node, 'custom-class')
        },
        code(node) {
          // Transform the code element
        },
      },
    ],
  },
}

Inline Code

Inline Highlighting

Use inline code with language:

The `const x = 1`{lang=ts} variable is typed.

Styled Inline Code

export default {
  markdown: {
    inlineCodeStyle: {
      backgroundColor: '#1e1e1e',
      padding: '0.2em 0.4em',
      borderRadius: '3px',
    },
  },
}

Copy Button

Enable Copy Button

export default {
  markdown: {
    features: {
      codeBlocks: {
        copyButton: true,
      },
    },
  },
}

Custom Copy Text

export default {
  markdown: {
    copyButtonText: {
      copy: 'Copy code',
      copied: 'Copied!',
    },
  },
}

Performance

Lazy Loading

export default {
  markdown: {
    syntaxHighlighting: {
      lazy: true, // Load highlighter on demand
    },
  },
}

Preload Languages

export default {
  markdown: {
    syntaxHighlighting: {
      preloadLanguages: ['typescript', 'javascript', 'css'],
    },
  },
}

Styling

Custom CSS

/* Override highlight colors */
.shiki {
  background-color: #1a1a1a !important;
}

.shiki .line.highlighted {
  background-color: rgba(255, 255, 0, 0.1);
}

.shiki .line.diff.add {
  background-color: rgba(0, 255, 0, 0.1);
}

.shiki .line.diff.remove {
  background-color: rgba(255, 0, 0, 0.1);
}

Code Groups - Tabbed code blocks
Markdown Features - All markdown features
Theming - Custom themes