Quill Delta from HTML

This is a package that converts HTML input into Quill Delta format, which is used in the Quill Js package.

This package supports the conversion of a wide range of HTML tags and attributes into their corresponding Delta operations, ensuring that your HTML content is accurately represented in the Quill editor.

Supported tags

1    <!--Text Formatting-->
2        <b>, <strong>: Bold text
3        <i>, <em>: Italic text
4        <u>, <ins>: Underlined text
5        <s>, <del>: Strikethrough text
6        <sup>: Superscript text
7        <sub>: Subscript text
8
9    <!--Headings-->
10        <h1> to <h6>: Headings of various levels
11
12    <!--Lists and nested ones-->
13        <ul>: Unordered lists
14        <ol>: Ordered lists
15        <li>: List items
16        <li data-checked="true">: Check lists
17        <input type="checkbox">: Another alternative to make a check lists
18
19    <!--Links-->
20        <a>: Hyperlinks with support for the href attribute
21
22    <!--Images-->
23        <img>: Images with support for the src, align, and styles
24
25    <!--div-->
26        <div>: HTML tag containers
27
28    <!--Videos -->
29        <video>: Videos with support for the src
30
31    <!--Blockquotes-->
32        <blockquote>: Block quotations
33
34    <!--Code Blocks-->
35        <pre>, <code>: Code blocks
36
37    <!--Text Alignment, inline text align and direction-->
38        <p style="text-align:left|center|right|justify">: Paragraph style alignment
39        <p align="left|center|right|justify">: Paragraph alignment
40        <p dir="rtl">: Paragraph direction
41
42    <!--Text attributes-->
43        <p style="padding: 10px;font-size: 12px;font-family: Times New Roman;color:#ffffff">: Inline attributes
44
45    <!--Custom Blocks-->
46        <pullquote data-author="john">: Custom html

Quick Example

1import { HtmlToDelta } from 'quill-delta-from-html';
2
3const htmlContent: string = '<p>Hello, <b>world</b>!</p>';
4const delta = new HtmlToDelta(<your_custom_blocks>, <YourHtmlToOperationsImpl>, <your_black_nodes_list>).convert(htmlContent);
5
6/*
7   { "insert": "hello, " },
8   { "insert": "world", "attributes": {"bold": true} },
9   { "insert": "!\n" }
10*/

Creating your own CustomHtmlPart

What is a CustomHtmlPart?

CustomHtmlPartis a special class that let us convert custom HTML elements in Operation to Quill Delta.

First you need to define your own CustomHtmlPart

1import { CustomHtmlPart } from 'quill-delta-from-html';
2import { HTMLElement } from 'node-html-parser';
3import Delta, { AttributeMap, Op } from 'quill-delta';
4
5/// Custom block handler for <pullquote> elements.
6class PullquoteBlock extends CustomHtmlPart {
7  matches(element: HTMLElement): boolean {
8    // you can put here the validation that you want
9    // To detect a <p>, you just need to do something like:
10    // element.rawTagName === 'p'
11    return element.rawTagName === 'pullquote';
12  }
13
14  convert(element: HTMLElement, currentAttributes: AttributeMap): Op[] {
15    const delta: Delta = new Delta();
16    const attributes = { ...currentAttributes };
17
18    // Extract custom attributes from the <pullquote> element
19    // The attributes represent the data into a html tag
20    // at this point, <pullquote> should have these attributes
21    //
22    // <pullquote data-author="John Doe" data-style="italic">
23    // These attributes can be optional, so ensure not to use "!" to avoid any null conflict
24    const author = element.attribs['data-author'];
25    const style = element.attribs['data-style'];
26
27    // Apply custom attributes to the Delta operations
28    if (author) {
29      delta.insert(
30        `Pullquote: "${element.children[0].data}" by ${author}`,
31        attributes,
32      );
33    } else {
34      delta.insert(`Pullquote: "${element.children[0].data}"`, attributes);
35    }
36
37    if (style && style.toLowerCase() === 'italic') {
38      attributes['italic'] = true;
39    }
40    return delta;
41  }
42}

After, put your PullquoteBlock to HtmlToDelta using the param customBlocks

1import { HtmlToDelta } from 'quill-delta-from-html';
2
3const htmlText: string = `
4  <html>
5    <body>
6      <p>Regular paragraph before the custom block</p>
7      <pullquote data-author="John Doe" data-style="italic">This is a custom pullquote</pullquote>
8      <p>Regular paragraph after the custom block</p>
9    </body>
10  </html>
11`;
12
13// Registering the custom block
14const customBlocks = [new PullquoteBlock()];
15
16// Initialize HtmlToDelta with the HTML text and custom blocks
17const converter = new HtmlToDelta(customBlocks);
18
19// Convert HTML to Delta operations
20const delta = converter.convert(htmlText);
21
22/*
23This should be resulting delta
24  {"insert": "Regular paragraph before the custom block"},
25  {"insert": "Pullquote: \"This is a custom pullquote\" by John Doe", "attributes": {"italic": true}},
26  {"insert": "\n"},
27  {"insert": "Regular paragraph after the custom block\n"}
28*/

HtmlOperations

The HtmlOperations class is designed to streamline the conversion process from HTML to Delta operations, accommodating a wide range of HTML structures and attributes commonly used in web content.

To utilize HtmlOperations, extend this class and implement the methods necessary to handle specific HTML elements. Each method corresponds to a different HTML tag or element type and converts it into Delta operations suitable for use with Quill JS.

1abstract class HtmlOperations {
2  // customBlocks are passed internally by HtmlToDelta
3  protected customBlocks?: CustomHtmlPart[];
4
5  // You don't need to override this method
6  // as it simply calls the other methods
7  // to detect the type of HTML tag
8  resolveCurrentElement(
9    element: dom.Element,
10    indentLevel?: number,
11  ): Operation[];
12
13  abstract brToOp(element: dom.Element): Operation[];
14  abstract headerToOp(element: dom.Element): Operation[];
15  abstract listToOp(element: dom.Element, indentLevel?: number): Operation[];
16  abstract paragraphToOp(element: dom.Element): Operation[];
17  abstract linkToOp(element: dom.Element): Operation[];
18  abstract spanToOp(element: dom.Element): Operation[];
19  abstract imgToOp(element: dom.Element): Operation[];
20  abstract videoToOp(element: dom.Element): Operation[];
21  abstract codeblockToOp(element: dom.Element): Operation[];
22  abstract blockquoteToOp(element: dom.Element): Operation[];
23}

Passing a custom HtmlOperations implementation

1import { HtmlToDelta } from 'quill-delta-from-html';
2
3const converter = new HtmlToDelta(...your_custom_blocks, <YourHtmlToOperationsImpl>);

Contributions

If you find a bug or want to add a new feature, please open an issue or submit a pull request on the GitHub repository.

This project is licensed under the MIT License - see the LICENSE file for details.