Custom Quill Integration in CMS: Formats, Uploads, Delta

Why the stock Quill editor in a CMS breaks content

The stock Quill editor in a CMS breaks predictably: a content manager pastes text from Word, saves it — and headings disappear from the page, paragraphs merge together, and a table turns into a set of rows.

The cause is not the editor, but the fact that between the input field and the storage there is no layer that brings the markup to a unified form. Quill outputs content in Delta format — a flat list of insert and formatting operations — while the CMS expects HTML. If the conversion is done "by eye," every non-standard case loses formatting on save.

The most costly issue is pasting from Word into the editor. Word brings inline styles, nested <span> tags, invisible characters, and its own classes.

The stock paste handler cuts out some of it and passes some of it through as is — and markup goes into the database that can then not be rendered identically in a browser and in a mobile app.

Tables break into separate paragraphs, lists lose nesting, and links remain with tracking parameters.

A separate category of losses is SEO markup. Heading levels are replaced with bold text, <h2> and <h3> disappear from the structure, and images come in without alt text and with original file names.

A search engine sees a flat page without hierarchy, and the site's content editor turns into a source of manual correction after every publication.

The problems of a custom editor here are not in the interface — they are in the absence of validation on input and normalization on output.

We break down how this is closed: the storage schema, the rules for converting Delta to HTML and back, media upload, and protection against "dirty" pasting.

What a Custom Editor Integration Delivers: Formats and Uploads

Document Structure Instead of "Raw" HTML

The default image insertion in the editor returns an <img> with an absolute address and inline styles — when the domain or CDN changes, half the content goes "blind," and the layout drifts on a different template.

Custom quill formats are described as separate document model nodes, so a heading, callout, or table remains a typed block rather than a set of tags. The result is predictable layout on any template and correct transfer of content between CMS sections.

Media Uploads Without "Heavy" Pages

Image uploads to the editor go through a custom handler: the file is sent to the server, checked by type and size, compressed, and given several sizes for different page blocks.

The editor inserts a ready object with a set of variants rather than the original at a dozen megabytes. The page serves the right size for the specific spot — page load time and weight no longer depend on who uploaded the image and how.

Delta Format as a Single Source

The delta format stores a document as a sequence of operations rather than as ready-made markup. This gives two things: a full edit history with rollback capability and identical output when rendering to web, email, or a mobile app.

Content storage comes down to a single structure — rendering to HTML, plain text, or PDF is assembled on the service side, without manual duplication.

Editor Integration with CMS

Editor integration with CMS is built so that the editor is an input field, while all the logic of formats, uploads, and validation lives in the service. Changing the template or frontend framework doesn't break already saved content: the document structure remains unchanged.

Quill was chosen as the foundation: its document model can be extended without rewriting the core, and the storage format isn't tied to a specific output template.

Stages of implementing a custom editor in a CMS

Implementing an editor into a CMS is not swapping one field for another, but working with the content storage format, media uploads, and access rights. Below is how we handle such a task so that after delivery the editor doesn't have to be rewritten.

1. Editor audit. We look at what's currently in place, in what form the markup is stored (HTML, Delta, a custom format), which fields and templates read it. We note where content loses structure on save and re-open.
2. Schema design. We define what the editor outputs and what it accepts back, how old records are converted, where the boundary lies between the stored and the rendered representation. The schema is agreed upon before code — otherwise migration turns into a rewrite.
3. Format configuration. We assemble the panel for real tasks: headings, lists, tables, code inserts, links. We remove unnecessary buttons — each extra one brings along a sanitization rule for pasting from external sources.
4. Media upload configuration. Images and files go through a custom handler: type and size validation, renaming, binding to the record. We separately test pasting from the clipboard and drag-and-drop — these are the most common sources of "broken" paths.
5. Format testing. We run content through the cycle: creation, saving, re-opening, editing, publishing. We verify that the markup doesn't accumulate junk after several editing cycles.
6. Migrating old records. We convert existing content and verify with a sample: where the structure wasn't restored — we fix the rules, not individual records by hand.
7. Handing over documentation. We provide the format description, the conversion schema, the uploader settings, and instructions for content editors. After that, the client's team maintains the editor on their own.

Each stage ends with a verifiable result: a schema, a working uploader, tested content. Describe your CMS and current editor — we'll get back to you with an estimate and a plan for these steps.

How does the Delta format differ from HTML when storing content?

The Delta format stores a document as a sequence of operations: "insert text," "retain attribute," "delete range." This is not markup but a change log — the editor and the CMS work with the same document structure, so when loading into the quill editor there is no need to parse HTML back into the model.

HTML content storage is structured differently: the database holds ready-made markup, and when opening it the editor parses it with its own parser, losing whatever is not described in its schema.

The difference shows up in operations where precision matters. Delta records the position and length of an insertion, so collaborative editing and undo work predictably: two edits do not conflict because of a different order of tags.

With HTML content storage, such conflicts have to be resolved by comparing trees, and nested lists, tables, and custom blocks often change structure after serialization.

The comparison of formats here is not about "better or worse" but about who is responsible for integrity — the editor or the database.

Delta has a cost. The format is not human-readable: to see the text you need a renderer, and searching through it in the database requires a separate index.

HTML can be served directly into a template, filtered with a sanitizer, and put into a cache — for a simple editorial team this is cheaper to maintain.

Therefore the choice depends on the scenario: if content is edited by several authors simultaneously or precise rollbacks are needed, the document structure in Delta pays off; if publications are infrequent and delivery speed matters, HTML is simpler.

In practice, we more often build a hybrid: Delta as the source of truth for the editor and the CMS, and HTML as a derived layer that is reassembled on save and served to visitors.

This way the editor and the CMS do not diverge in their representation of the document, and the frontend receives ready-made markup without rendering on the fly.

Case study: how we eliminated formatting loss in the editor

The client's editorial team — an online store with a catalog of several thousand product cards — was working with a standard editor build inside the CMS.

When pasting text from Word and Google Docs, lists, tables, and nested headings were lost: the markup "collapsed" into a single paragraph, and saving a large article with a dozen images took up to a minute and sometimes failed with an error.

Content managers double-checked every publication manually, and some materials went back for re-editing after they had already gone live on the site.

What we changed

We traced the chain from input to database write and found two bottlenecks. First, the editor output markup in its own internal format, and conversion to HTML happened server-side "on the fly," which caused some nodes to be lost. Second, images were uploaded synchronously, blocking the interface until the file write completed.

We switched storage to the editor's own canonical markup format: it is saved to the database as is, and HTML is assembled from it deterministically — the same document always produces the same result.

Image uploads were moved to a separate thread with queuing and preview: the author sees the image immediately, while the write happens in the background.

Additionally, we fixed pasting from external sources — markup cleanup now preserves lists, tables, and headings, discarding only junk styles.

Metrics before and after

We should also note the effect on the editorial team: the time to prepare a material was cut roughly in half, because the mandatory markup proofreading disappeared.

Content managers no longer had to keep "safe pasting rules" in mind — the editor itself brings the pasted fragment into the correct form.

We chose Quill as the foundation precisely because of its predictable document model: the markup is described by an operation tree rather than an HTML string, so it can be reliably compared, stored, and restored. That is what delivered the very content integrity that the old build lacked.

Doubts before implementation: compatibility, migration, rollback

The most common technical question is what will happen to the content already accumulated. Quill stores markup not in HTML, but in Delta: a flat list of insert and format operations.

During migration, we convert old materials to Delta and back, running each document through a check for formatting loss — tables, nested lists, and custom blocks are transferred by a separate rule, not "by eye".

The editor's compatibility with the current CMS is checked on a copy of the database before making changes in production.

What if a rollback is needed? The editor configuration and conversion rules are kept in a version control system, so returning to a previous state is switching to a previous build, not manual editing. What about access permissions?

Roles for reading, editing, and publishing are separated at the CMS level: an author sees only their own documents, an editor sees the approval queue, an administrator sees the change history.

After implementation, the team hands over:

• the editor configuration with a description of the toolbar and formatting rules;
• the Delta ↔ HTML conversion scheme with examples of complex documents;
• the roles and access policy tied to groups in the CMS;
• content migration scripts and transfer verification reports;
• the rollback procedure with return points at each stage;
• editor documentation: connection, extension, typical errors.

Describe your task — what content has already been accumulated, which CMS is used, and which roles are needed. We will get back to you with an estimate and an implementation plan.

Custom editor implementation timeline: stages and benchmarks

The timeline depends not on the editor itself, but on how many formats, integrations, and insertion scenarios need to be covered. Below are benchmarks for a typical project: a custom editor based on Quill, embedded in a CMS, with file uploads and content stored in Delta format.

The range across stages is from three to seven weeks per editor. The spread is determined by the number of non-standard scenarios: insertion from tables and documents, collaborative editing, versioning, role-based restrictions. Each such scenario adds a separate branch of checks and noticeably shifts the timeline.

The stages do not proceed in strict sequence. The prototype and storage design often overlap: while schemas are being configured, it is already clear how the content will be stored in the database.

This shortens the overall schedule, but requires that decisions on the storage format be made in the first week, not at the end.

The benchmarks above are for a team that has already worked with Delta format and custom builds. If content is being migrated from an old editor, a migration stage is added: markup analysis, conversion, verification on a sample of pages.