@domternal/extension-code-block-lowlight

Syntax highlighting for the Domternal editor's code blocks, powered by lowlight (a lightweight highlight.js wrapper, 190+ languages). CodeBlockLowlight extends the core CodeBlock node with language auto-detection, Tab/Shift-Tab indentation, and incremental re-highlighting that only updates the blocks affected by an edit. It inherits every command, shortcut, toolbar item, and input rule from CodeBlock, so it is a drop-in replacement. Server-side and inline-style highlighting helpers (generateHighlightedHTML, createCodeHighlighter) are included for SSR and email rendering.

Links

Website    •    Documentation    •    Live examples

Install

pnpm add @domternal/extension-code-block-lowlight lowlight

lowlight is a peer dependency (alongside @domternal/core and @domternal/pm). Install it yourself and pass a configured instance via the required lowlight option.

Usage

import { Editor, Document, Paragraph, Text } from '@domternal/core';
import { CodeBlockLowlight } from '@domternal/extension-code-block-lowlight';
import { createLowlight, common } from 'lowlight';

const lowlight = createLowlight(common); // ~37 common languages; use `all` for ~190

const editor = new Editor({
  element: document.getElementById('editor')!,
  extensions: [
    Document,
    Paragraph,
    Text,
    CodeBlockLowlight.configure({
      lowlight,
      defaultLanguage: 'javascript',
      autoDetect: true,
      tabIndentation: true,
      tabSize: 2,
    }),
  ],
});

// Inherited from CodeBlock
editor.commands.toggleCodeBlock({ language: 'typescript' });

// Languages registered on the lowlight instance.
// Storage is keyed by the inherited `codeBlock` name, not `codeBlockLowlight`.
editor.storage.codeBlock.listLanguages();

CodeBlockLowlight replaces the built-in CodeBlock. Do not register both. With StarterKit, disable the core code block: StarterKit.configure({ codeBlock: false }).

Options

| Option | Type | Default | Description | |---|---|---|---| | lowlight | Lowlight | null (required) | The instance from createLowlight(). Throws at init if missing. | | defaultLanguage | string \| null | null | Language used when a block has none set. | | autoDetect | boolean | true | Detect the language via highlightAuto() when none is set. | | tabIndentation | boolean | true | Tab inserts spaces inside code blocks; Shift-Tab outdents. | | tabSize | number | 2 | Number of spaces per tab. |

Server-side highlighting

generateHighlightedHTML renders JSON content to HTML with highlighted code blocks, and createCodeHighlighter produces a codeHighlighter callback for inlineStyles() (email, CMS, and Google Docs output). These are two independent paths: use whichever fits your pipeline. For generateHighlightedHTML(json, extensions, lowlight), extensions must be the same array you used to build the editor and json is its document JSON (e.g. editor.getJSON()). The example below shows both helpers running over the same html:

import {
  generateHighlightedHTML,
  createCodeHighlighter,
} from '@domternal/extension-code-block-lowlight';
import { inlineStyles } from '@domternal/core';
import { createLowlight, common } from 'lowlight';

const lowlight = createLowlight(common);

const html = generateHighlightedHTML(json, extensions, lowlight);

const styled = inlineStyles(html, {
  codeHighlighter: createCodeHighlighter(lowlight),
});

Both SSR helpers accept an optional { defaultLanguage?, autoDetect? } as their last argument. For SSR, autoDetect defaults to false (the opposite of the editor extension's true), so pass { autoDetect: true } if you want detection during server rendering.