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

Tiptap extension that enhances code blocks with syntax highlighting using lowlight

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Tiptap Code Block Lowlight Extension

Name: tessl/npm-tiptap--extension-code-block-lowlight
Author: tessl

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

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