
Blockstudio 7.4 цели да направи проектите, съхранявани във файлове, по-преносими. Във версия 7.2 стана по-лесно да се разглеждат и разпространяват по-големи проекти, а 7.3 добави слой UI отгоре. Версия 7.4 се фокусира върху преместването на по-голяма част от проекта, неговите страници и подбрано съдържание от базата данни във файлове под контрол на версиите.

Основната нова функция са колекциите от страници: начин да насочите Blockstudio към папка с източници на страници и да генерирате от нея цялостна вложена структура от страници WordPress. Източникът може да бъде PHP, Twig, Blade, HTML, Markdown или доверен loader, който връща страници от друг локален източник.

Накратко:

- **Колекции от страници**: `pages.json` може да задава цялостен набор от вложени страници, стойности по подразбиране, поведение на типа публикация, оформления, loaders и метаданни на колекцията.
- **Страници Markdown**: `index.md` може да служи като съдържание на страница — със `page.json` или самостоятелно с frontmatter.
- **Оформления на страниците във frontend**: `layout.php` може да обвива синхронизираното съдържание на страницата и да използва помощници като `blockstudio_page_tree()` и `blockstudio_page_content()`.
- **Външни източници за документация**: loader-ите на колекции могат да генерират страници от локални файлове или върнати Markdown/HTML.
- **Необработен изход Markdown**: източниците на страници Markdown могат да се предоставят като `.md` или чрез `Accept: text/markdown`.
- **Персонализирани типове публикации за колекции**: колекциите могат да имат чисти URL адреси, автоматично обновяване на rewrite правилата, маршрути за необработен Markdown и миграции от страници към CPT без помощни механизми от темата.
- **Content Sync**: `wp bs content pull`, `wp bs content push` и `wp bs content status` пренасят в преносими файлове публикации, термини, връзки и декларирани препратки към метаданни, разрешени за проекта.
- **Префикси за тагове на блокове**: проектните префикси като `<theme-card>` могат да се разрешават в подредени пространства от имена без псевдоними за отделните блокове.
- **По-надеждна синхронизация**: промените в страниците се откриват в манифестите, loader-ите, оформленията, метаданните и изходните файлове.
- **Корекции в средата за изпълнение и редактора**: динамичните опции остават актуални, класовете на блоковете за заявки се запазват при програмно визуализиране, `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, така че крайното съдържание е естествен markup на блокове.

### Оформления и помощници за страници

Колекциите могат да включват файл `layout.php`. Във frontend 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 като основна област.

### Loaders и необработен 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`.

[Прочетете документацията за Pages](https://blockstudio.dev/bg/docs/pages-and-patterns/pages/)

## Синхронизиране на съдържание

Версия 7.4 представя и Content Sync — работен процес WP-CLI за екипи, които искат по-голяма част от проекта си WordPress да бъде представена като файлове.

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

Blockstudio вече съхранява блокове, полета, шаблони, модели и страници, базирани на файлове, в проекта ви. Content Sync добавя избрано съдържание от базата данни към този файлово ориентиран работен процес: разрешените публикации, термини, връзки и декларираните метаданни могат да се извеждат във файлове, преглеждат в git и изпращат към друга среда.

Работният процес умишлено изисква изрична конфигурация. Активирате го в `blockstudio.json`, добавяте към списък с разрешени типовете публикации и таксономиите, които искате да управлявате, и декларирате препратките към метаданни, които трябва да се пренаписват между средите.

При изтегляне Blockstudio записва преносими публикации, термини, връзки и разрешени метаданни във файлове в темата ви. При изпращане първо проверява плана и след това преобразува декларираните препратки `post`, `term` и `attachment` обратно в локални идентификатори от базата данни. Не приема произволни цели числа за идентификатори.

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

Така екипите разполагат с чист начин да управляват чрез контрол на версиите подбрано съдържание, например членове на екипа, казуси, местоположения, записи в документацията или други структурирани записи, без да превръщат цялата производствена база данни в миграция. Този подход е предназначен за набори от съдържание, които все още могат да се преглеждат като файлове: десетки или стотици записи, а в някои проекти — и няколко хиляди, когато съдържанието е структурирано и се променя рядко. Той не замества резервните копия на базата данни, синхронизирането на електронна търговия/поръчки, анализите, логовете, изпращането на формуляри или други данни с голям обем.

[Прочетете документацията за Content Sync](https://blockstudio.dev/bg/docs/content-sync/)

### По-надеждна синхронизация

Blockstudio вече открива промени в източниците на страници, манифестите на колекции, файловете на loader-ите, файловете на оформленията, метаданните и свързаните пътища. При промяна на някой от тях синхронизираната страница WordPress се обновява.

Потокът за обработка на страниците вече се справя и с подробностите, които правят документацията във файлове практична в реални проекти:

- Източниците на страници Markdown се синхронизират като естествено съдържание на блокове, включително атрибутите на блоковете
- Метаданните от frontmatter са достъпни за помощниците и оформленията във frontend
- Страниците в колекциите запазват стабилна идентичност между синхронизациите
- Вложените страници извън колекциите се свързват с родителската си страница
- Вложените страници извън колекциите могат да наследяват най-близкия предшественик `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` все пак имат предимство, когато проектът се нуждае от еднократно заместване. Таговете с непознат префикс остават непроменени, а съществуващите филтри за разрешаване и забраняване на тагове на блокове продължават да важат за блоковете, разрешени чрез префикс.

[Прочетете документацията за Block Tags](https://blockstudio.dev/bg/docs/blocks/rendering/#prefix-shorthands)

## Корекции в средата за изпълнение и редактора

Версия 7.4 включва и набор от корекции, произлезли от реалната употреба в проекти.

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

## Защо тази версия е важна

Темата на версия 7.4 е преносимостта.

Колекциите от страници превръщат цели сайтове с документация в папки с изходни файлове. Страниците Markdown улесняват създаването и извличането на това съдържание. Content Sync разширява същия файлово ориентиран модел към подбрано съдържание от базата данни, така че публикации, термини и връзки да могат да се съхраняват в git и да се преместват между среди. Префиксите на таговете на блокове правят големите библиотеки с блокове по-четими в шаблоните.

Blockstudio все още е базиран на файлове. Блоковете все още са папки. Страниците все още са файлове. Версия 7.4 просто позволява по-голяма част от проекта — структурата на страниците и подбраното съдържание — да се съхранява в тези файлове и да се пренася заедно с тях.
