Чому штатний Quill-редактор у CMS ламає контент
Штатний Quill-редактор у CMS ламається передбачувано: контент-менеджер вставляє текст із Word, зберігає — і на сторінці зникають заголовки, злипаються абзаци, а таблиця перетворюється на набір рядків.
Причина не в редакторі, а в тому, що між полем введення та сховищем немає шару, який приводить розмітку до єдиного вигляду. Quill віддає вміст у форматі Delta — плоскому списку операцій вставлення та форматування, — а CMS чекає HTML.
Якщо перетворення роблять «на око», кожен нестандартний випадок втрачає форматування при збереженні.
Найдорожче обходиться вставлення з Word у редактор. Word приносить інлайнові стилі, вкладені <span>, невидимі символи та власні класи.
Штатний обробник вставлення частину вирізає, частину пропускає як є — і в базу йде розмітка, яку потім не відрендерити однаково в браузері та в мобільному застосунку. Таблиці рвуться на окремі абзаци, списки втрачають вкладеність, посилання залишаються з параметрами відстеження.
Окрема стаття втрат — SEO-розмітка. Заголовки рівнів підмінюються жирним текстом, <h2> і <h3> зникають зі структури, зображення приходять без alt і з вихідними іменами файлів.
Пошуковик бачить плоску сторінку без ієрархії, а редактор контенту для сайту перетворюється на джерело ручної правки після кожної публікації. Проблеми кастомного редактора тут не в інтерфейсі — у відсутності валідації на вході та нормалізації на виході.
Ми розбираємо, як це закривається: схема зберігання, правила перетворення Delta в HTML і назад, завантаження медіа та захист від «брудної» вставки.
Що дає кастомна інтеграція редактора: формати та завантаження
Структура документа замість «сирого» HTML
Штатна вставка зображень у редактор віддає <img> з абсолютною адресою та інлайновими стилями — при зміні домену або CDN половина матеріалів «сліпне», а верстка пливе на іншому шаблоні.
Кастомні формати quill описуються як окремі вузли моделі документа, тому заголовок, врізка або таблиця залишаються типізованими блоками, а не набором тегів. На виході — передбачувана верстка на будь-якому шаблоні та коректне перенесення матеріалу між розділами CMS.
Завантаження медіа без «важких» сторінок
Завантаження зображень у редактор іде через власний обробник: файл вирушає на сервер, перевіряється за типом і розміром, стискається та отримує кілька розмірів під різні блоки сторінки. Редактор вставляє готовий об'єкт із набором варіантів, а не оригінал на десяток мегабайт.
Сторінка віддає потрібний розмір під конкретне місце — час завантаження та вага сторінки перестають залежати від того, хто і як завантажив картинку.
Формат Delta як єдине джерело
Формат delta зберігає документ як послідовність операцій, а не як готову розмітку. Це дає дві речі: повну історію правок із можливістю відкату та однаковий результат при виведенні у веб, лист або мобільний застосунок.
Зберігання контенту зводиться до однієї структури — рендер у HTML, plain text або PDF збирається на стороні сервісу, без ручного дублювання.
Інтеграція редактора з CMS
Інтеграція редактора з CMS будується так, що редактор — це поле введення, а вся логіка форматів, завантаження та валідації живе в сервісі. Зміна шаблону або фронтенд-фреймворку не ламає вже збережені матеріали: структура документа залишається незмінною.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Готовий плагін з маркетплейсу | Простий текст, один шаблон виведення | Свої формати та медіа-логіку не розширити |
| Редактор «як є» + ручний HTML | Разові лендінги | Верстка ламається при зміні шаблону, правки не відстежуються |
| Кастомна інтеграція з Delta | Мультишаблонне виведення, історія правок, медіа | Потребує сервісного шару та підтримки |
Quill обрано як основу: його модель документа розширюється без переписування ядра, а формат зберігання не прив'язаний до конкретного шаблону виведення.
Етапи впровадження кастомного редактора в CMS
Впровадження редактора в CMS — це не заміна одного поля на інше, а робота з форматом зберігання контенту, завантаженням медіа та правами доступу. Нижче — як ми ведемо таке завдання, щоб після здачі редактор не довелося переписувати.
- Аудит редактора. Дивимося, що стоїть зараз, у якому вигляді зберігається розмітка (HTML, Delta, власний формат), які поля та шаблони її читають. Фіксуємо, де контент втрачає структуру при збереженні та повторному відкритті.
- Проєктування схеми. Визначаємо, що редактор віддає назовні та що приймає назад, як конвертуються старі записи, де проходить межа між збережуваним і відображуваним представленням. Схема узгоджується до коду — інакше міграція перетворюється на переписування.
- Налаштування форматів. Збираємо панель під реальні завдання: заголовки, списки, таблиці, вставки коду, посилання. Зайві кнопки прибираємо — кожна зайва тягне за собою правило очищення при вставці із зовнішніх джерел.
- Налаштування завантаження медіа. Зображення та файли йдуть через власний обробник: перевірка типу й розміру, перейменування, прив'язка до запису. Окремо перевіряємо вставку з буфера та перетягування — це найчастіші джерела «битих» шляхів.
- Перевірка форматів. Прогоняємо контент по колу: створення, збереження, повторне відкриття, правка, публікація. Звіряємо, що розмітка не накопичує сміття після кількох циклів редагування.
- Перенесення старих записів. Конвертуємо наявний контент і перевіряємо вибіркою: де структура не відновилася — правимо правила, а не окремі записи вручну.
- Передача документації. Віддаємо опис формату, схему конвертації, налаштування завантажувача та інструкцію для редакторів контенту. Далі команда замовника веде редактор сама.
Кожен етап закінчується перевірюваним результатом: схема, працюючий завантажувач, прогнаний контент. Опишіть вашу CMS і поточний редактор — повернемося з оцінкою та планом за цими кроками.
Чим відрізняється Delta-формат від HTML при зберіганні контенту?
Delta-формат зберігає документ як послідовність операцій: «вставити текст», «зберегти атрибут», «видалити діапазон».
Це не розмітка, а журнал змін — редактор і CMS працюють з однією й тією самою структурою документа, тому при завантаженні в quill редактор не потрібно розбирати HTML назад у модель.
HTML-зберігання контенту влаштоване інакше: у базі лежить готова розмітка, і редактор при відкритті розбирає її своїм парсером, втрачаючи те, що не описано в його схемі.
Різниця проявляється на операціях, де важлива точність. Delta фіксує позицію та довжину вставки, тому спільне редагування й скасування дій працюють передбачувано: дві правки не конфліктують через різний порядок тегів.
При HTML-зберіганні контенту такі конфлікти доводиться вирішувати порівнянням дерев, а вкладені списки, таблиці та кастомні блоки після серіалізації часто змінюють структуру.
Порівняння форматів тут не про «краще чи гірше», а про те, хто відповідає за цілісність — редактор чи база.
У Delta є ціна. Формат нечитабельний очима: щоб побачити текст, потрібен рендерер, а пошук по ньому в базі вимагає окремого індексу. HTML можна віддати напряму в шаблон, відфільтрувати санітайзером і покласти в кеш — для простої редакції це дешевше в підтримці.
Тому вибір залежить від сценарію: якщо контент правлять кілька авторів одночасно або потрібні точні відкати, структура документа в Delta окупається; якщо публікації рідкісні й важлива швидкість видачі, HTML простіше.
На практиці ми частіше робимо гібрид: Delta як джерело правди для редактора й CMS, а HTML — як похідний шар, який перезбирається при збереженні та віддається відвідувачам.
Так редактор і CMS не розходяться в представленні документа, а фронтенд отримує готову розмітку без рендера на льоту.
Кейс: як ми усунули втрати форматування в редакторі
Редакція клієнта — інтернет-магазин з каталогом на кілька тисяч карток — працювала у стандартній збірці редактора всередині CMS.
Під час вставлення тексту з Word і Google Docs губилися списки, таблиці та вкладені заголовки: розмітка «схлопувалася» в один абзац, а збереження великої статті з десятком зображень займало до хвилини й іноді падало з помилкою.
Контент-менеджери перевіряли кожну публікацію вручну, а частина матеріалів ішла на повторне редагування вже після виходу на сайт.
Що змінили
Ми розібрали ланцюжок від введення до запису в базу й знайшли два вузькі місця. Перше — редактор віддавав розмітку у власному внутрішньому форматі, а конвертація в HTML відбувалася на стороні сервера «на льоту», через що частина вузлів губилася. Друге — зображення завантажувалися синхронно, блокуючи інтерфейс до завершення запису файлу.
Ми перевели зберігання на канонічний формат розмітки самого редактора: він зберігається в базу як є, а HTML збирається з нього детерміновано — той самий документ завжди дає той самий результат.
Завантаження зображень винесли в окремий потік із постановкою в чергу та попереднім переглядом: автор бачить картинку одразу, а запис іде фоном.
Додатково закрили вставлення із зовнішніх джерел — очищення розмітки тепер зберігає списки, таблиці та заголовки, відкидаючи лише сміттєві стилі.
Метрики до і після
| Показник | До | Після |
|---|---|---|
| Частка публікацій із втратою форматування | ~30% | менше 1% |
| Середній час збереження статті із зображеннями | до 60 сек | 3-5 сек |
| Ручні правки після публікації | 2-3 на матеріал | поодинокі випадки |
| Повторне вставлення тексту з Word | вимагало чищення вручну | проходить автоматично |
Окремо відзначимо ефект на редакцію: час на підготовку матеріалу скоротився приблизно вдвічі, бо зникла обов'язкова вичитка розмітки. Контент-менеджери перестали тримати в голові «правила безпечного вставлення» — редактор сам приводить вставлений фрагмент до коректного вигляду.
Quill ми обрали як основу саме через передбачувану модель документа: розмітка описується деревом операцій, а не рядком HTML, тому її можна надійно порівнювати, зберігати та відновлювати. Це й дало ту саму збереженість контенту, якої не бракувало на старій збірці.
Сумніви перед впровадженням: сумісність, міграція, відкат
Найчастіше технічне питання — що буде з уже накопиченим контентом. Quill зберігає розмітку не в HTML, а в Delta: плоскому списку операцій вставки та форматування.
Під час міграції ми конвертуємо старі матеріали в Delta і назад, проганяючи кожен документ через перевірку на втрату форматування — таблиці, вкладені списки та кастомні блоки переносяться окремим правилом, а не «на око». Сумісність редактора з поточною CMS перевіряється на копії бази до правок у проді.
Що як знадобиться відкат? Конфігурація редактора та правила конвертації лежать у системі контролю версій, тому повернення до попереднього стану — це перемикання на минулий збірку, а не ручна правка. Як бути з доступами?
Ролі на читання, редагування та публікацію розводяться на рівні CMS: автор бачить лише свої документи, редактор — чергу на погодження, адміністратор — історію змін.
Чи зламається поточна верстка після підключення редактора?
Ні. Редактор підключається як окремий модуль з ізольованими стилями, тому теми та шаблони сайту не зачіпаються. Ми проганяємо регрес на типових сторінках і звіряємо розмітку до та після — розбіжності видно до викочування в прод.
На руки після впровадження команда передає:
- конфігурацію редактора з описом панелі інструментів і правил форматування;
- схему конвертації Delta ↔ HTML з прикладами складних документів;
- політику ролей і доступів, прив'язану до груп у CMS;
- скрипти міграції контенту та звіти про перевірку перенесення;
- регламент відкату з точками повернення на кожному етапі;
- документацію по редактору: підключення, розширення, типові помилки.
Опишіть вашу задачу — який контент уже накопичено, яка CMS використовується і які ролі потрібні. Повернемося з оцінкою та планом впровадження.
Терміни впровадження кастомного редактора: етапи та орієнтири
Терміни залежать не від самого редактора, а від того, скільки форматів, інтеграцій і сценаріїв вставки потрібно закрити. Нижче — орієнтири для типового проєкту: кастомний редактор на базі Quill, вбудований у CMS, із завантаженням файлів і зберіганням контенту у Delta-форматі.
Діапазон за етапами — від трьох до семи тижнів на один редактор. Розкид визначається числом нестандартних сценаріїв: вставка з таблиць і документів, спільне редагування, версіонування, обмеження за ролями. Кожен такий сценарій додає окрему гілку перевірок і помітно зсуває термін.
Етапи йдуть не строго послідовно. Прототип і опрацювання зберігання часто перетинаються: поки налаштовуються схеми, вже зрозуміло, у якому вигляді контент ляже в базу.
Це скорочує загальний графік, але вимагає, щоб рішення щодо формату зберігання ухвалювалися на першому тижні, а не в кінці.
Орієнтири вище — для команди, яка вже працювала з Delta-форматом і кастомними збірками. Якщо контент переноситься зі старого редактора, додається етап міграції: розбір розмітки, конвертація, перевірка на вибірці сторінок.
