@domternal/extension-code-block-lowlight 0.11.0 → 0.11.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -29
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,42 +3,101 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@domternal/extension-code-block-lowlight)
|
|
4
4
|
[](https://github.com/domternal/domternal/blob/main/LICENSE)
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
Syntax highlighting for the [Domternal](https://domternal.dev) editor's code blocks,
|
|
7
|
+
powered by [lowlight](https://github.com/wooorm/lowlight) (a lightweight highlight.js
|
|
8
|
+
wrapper, 190+ languages). `CodeBlockLowlight` extends the core `CodeBlock` node with
|
|
9
|
+
language auto-detection, Tab/Shift-Tab indentation, and incremental re-highlighting that
|
|
10
|
+
only updates the blocks affected by an edit. It inherits every command, shortcut, toolbar
|
|
11
|
+
item, and input rule from `CodeBlock`, so it is a drop-in replacement. Server-side and
|
|
12
|
+
inline-style highlighting helpers (`generateHighlightedHTML`, `createCodeHighlighter`) are
|
|
13
|
+
included for SSR and email rendering.
|
|
8
14
|
|
|
9
15
|
## Links
|
|
10
16
|
|
|
11
|
-
<u>[Website](https://domternal.dev)</u> • <u>[Documentation](https://domternal.dev/v1/
|
|
12
|
-
<u>[StackBlitz (Angular)](https://stackblitz.com/edit/domternal-angular-full-example)</u> • <u>[StackBlitz (React)](https://stackblitz.com/edit/domternal-react-full-example)</u> • <u>[StackBlitz (Vue)](https://stackblitz.com/edit/domternal-vue-full-example)</u> • <u>[StackBlitz (Vanilla TS)](https://stackblitz.com/edit/domternal-vanilla-full-example)</u>
|
|
17
|
+
<u>[Website](https://domternal.dev)</u> • <u>[Documentation](https://domternal.dev/v1/extensions/code-block-lowlight)</u> • <u>[Live examples](https://domternal.dev/examples)</u>
|
|
13
18
|
|
|
14
|
-
##
|
|
19
|
+
## Install
|
|
15
20
|
|
|
16
|
-
|
|
21
|
+
```bash
|
|
22
|
+
pnpm add @domternal/extension-code-block-lowlight lowlight
|
|
23
|
+
```
|
|
17
24
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- **React components** - composable `Domternal` component, toolbar, bubble menu, floating menu, emoji picker, notion color picker, custom node views (React 18+)
|
|
21
|
-
- **Vue components** - composable `Domternal` component, `useEditor`/`useEditorState` composables, toolbar, bubble menu, floating menu, emoji picker, notion color picker, custom node views (Vue 3.3+)
|
|
22
|
-
- **Vanilla wrapper** - framework-free class-based API for Astro, Svelte, Solid, plain HTML, and Web Components - editor, toolbar, bubble menu, floating menu, emoji picker, notion color picker
|
|
23
|
-
- **Notion-style block UX** - drag-to-reorder, block context menu, slash command, smart paste, keyboard reorder, floating Table of Contents
|
|
24
|
-
- **70+ extensions across 16 packages** - nodes, marks, and behavior extensions
|
|
25
|
-
- **125+ chainable commands** - `editor.chain().focus().toggleBold().run()`
|
|
26
|
-
- **Full table support** - cell merging, column resize, row/column controls, cell toolbar, all free and MIT licensed
|
|
27
|
-
- **Tree-shakeable** - import only what you use, your bundler strips the rest
|
|
28
|
-
- **~44 KB gzipped** (own code), <u>[see Packages](https://domternal.dev/v1/packages)</u> for full bundle breakdown with ProseMirror
|
|
29
|
-
- **TypeScript first** - 100% typed, zero `any`
|
|
30
|
-
- **15,000+ tests** - 4,000+ unit and 11,000+ E2E across 230+ Playwright specs and 4 demo apps
|
|
31
|
-
- **Light and dark theme** - 120+ CSS custom properties for full visual control
|
|
32
|
-
- **Inline styles export** - `getHTML({ styled: true })` produces inline CSS ready for email clients, CMS, and Google Docs
|
|
33
|
-
- **SSR helpers** - `generateHTML`, `generateJSON`, `generateText` for server-side rendering
|
|
25
|
+
`lowlight` is a peer dependency (alongside `@domternal/core` and `@domternal/pm`). Install
|
|
26
|
+
it yourself and pass a configured instance via the required `lowlight` option.
|
|
34
27
|
|
|
35
|
-
##
|
|
28
|
+
## Usage
|
|
36
29
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
30
|
+
```ts
|
|
31
|
+
import { Editor, Document, Paragraph, Text } from '@domternal/core';
|
|
32
|
+
import { CodeBlockLowlight } from '@domternal/extension-code-block-lowlight';
|
|
33
|
+
import { createLowlight, common } from 'lowlight';
|
|
41
34
|
|
|
42
|
-
|
|
35
|
+
const lowlight = createLowlight(common); // ~37 common languages; use `all` for ~190
|
|
43
36
|
|
|
44
|
-
|
|
37
|
+
const editor = new Editor({
|
|
38
|
+
element: document.getElementById('editor')!,
|
|
39
|
+
extensions: [
|
|
40
|
+
Document,
|
|
41
|
+
Paragraph,
|
|
42
|
+
Text,
|
|
43
|
+
CodeBlockLowlight.configure({
|
|
44
|
+
lowlight,
|
|
45
|
+
defaultLanguage: 'javascript',
|
|
46
|
+
autoDetect: true,
|
|
47
|
+
tabIndentation: true,
|
|
48
|
+
tabSize: 2,
|
|
49
|
+
}),
|
|
50
|
+
],
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
// Inherited from CodeBlock
|
|
54
|
+
editor.commands.toggleCodeBlock({ language: 'typescript' });
|
|
55
|
+
|
|
56
|
+
// Languages registered on the lowlight instance.
|
|
57
|
+
// Storage is keyed by the inherited `codeBlock` name, not `codeBlockLowlight`.
|
|
58
|
+
editor.storage.codeBlock.listLanguages();
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
> `CodeBlockLowlight` **replaces** the built-in `CodeBlock`. Do not register both. With
|
|
62
|
+
> `StarterKit`, disable the core code block: `StarterKit.configure({ codeBlock: false })`.
|
|
63
|
+
|
|
64
|
+
## Options
|
|
65
|
+
|
|
66
|
+
| Option | Type | Default | Description |
|
|
67
|
+
|---|---|---|---|
|
|
68
|
+
| `lowlight` | `Lowlight` | `null` (required) | The instance from `createLowlight()`. Throws at init if missing. |
|
|
69
|
+
| `defaultLanguage` | `string \| null` | `null` | Language used when a block has none set. |
|
|
70
|
+
| `autoDetect` | `boolean` | `true` | Detect the language via `highlightAuto()` when none is set. |
|
|
71
|
+
| `tabIndentation` | `boolean` | `true` | Tab inserts spaces inside code blocks; Shift-Tab outdents. |
|
|
72
|
+
| `tabSize` | `number` | `2` | Number of spaces per tab. |
|
|
73
|
+
|
|
74
|
+
## Server-side highlighting
|
|
75
|
+
|
|
76
|
+
`generateHighlightedHTML` renders JSON content to HTML with highlighted code blocks, and
|
|
77
|
+
`createCodeHighlighter` produces a `codeHighlighter` callback for `inlineStyles()` (email,
|
|
78
|
+
CMS, and Google Docs output). These are two independent paths: use whichever fits your
|
|
79
|
+
pipeline. For `generateHighlightedHTML(json, extensions, lowlight)`, `extensions` must be
|
|
80
|
+
the same array you used to build the editor and `json` is its document JSON (e.g.
|
|
81
|
+
`editor.getJSON()`). The example below shows both helpers running over the same `html`:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import {
|
|
85
|
+
generateHighlightedHTML,
|
|
86
|
+
createCodeHighlighter,
|
|
87
|
+
} from '@domternal/extension-code-block-lowlight';
|
|
88
|
+
import { inlineStyles } from '@domternal/core';
|
|
89
|
+
import { createLowlight, common } from 'lowlight';
|
|
90
|
+
|
|
91
|
+
const lowlight = createLowlight(common);
|
|
92
|
+
|
|
93
|
+
const html = generateHighlightedHTML(json, extensions, lowlight);
|
|
94
|
+
|
|
95
|
+
const styled = inlineStyles(html, {
|
|
96
|
+
codeHighlighter: createCodeHighlighter(lowlight),
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Both SSR helpers accept an optional `{ defaultLanguage?, autoDetect? }` as their last
|
|
101
|
+
argument. For SSR, `autoDetect` defaults to `false` (the opposite of the editor
|
|
102
|
+
extension's `true`), so pass `{ autoDetect: true }` if you want detection during
|
|
103
|
+
server rendering.
|
package/package.json
CHANGED