Когда я впервые столкнулся с задачей синхронизации Gutenberg template parts с реальными файлами темы, я понял: привычный подход через базу данных WordPress — это не всегда удобно. Изменил блок в редакторе — а в файлах темы ничего не отражается. Ручное редактирование кода? Нет, спасибо. Мне нужен был Gutenberg Sync, который работает автоматически и при этом максимально гибкий.

В этой статье я расскажу, как я сделал плагин Gutenberg Sync, что он делает и как он устроен поверхностно, без глубокой технической воды, но с понятной логикой.

Почему нужен Gutenberg Sync

Основная проблема, с которой сталкиваются разработчики и студии: вы меняете хедер, футер или секцию в редакторе блоков, но все изменения остаются только в базе данных WordPress.

Это значит:

  • Вы не можете быстро обновить файл темы.
  • Если кто-то другой работает с кодом — изменения теряются.
  • Любая ручная правка в файле — риск конфликтов.

Вот тут на помощь приходит Gutenberg Sync. Суть проста: любые изменения в template parts, которые вы делаете в редакторе, автоматически или вручную сохраняются в соответствующие HTML-файлы темы.

Как работает плагин

Я разделил функционал на два уровня:

1. Ручная синхронизация блока

В редакторе рядом с каждым template-part появляется кнопка Sync to file. Нажимая её, вы сохраняете именно тот блок, который редактируете, прямо в файл темы.

Внутри это работает так:

  • Скрипт React получает clientId блока и его атрибуты.
  • Через serialize берутся все вложенные блоки внутри выбранного template-part.
  • Содержимое отправляется на сервер через REST API плагина.
  • PHP проверяет, есть ли файл в папках parts, templates.
  • Если файл найден — обновляется содержимое, если нет — появляется уведомление.

Таким образом вы всегда знаете, что редактируемый блок в редакторе точно соответствует файлу темы.

2. Автоматическая синхронизация при сохранении

Чтобы не думать о каждом клике, я добавил авто-sync:

  • При сохранении поста или страницы плагин проходит по всем блокам template-part на странице.
  • Каждый блок сериализуется и отправляется в файл.
  • Всё происходит тихо на фоне, вы видите только уведомление в консоли (для дебага).

Так вы можете редактировать в Gutenberg, а файлы темы всегда актуальны.

Поддерживаемые папки

Чтобы не затрагивать весь код темы, плагин работает только с конкретными папками:

  • parts — хедер, футер, секции
  • templates — страницы и шаблоны контента

Любой файл вне этих папок игнорируется. Это снижает риск случайного перезаписывания важного кода.

Как я сделал синхронизацию

С точки зрения кода всё строится вокруг двух частей:

  1. PHP — REST API для записи и получения списка файлов. Проверяется наличие файла, записывается содержимое, возвращается результат. Всё безопасно: права проверяются через current_user_can('edit_posts').
  2. JavaScript / React — добавление кнопки в редактор Gutenberg. Используются хуки WordPress (addFilter) и select из @wordpress/data для получения блоков. Важный момент: берутся только вложенные блоки выбранного template-part, чтобы не сохранять лишнее.

Дополнительно есть debug-логи, которые помогают проверять, что скрипт загружен и синхронизация выполняется.

Кому нужен этот плагин

  • Студиям, создающим сайты на Gutenberg-блоках.
  • Тем, кто активно использует template parts и хочет работать напрямую с файлами темы.
  • Разработчикам, которым важно, чтобы изменения в редакторе мгновенно попадали в код.

Идеально подходит для современных тем, где структура блоков продумана и нужна быстрая синхронизация с файлами.

Резюме

Создавая этот Gutenberg Sync, я хотел решить три задачи:

  1. Сделать работу с шаблонами удобной и прозрачной.
  2. Исключить ручное редактирование файлов для каждого изменения.
  3. Обеспечить автоматическую синхронизацию при сохранении страницы.

Сейчас плагин позволяет:

  • Сохранять изменения конкретного блока вручную.
  • Автоматически обновлять все template-part при сохранении.
  • Работать с конкретными папками темы, чтобы не трогать лишний код.

Если вы используете Gutenberg и хотите полный контроль над шаблонами, Gutenberg Sync — идеальный инструмент для синхронизации редактора и файлов с шаблонами в вашей блочной WordPress теме.

https://github.com/ecomsys/ecomsys-parts-sync