or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-tiptap--extension-code-block-lowlight

Tiptap extension that enhances code blocks with syntax highlighting using lowlight

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@tiptap/extension-code-block-lowlight@3.4.x

To install, run

npx @tessl/cli install tessl/npm-tiptap--extension-code-block-lowlight@3.4.0

Tiptap Code Block Lowlight Extension

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.

Package Information

Package Name: @tiptap/extension-code-block-lowlight
Package Type: npm
Language: TypeScript
Installation: npm install @tiptap/extension-code-block-lowlight

Core Imports

import { CodeBlockLowlight, CodeBlockLowlightOptions } from "@tiptap/extension-code-block-lowlight";

For CommonJS:

const { CodeBlockLowlight } = require("@tiptap/extension-code-block-lowlight");

Default import (recommended):

import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight";

Basic Usage

import { Editor } from "@tiptap/core";
import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight";
import { lowlight } from "lowlight";

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

// Configure the editor with syntax highlighting
const editor = new Editor({
  extensions: [
    CodeBlockLowlight.configure({
      lowlight,
      defaultLanguage: 'javascript',
    }),
  ],
});

Capabilities

Extension Configuration

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

/**
 * Tiptap extension that enhances code blocks with syntax highlighting using lowlight
 */
const CodeBlockLowlight: Extension<CodeBlockLowlightOptions>;

interface CodeBlockLowlightOptions extends CodeBlockOptions {
  /** The lowlight instance for syntax highlighting */
  lowlight: any;
  /** CSS class prefix for language classes (default: 'language-') */
  languageClassPrefix?: string;
  /** Exit code block on triple enter (default: true) */
  exitOnTripleEnter?: boolean;
  /** Exit code block on arrow down (default: true) */
  exitOnArrowDown?: boolean;
  /** Default language for code blocks (default: null) */
  defaultLanguage?: string | null;
  /** Enable tab key for indentation (default: false) */
  enableTabIndentation?: boolean;
  /** Tab size in spaces (default: 4) */
  tabSize?: number;
  /** Additional HTML attributes for code blocks (default: {}) */
  HTMLAttributes?: Record<string, any>;
}

Usage Example:

import { Editor } from "@tiptap/core";
import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight";
import { lowlight } from "lowlight";

// Basic configuration
const editor = new Editor({
  extensions: [
    CodeBlockLowlight.configure({
      lowlight,
    }),
  ],
});

// Advanced configuration
const editor = new Editor({
  extensions: [
    CodeBlockLowlight.configure({
      lowlight,
      defaultLanguage: 'typescript',
      languageClassPrefix: 'hljs-',
      exitOnTripleEnter: true,
      exitOnArrowDown: true,
      enableTabIndentation: true,
      tabSize: 2,
      HTMLAttributes: {
        class: 'my-code-block',
      },
    }),
  ],
});

Commands

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

interface CodeBlockCommands {
  /**
   * Set a code block
   * @param attributes Code block attributes
   * @example editor.commands.setCodeBlock({ language: 'javascript' })
   */
  setCodeBlock: (attributes?: { language: string }) => boolean;
  
  /**
   * Toggle a code block
   * @param attributes Code block attributes
   * @example editor.commands.toggleCodeBlock({ language: 'javascript' })
   */
  toggleCodeBlock: (attributes?: { language: string }) => boolean;
}

Usage Example:

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

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

// Toggle without specifying language (uses defaultLanguage)
editor.commands.toggleCodeBlock();

Keyboard Shortcuts

The extension inherits keyboard shortcuts from the base CodeBlock extension.

interface CodeBlockKeyboardShortcuts {
  /** Toggle code block */
  'Mod-Alt-c': () => boolean;
  /** Remove code block when empty or at start */
  'Backspace': () => boolean;
  /** Handle tab indentation (if enableTabIndentation is true) */
  'Tab': () => boolean;
  /** Handle reverse tab indentation (if enableTabIndentation is true) */
  'Shift-Tab': () => boolean;
  /** Exit code block on triple enter (if exitOnTripleEnter is true) */
  'Enter': () => boolean;
  /** Exit code block on arrow down (if exitOnArrowDown is true) */
  'ArrowDown': () => boolean;
}

Input Rules

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

/** Input rule patterns */
const backtickInputRegex: RegExp; // Matches ```language
const tildeInputRegex: RegExp;    // Matches ~~~language

Usage:

Type ```javascript and press space/enter to create a JavaScript code block
Type ~~~python and press space/enter to create a Python code block
Language is optional - ``` creates a code block with default/no language

Plugin System

The extension includes a ProseMirror plugin for handling syntax highlighting.

/**
 * Creates a ProseMirror plugin for syntax highlighting
 * @param name - The name of the code block node type
 * @param lowlight - The lowlight instance for highlighting
 * @param defaultLanguage - Default language when none is specified
 * @returns ProseMirror Plugin instance
 */
function LowlightPlugin(options: {
  name: string;
  lowlight: any;
  defaultLanguage: string | null | undefined;
}): Plugin<any>;

Types

import type { CodeBlockOptions } from '@tiptap/extension-code-block';
import type { Plugin } from '@tiptap/pm/state';
import type { Extension } from '@tiptap/core';

/** Configuration options for the CodeBlockLowlight extension */
interface CodeBlockLowlightOptions extends CodeBlockOptions {
  /** The lowlight instance for syntax highlighting */
  lowlight: any;
  /** CSS class prefix for language classes (default: 'language-') */
  languageClassPrefix?: string;
  /** Exit code block on triple enter (default: true) */
  exitOnTripleEnter?: boolean;
  /** Exit code block on arrow down (default: true) */
  exitOnArrowDown?: boolean;
  /** Default language for code blocks (default: null) */
  defaultLanguage?: string | null;
  /** Enable tab key for indentation (default: false) */
  enableTabIndentation?: boolean;
  /** Tab size in spaces (default: 4) */
  tabSize?: number;
  /** Additional HTML attributes for code blocks (default: {}) */
  HTMLAttributes?: Record<string, any>;
}

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

/** Plugin configuration options */
interface LowlightPluginOptions {
  name: string;
  lowlight: any;
  defaultLanguage: string | null | undefined;
}

Dependencies

The extension requires the following peer dependencies:

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

Error Handling

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

// Throws Error if lowlight instance is invalid
throw Error('You should provide an instance of lowlight to use the code-block-lowlight extension');

The required lowlight APIs are:

highlight - Highlight code with a specific language
highlightAuto - Auto-detect and highlight code
listLanguages - List available languages