
Blockstudio Версія 7.4 покликана зробити проєкти на основі файлів портативнішими. Якщо у версії 7.2 стало легше перевіряти та поширювати великі проєкти, а у 7.3 з’явився рівень UI, то 7.4 зосереджена на перенесенні більшої частини проєкту, його сторінок і відібраного вмісту з бази даних у файли під контролем версій.

Головна новинка — колекції сторінок: спосіб вказати Blockstudio папку з джерелами сторінок і створити на її основі повну вкладену структуру сторінок WordPress. Джерелом може бути PHP, Twig, Blade, HTML, Markdown або довірений завантажувач, який повертає сторінки з іншого локального джерела.

Коротко:

- **Колекції сторінок**: `pages.json` можуть визначати повний набір вкладених сторінок, значення за замовчуванням, поведінку типу запису, макети, завантажувачі та метадані колекції.
- **Сторінки Markdown**: `index.md` можна використовувати як вміст сторінки — разом із `page.json` або окремо з frontmatter.
- **Макети сторінок фронтенду**: `layout.php` можуть обгортати синхронізований вміст сторінки та використовувати допоміжні функції, як-от `blockstudio_page_tree()` і `blockstudio_page_content()`.
- **Зовнішні джерела документації**: завантажувачі колекцій можуть створювати сторінки з локальних файлів або повернутих Markdown/HTML.
- **Необроблений вивід Markdown**: джерела сторінок Markdown можна віддавати як `.md` або через `Accept: text/markdown`.
- **Користувацькі типи записів для колекцій**: колекції можуть мати чисті URL, автоматичне оновлення правил перезапису, маршрути Markdown та перенесення сторінок у CPT без обхідних рішень на рівні теми.
- **Синхронізація вмісту**: `wp bs content pull`, `wp bs content push` і `wp bs content status` переносять дозволені для проєкту записи, терміни, зв’язки та оголошені посилання на метадані в портативні файли.
- **Префікси тегів блоків**: префікси проєкту, як-от `<theme-card>`, можна розпізнавати в упорядкованих просторах назв без псевдонімів для кожного блока.
- **Надійніша синхронізація**: зміни сторінок виявляються в маніфестах, завантажувачах, макетах, метаданих і файлах джерел.
- **Виправлення середовища виконання й редактора**: динамічні параметри залишаються актуальними, класи блоків запиту зберігаються під час програмного рендерингу, `bsui/select` краще працює у щільних формах, властивості RichText передаються редактору, а видалення рядка повторюваного поля з RichText зберігається після збереження.

## Сторінки на основі файлів

Більша частина версії 7.4 розвиває сторінки на основі файлів.

### Колекції сторінок

До версії 7.4 сторінки на основі файлів здебільшого були функцією рівня папки: створіть `page.json`, додайте `index.php` або `index.twig`, і Blockstudio синхронізує цю окрему сторінку в WordPress.

Це й далі працює. У версії 7.4 додано другий режим для більших структур.

Додайте до папки маніфест `pages.json` — і вона стане колекцією:

```txt
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
```

```json title="pages/docs/pages.json"
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
```

Усі джерела сторінок у колекції виявляються, нормалізуються, синхронізуються та зв’язуються за шляхом. Сторінка за адресою `guide/install` стає дочірньою для `guide`; якщо сторінки `guide` немає, Blockstudio створює згенеровану сторінку-контейнер, щоб ієрархія WordPress і далі відповідала структурі файлової системи.

Колекції можуть використовувати вбудований тип запису `page` або власний тип запису. Якщо колекція оголошує тип запису, якого ще немає, Blockstudio реєструє його з `postTypeArgs`. Маніфест `postType` також стає значенням за замовчуванням для кожної сторінки колекції, тож проєктам не потрібно повторювати його в `defaults`.

Для публічної бази URL типів записів колекцій використовується назва колекції. Коренева сторінка колекції `docs` доступна за адресою `/docs/`, сторінка з `path: "getting-started"` — за адресою `/docs/getting-started/`, а вкладені сторінки розміщуються за шляхами в тій самій базі. Подвоєні URL, як-от `/docs/docs/`, перенаправляються на канонічну адресу. Правила перезапису автоматично оновлюються, коли змінюється маршрутизація типу запису колекції, тож для нової колекції не потрібно вручну зберігати постійні посилання.

Саме ця можливість робить зовнішню документацію, посібники з продуктів, бази знань і бібліотеки сторінок природною частиною WordPress: джерело залишається у файлах, а результат — це повноцінний редагований вміст WordPress.

### Markdown як вміст сторінки

Тепер Markdown є повноцінним джерелом сторінок.

Для окремих сторінок Markdown використовуйте frontmatter:

```md title="pages/about/index.md"
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.
```

Також можна поєднати `page.json` з `index.md`, якщо конфігурацію та вміст потрібно зберігати в окремих файлах. Frontmatter у `index.md` може перевизначати відповідні поля `page.json`, а невідомі ключі frontmatter зберігаються як метадані.

Markdown перетворюється на HTML, а потім проходить через той самий парсер сторінок, що й шаблони PHP, Twig та Blade, тож кінцевий вміст є нативною розміткою блоків.

### Макети та допоміжні функції сторінок

Колекції можуть містити файл `layout.php`. На фронтенді Blockstudio обгортає ним синхронізований вміст сторінки.

```php title="pages/docs/layout.php"
<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <a href="<?php echo esc_url($item['permalink'] ?? '#'); ?>">
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>
```

Нові допоміжні функції надають дані колекції у структурованому вигляді:

```php
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
```

Це дає все необхідне для створення повноцінної оболонки документації: навігацію за деревом сторінок, метадані сторінок із frontmatter і синхронізований вміст блоків WordPress як основну область вмісту.

### Завантажувачі та необроблений Markdown

Колекції можуть містити довірений локальний файл `loader.php`. Він може повертати сторінки безпосередньо або вказувати Blockstudio на додаткові локальні каталоги для пошуку.

```php title="pages/docs/loader.php"
<?php

return [
  'pages' => [
    [
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ],
  ],
];
```

Це зручно, коли джерело вже створюється в іншому місці: наприклад, це папка документації пакета, експорт Markdown або етап збірки, що повертає список сторінок.

Джерела сторінок Markdown також можуть віддавати необроблений вихідний код Markdown. Запитайте сторінку із суфіксом `.md` або надішліть `Accept: text/markdown`. Frontmatter видаляється з відповіді, тож інструменти отримують читабельне тіло документа. Це працює і для типів записів колекцій, зокрема за URL `/docs.md` та `/docs/getting-started.md`.

[Переглянути документацію зі сторінок](https://blockstudio.dev/uk/docs/pages-and-patterns/pages/)

## Синхронізація вмісту

У версії 7.4 також з’явилася синхронізація вмісту — робочий процес WP-CLI для команд, які хочуть зберігати більше свого проєкту WordPress у вигляді файлів.

```bash
wp bs content pull
wp bs content push --dry-run
wp bs content status
```

Blockstudio уже зберігає блоки, поля, шаблони, шаблони блоків і сторінки на основі файлів у вашому проєкті. Синхронізація вмісту додає до цього процесу, орієнтованого на файли, вибраний вміст бази даних: дозволені записи, терміни, зв’язки та оголошені метадані можна перенести у файли, переглянути в git і надіслати до іншого середовища.

Цей процес навмисно вимагає явного налаштування. Увімкніть його в `blockstudio.json`, додайте до списку дозволених типи записів і таксономії, якими хочете керувати, та оголосіть посилання на метадані, які потрібно переписувати між середовищами.

Під час отримання Blockstudio записує портативні записи, терміни, зв’язки та дозволені метадані у файли теми. Перед надсиланням він перевіряє план, а потім перетворює оголошені посилання `post`, `term` і `attachment` назад на ідентифікатори локальної бази даних. Він не вгадує, що довільні цілі числа є ідентифікаторами.

Обсяг версії 7.4 навмисно обмежений: записи, терміни, зв’язки термінів, дозволені метадані, портативні UID, маніфести вкладень, пробні запуски, обробка видалень, заблоковані сутності та звітування про стан. Запис визначень таксономій, копіювання бінарних медіафайлів і переписування ідентифікаторів у розмітці блоків свідомо не включено до першої версії.

Це дає командам зручний спосіб зберігати у системі контролю версій відібраний вміст, як-от відомості про команду, кейси, локації, документаційні статті чи інші структуровані записи, не перетворюючи всю виробничу базу даних на міграцію. Рішення призначене для наборів вмісту, які можна переглядати як файли: десятки або сотні рядків, а в деяких проєктах — кілька тисяч, якщо вміст структурований і рідко змінюється. Воно не замінює резервне копіювання бази даних, синхронізацію даних електронної торгівлі/замовлень, аналітику, журнали, надсилання форм та інші великі масиви даних.

[Переглянути документацію із синхронізації вмісту](https://blockstudio.dev/uk/docs/content-sync/)

### Надійніша синхронізація

Blockstudio тепер виявляє зміни в джерелах сторінок, маніфестах колекцій, файлах завантажувачів і макетів, метаданих та пов’язаних шляхах. Якщо змінюється будь-що з цього, синхронізована сторінка WordPress оновлюється.

Конвеєр сторінок також обробляє нюанси, завдяки яким документація на основі файлів стає практичною для реальних проєктів:

- Джерела сторінок Markdown синхронізуються як нативний вміст блоків, зокрема з атрибутами блоків
- метадані frontmatter доступні допоміжним функціям фронтенду та макетам
- сторінки колекцій зберігають сталу ідентичність між синхронізаціями
- вкладені сторінки поза колекціями пов’язуються з батьківською сторінкою
- вкладені сторінки поза колекціями можуть успадковувати найближчий батьківський `layout.php`
- видалені джерела колекцій прибирають створені для них сторінки WordPress
- перетворення колекції з `page` на користувацький тип запису переносить наявні синхронізовані записи замість створення дублікатів
- порядок сторінок зберігається через `menu_order`

## Префікси тегів блоків

Тепер теги блоків підтримують налаштовувані префікси просторів назв. Проєкт може зареєструвати один короткий префікс, і Blockstudio шукатиме блок в одному чи кількох просторах назв:

```php
add_filter('blockstudio/block_tags/prefixes', function ($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
```

Після цього `<theme-card>` може відповідати `theme-components/card`, `<theme-button>` може переходити до `bsui/button`, а `<theme-ui-feature-matrix>` може відповідати `theme-components/ui-feature-matrix`.

Явні `tag_aliases` і далі мають пріоритет, якщо проєкту потрібне разове перевизначення. Теги з невідомими префіксами залишаються без змін, а на блоки, знайдені за префіксом, і далі поширюються наявні фільтри дозволених і заборонених тегів блоків.

[Переглянути документацію з тегів блоків](https://blockstudio.dev/uk/docs/blocks/rendering/#prefix-shorthands)

## Виправлення середовища виконання й редактора

У версії 7.4 також є низка виправлень, виявлених під час використання в реальних проєктах.

- Параметри, заповнені динамічними запитами, залишаються актуальними після змін записів, термінів, користувачів або пов’язаних метаданих, а елементи вибору запитів `populate.fetch: true` отримують актуальні параметри для порожніх пошукових запитів у редакторі.
- Теги блоків `core/query` і `core/comments`, створені програмно, зберігають `className` у згенерованій розмітці обгортки.
- Псевдокомпоненти шаблонів зберігають властивості camelCase, тож властивості на кшталт `allowedFormats` і `withoutInteractiveFormatting` передаються компоненту редактора, а не відкидаються раніше.
- `bsui/select` надійніше обробляє дані параметрів і меню, що виходять за межі, особливо в щільніших елементах керування редактора.
- `blockstudio/phpstan` розпізнає поля, оголошені всередині контейнерів `tabs`, тож перевірка шаблонів, Twig/Blade і тегів блоків розуміє ту саму структуру полів, яку Blockstudio використовує у проєктах.
- Видалення рядка повторюваного поля з RichText зберігається після збереження. Застарілі значення RichText більше не відновлюють видалений рядок.

## Чому цей випуск важливий

Тема версії 7.4 — портативність.

Колекції сторінок перетворюють цілі сайти документації на папки з файлами джерел. Сторінки Markdown дають змогу легко створювати цей вміст і читати його назад. Синхронізація вмісту поширює ту саму модель, орієнтовану на файли, на відібраний вміст бази даних, тож записи, терміни та зв’язки можна зберігати в git і переносити між середовищами. Префікси тегів блоків роблять великі бібліотеки блоків зрозумілішими у шаблонах.

Blockstudio і далі працює на основі файлів. Блоки й далі є папками. Сторінки й далі є файлами. Версія 7.4 просто дає змогу зберігати у цих файлах більше складників проєкту — структури його сторінок і відібраний вміст — та переносити їх разом.
