0
# Tiptap Code Block Lowlight Extension
1

2
The @tiptap/extension-code-block-lowlight package provides syntax highlighting capabilities for code blocks in Tiptap rich text editors using the lowlight library (built on highlight.js). It extends the base CodeBlock extension from @tiptap/extension-code-block to automatically detect and highlight code syntax within code blocks.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/extension-code-block-lowlight
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-code-block-lowlight`
10

11
## Core Imports
12

13
```typescript
14
import { CodeBlockLowlight, CodeBlockLowlightOptions } from "@tiptap/extension-code-block-lowlight";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { CodeBlockLowlight } = require("@tiptap/extension-code-block-lowlight");
21
```
22

23
Default import (recommended):
24

25
```typescript
26
import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Editor } from "@tiptap/core";
33
import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight";
34
import { lowlight } from "lowlight";
35

36
// Register languages you want to use
37
import javascript from "highlight.js/lib/languages/javascript";
38
import typescript from "highlight.js/lib/languages/typescript";
39
lowlight.register({ javascript, typescript });
40

41
// Configure the editor with syntax highlighting
42
const editor = new Editor({
43
  extensions: [
44
    CodeBlockLowlight.configure({
45
      lowlight,
46
      defaultLanguage: 'javascript',
47
    }),
48
  ],
49
});
50
```
51

52
## Capabilities
53

54
### Extension Configuration
55

56
The main extension class that provides syntax highlighting for code blocks.
57

58
```typescript { .api }
59
/**
60
 * Tiptap extension that enhances code blocks with syntax highlighting using lowlight
61
 */
62
const CodeBlockLowlight: Extension<CodeBlockLowlightOptions>;
63

64
interface CodeBlockLowlightOptions extends CodeBlockOptions {
65
  /** The lowlight instance for syntax highlighting */
66
  lowlight: any;
67
  /** CSS class prefix for language classes (default: 'language-') */
68
  languageClassPrefix?: string;
69
  /** Exit code block on triple enter (default: true) */
70
  exitOnTripleEnter?: boolean;
71
  /** Exit code block on arrow down (default: true) */
72
  exitOnArrowDown?: boolean;
73
  /** Default language for code blocks (default: null) */
74
  defaultLanguage?: string | null;
75
  /** Enable tab key for indentation (default: false) */
76
  enableTabIndentation?: boolean;
77
  /** Tab size in spaces (default: 4) */
78
  tabSize?: number;
79
  /** Additional HTML attributes for code blocks (default: {}) */
80
  HTMLAttributes?: Record<string, any>;
81
}
82
```
83

84
**Usage Example:**
85

86
```typescript
87
import { Editor } from "@tiptap/core";
88
import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight";
89
import { lowlight } from "lowlight";
90

91
// Basic configuration
92
const editor = new Editor({
93
  extensions: [
94
    CodeBlockLowlight.configure({
95
      lowlight,
96
    }),
97
  ],
98
});
99

100
// Advanced configuration
101
const editor = new Editor({
102
  extensions: [
103
    CodeBlockLowlight.configure({
104
      lowlight,
105
      defaultLanguage: 'typescript',
106
      languageClassPrefix: 'hljs-',
107
      exitOnTripleEnter: true,
108
      exitOnArrowDown: true,
109
      enableTabIndentation: true,
110
      tabSize: 2,
111
      HTMLAttributes: {
112
        class: 'my-code-block',
113
      },
114
    }),
115
  ],
116
});
117
```
118

119
### Commands
120

121
The extension inherits commands from the base CodeBlock extension for programmatically creating and toggling code blocks.
122

123
```typescript { .api }
124
interface CodeBlockCommands {
125
  /**
126
   * Set a code block
127
   * @param attributes Code block attributes
128
   * @example editor.commands.setCodeBlock({ language: 'javascript' })
129
   */
130
  setCodeBlock: (attributes?: { language: string }) => boolean;
131
  
132
  /**
133
   * Toggle a code block
134
   * @param attributes Code block attributes
135
   * @example editor.commands.toggleCodeBlock({ language: 'javascript' })
136
   */
137
  toggleCodeBlock: (attributes?: { language: string }) => boolean;
138
}
139
```
140

141
**Usage Example:**
142

143
```typescript
144
// Set a code block with specific language
145
editor.commands.setCodeBlock({ language: 'typescript' });
146

147
// Toggle code block (paragraph ↔ code block)
148
editor.commands.toggleCodeBlock({ language: 'javascript' });
149

150
// Toggle without specifying language (uses defaultLanguage)
151
editor.commands.toggleCodeBlock();
152
```
153

154
### Keyboard Shortcuts
155

156
The extension inherits keyboard shortcuts from the base CodeBlock extension.
157

158
```typescript { .api }
159
interface CodeBlockKeyboardShortcuts {
160
  /** Toggle code block */
161
  'Mod-Alt-c': () => boolean;
162
  /** Remove code block when empty or at start */
163
  'Backspace': () => boolean;
164
  /** Handle tab indentation (if enableTabIndentation is true) */
165
  'Tab': () => boolean;
166
  /** Handle reverse tab indentation (if enableTabIndentation is true) */
167
  'Shift-Tab': () => boolean;
168
  /** Exit code block on triple enter (if exitOnTripleEnter is true) */
169
  'Enter': () => boolean;
170
  /** Exit code block on arrow down (if exitOnArrowDown is true) */
171
  'ArrowDown': () => boolean;
172
}
173
```
174

175
### Input Rules
176

177
The extension inherits input rules from the base CodeBlock extension for creating code blocks with markdown syntax.
178

179
```typescript { .api }
180
/** Input rule patterns */
181
const backtickInputRegex: RegExp; // Matches ```language
182
const tildeInputRegex: RegExp;    // Matches ~~~language
183
```
184

185
**Usage:**
186
- Type ` ```javascript ` and press space/enter to create a JavaScript code block
187
- Type ` ~~~python ` and press space/enter to create a Python code block
188
- Language is optional - ` ``` ` creates a code block with default/no language
189

190
### Plugin System
191

192
The extension includes a ProseMirror plugin for handling syntax highlighting.
193

194
```typescript { .api }
195
/**
196
 * Creates a ProseMirror plugin for syntax highlighting
197
 * @param name - The name of the code block node type
198
 * @param lowlight - The lowlight instance for highlighting
199
 * @param defaultLanguage - Default language when none is specified
200
 * @returns ProseMirror Plugin instance
201
 */
202
function LowlightPlugin(options: {
203
  name: string;
204
  lowlight: any;
205
  defaultLanguage: string | null | undefined;
206
}): Plugin<any>;
207
```
208

209

210
## Types
211

212
```typescript { .api }
213
import type { CodeBlockOptions } from '@tiptap/extension-code-block';
214
import type { Plugin } from '@tiptap/pm/state';
215
import type { Extension } from '@tiptap/core';
216

217
/** Configuration options for the CodeBlockLowlight extension */
218
interface CodeBlockLowlightOptions extends CodeBlockOptions {
219
  /** The lowlight instance for syntax highlighting */
220
  lowlight: any;
221
  /** CSS class prefix for language classes (default: 'language-') */
222
  languageClassPrefix?: string;
223
  /** Exit code block on triple enter (default: true) */
224
  exitOnTripleEnter?: boolean;
225
  /** Exit code block on arrow down (default: true) */
226
  exitOnArrowDown?: boolean;
227
  /** Default language for code blocks (default: null) */
228
  defaultLanguage?: string | null;
229
  /** Enable tab key for indentation (default: false) */
230
  enableTabIndentation?: boolean;
231
  /** Tab size in spaces (default: 4) */
232
  tabSize?: number;
233
  /** Additional HTML attributes for code blocks (default: {}) */
234
  HTMLAttributes?: Record<string, any>;
235
}
236

237
/** The main extension instance */
238
declare const CodeBlockLowlight: Extension<CodeBlockLowlightOptions>;
239

240
/** Plugin configuration options */
241
interface LowlightPluginOptions {
242
  name: string;
243
  lowlight: any;
244
  defaultLanguage: string | null | undefined;
245
}
246
```
247

248
## Dependencies
249

250
The extension requires the following peer dependencies:
251

252
- `@tiptap/core` - Core Tiptap functionality
253
- `@tiptap/extension-code-block` - Base code block extension
254
- `@tiptap/pm` - ProseMirror packages
255
- `lowlight` (^2 || ^3) - Syntax highlighting library
256
- `highlight.js` (^11) - Code highlighting engine
257

258
## Error Handling
259

260
The LowlightPlugin function validates the lowlight instance and throws an error if required APIs are missing:
261

262
```typescript
263
// Throws Error if lowlight instance is invalid
264
throw Error('You should provide an instance of lowlight to use the code-block-lowlight extension');
265
```
266

267
The required lowlight APIs are:
268
- `highlight` - Highlight code with a specific language
269
- `highlightAuto` - Auto-detect and highlight code
270
- `listLanguages` - List available languages