
Blockstudio Wersja 7.4 ma ułatwić przenoszenie projektów opartych na plikach. W wersji 7.2 ułatwiono analizowanie i dystrybuowanie większych projektów, a wersja 7.3 dodała warstwę UI. Wersja 7.4 skupia się na przeniesieniu większej części projektu, jego stron i wyselekcjonowanej treści z bazy danych do plików śledzonych w systemie kontroli wersji.

Główną nowością są kolekcje stron: sposób na wskazanie folderu źródeł stron dla Blockstudio i wygenerowanie na jego podstawie kompletnej, zagnieżdżonej struktury stron WordPress. Źródłem mogą być PHP, Twig, Blade, HTML, Markdown lub zaufany loader zwracający strony z innego lokalnego źródła.

W skrócie:

- **Kolekcje stron**: `pages.json` może definiować kompletny zestaw zagnieżdżonych stron, wartości domyślne, zachowanie typu wpisu, układy, loadery i metadane kolekcji.
- **Strony Markdown**: `index.md` działa jako treść strony, z `page.json` lub samodzielnie z metadanymi frontmatter.
- **Układy stron frontendowych**: `layout.php` może opakowywać zsynchronizowaną treść strony i korzystać z pomocników takich jak `blockstudio_page_tree()` i `blockstudio_page_content()`.
- **Zewnętrzne źródła dokumentacji**: loadery kolekcji mogą generować strony z lokalnych plików lub zwróconych Markdown/HTML.
- **Surowy wynik Markdown**: źródła stron Markdown mogą być udostępniane jako `.md` lub przez `Accept: text/markdown`.
- **Niestandardowe typy wpisów kolekcji**: kolekcje mogą mieć własne czyste adresy URL, automatyczne odświeżanie reguł przepisywania, trasy surowego Markdown oraz migracje stron do CPT bez obejść po stronie motywu.
- **Synchronizacja treści**: `wp bs content pull`, `wp bs content push` i `wp bs content status` umożliwiają przenoszenie do plików dozwolonych wpisów, taksonomii, relacji i zadeklarowanych odwołań do metadanych projektu.
- **Prefiksy tagów bloków**: prefiksy projektu, takie jak `<theme-card>`, mogą być rozpoznawane w uporządkowanych przestrzeniach nazw bez aliasów dla poszczególnych bloków.
- **Bardziej niezawodna synchronizacja**: zmiany stron są wykrywane w manifestach, loaderach, układach, metadanych i plikach źródłowych.
- **Poprawki działania i edytora**: dynamiczne opcje pozostają aktualne, klasy bloków zapytań są zachowywane podczas programowego renderowania, `bsui/select` działa lepiej w gęstych formularzach, właściwości RichText trafiają do edytora, a usunięcie wiersza pola powtarzalnego z RichText jest zachowywane po zapisaniu.

## Strony oparte na plikach

Większość zmian w wersji 7.4 rozwija strony oparte na plikach.

### Kolekcje stron

Przed wersją 7.4 strony oparte na plikach były głównie funkcją na poziomie folderu: utwórz `page.json`, dodaj `index.php` lub `index.twig`, a Blockstudio zsynchronizuje tę pojedynczą stronę z WordPress.

To nadal działa. Wersja 7.4 dodaje drugi tryb, przeznaczony dla większych struktur.

Dodaj manifest `pages.json` do folderu, a stanie się on kolekcją:

```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"
  }
}
```

Każde źródło strony w kolekcji jest wykrywane, normalizowane, synchronizowane i łączone według ścieżki. Strona pod adresem `guide/install` staje się stroną podrzędną `guide`; jeśli brakuje strony `guide`, Blockstudio tworzy wygenerowaną stronę kontenerową, dzięki czemu hierarchia WordPress nadal odpowiada strukturze systemu plików.

Kolekcje mogą korzystać z natywnego typu wpisów `page` lub własnego typu. Gdy kolekcja deklaruje typ wpisów, który jeszcze nie istnieje, Blockstudio rejestruje go na podstawie `postTypeArgs`. Manifest `postType` staje się też wartością domyślną dla każdej strony w kolekcji, więc projekty nie muszą powtarzać jej w `defaults`.

Typy wpisów kolekcji używają sluga kolekcji jako publicznej podstawy URL. Kolekcja `docs` wyznacza stronę główną pod adresem `/docs/`, stronę z `path: "getting-started"` pod adresem `/docs/getting-started/` oraz zagnieżdżone ścieżki pod tą samą podstawą. Podwojone adresy URL, takie jak `/docs/docs/`, przekierowują do adresu kanonicznego. Reguły przepisywania są automatycznie odświeżane po zmianie routingu typu wpisów kolekcji, więc dodanie nowej kolekcji nie wymaga ręcznego zapisywania ustawień bezpośrednich odnośników.

To właśnie sprawia, że zewnętrzna dokumentacja, instrukcje produktów, bazy wiedzy i biblioteki stron naturalnie wpisują się w WordPress: źródło pozostaje w plikach, ale wynik nadal jest prawdziwą, edytowalną treścią WordPress.

### Markdown jako treść strony

Markdown jest teraz pełnoprawnym źródłem stron.

Samodzielne strony Markdown używają metadanych 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.
```

Możesz też połączyć `page.json` z `index.md`, jeśli chcesz rozdzielić konfigurację i treść na osobne pliki. Metadane frontmatter w `index.md` mogą nadpisywać pasujące pola `page.json`, a nieznane klucze frontmatter są zachowywane jako metadane.

Markdown jest konwertowane do HTML, a następnie przekazywane do tego samego parsera stron co szablony PHP, Twig i Blade, dzięki czemu końcowa treść ma natywną postać znaczników bloków.

### Układy i pomocniki stron

Kolekcje mogą zawierać plik `layout.php`. W frontendzie Blockstudio opakowuje zsynchronizowaną treść strony w ten układ.

```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>
```

Nowe pomocniki udostępniają kolekcję jako uporządkowane dane:

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

Dzięki temu masz elementy potrzebne do zbudowania pełnego szkieletu dokumentacji: nawigację opartą na drzewie stron, metadane strony z frontmatter oraz zsynchronizowaną treść blokową WordPress jako główny obszar zawartości.

### Loadery i surowe Markdown

Kolekcje mogą zawierać zaufany lokalny plik `loader.php`. Może on bezpośrednio zwracać strony albo wskazywać dodatkowe lokalne katalogi do przeszukania przez 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',
    ],
  ],
];
```

Przydaje się to, gdy źródło jest już generowane w innym miejscu: w folderze dokumentacji pakietu, eksporcie Markdown lub w kroku budowania zwracającym listę stron.

Źródła stron Markdown mogą też udostępniać surowe źródło Markdown. Zażądaj strony z sufiksem `.md` albo wyślij `Accept: text/markdown`. Metadane frontmatter są usuwane z odpowiedzi, dzięki czemu narzędzia otrzymują czytelną treść dokumentu. Działa to również w przypadku typów wpisów kolekcji, w tym adresów URL takich jak `/docs.md` i `/docs/getting-started.md`.

[Przeczytaj dokumentację stron](https://blockstudio.dev/pl/docs/pages-and-patterns/pages/)

## Synchronizacja treści

Wersja 7.4 wprowadza też synchronizację treści — przepływ pracy WP-CLI dla zespołów, które chcą przechowywać większą część swojego projektu WordPress w plikach.

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

Blockstudio już przechowuje bloki, pola, szablony, wzorce i strony oparte na plikach w Twoim projekcie. Content Sync dodaje wybrane treści z bazy danych do tego procesu opartego na plikach: dozwolone wpisy, terminy, relacje i zadeklarowane metadane można pobierać do plików, przeglądać w git i przesyłać do innego środowiska.

To rozwiązanie jest celowo jawne. Włącz je w `blockstudio.json`, dodaj do listy dozwolonych typy wpisów i taksonomie, którymi chcesz zarządzać, i zadeklaruj odwołania do metadanych, które należy przepisywać między środowiskami.

Podczas pobierania Blockstudio zapisuje w plikach motywu przenośne wpisy, taksonomie, relacje i dozwolone metadane. Podczas wysyłania weryfikuje plan przed zapisem i rozwiązuje zadeklarowane odwołania `post`, `term` i `attachment` z powrotem do lokalnych identyfikatorów bazy danych. Nie zgaduje, że dowolne liczby całkowite są identyfikatorami.

Zakres wersji 7.4 jest celowo zachowawczy: wpisy, taksonomie, relacje taksonomii, dozwolone metadane, przenośne UID, manifesty załączników, próbne uruchomienia, obsługa usuwania, zablokowane elementy i raportowanie stanu. Przechwytywanie definicji taksonomii, kopiowanie plików multimedialnych i przepisywanie identyfikatorów w znacznikach bloków celowo pominięto w tej pierwszej wersji.

Dzięki temu zespoły mogą w przejrzysty sposób wersjonować wyselekcjonowaną treść, taką jak członkowie zespołu, analizy przypadków, lokalizacje, wpisy dokumentacji czy inne uporządkowane rekordy, bez przekształcania całej produkcyjnej bazy danych w migrację. Rozwiązanie jest przeznaczone dla zestawów treści, które nadal można przeglądać jako pliki: dziesiątek lub setek wierszy, a w niektórych projektach niewielu tysięcy, jeśli treść jest uporządkowana i rzadko się zmienia. Nie zastępuje kopii zapasowych bazy danych, synchronizacji danych e-commerce i zamówień, analityki, dzienników, zgłoszeń z formularzy ani innych danych o dużej objętości.

[Przeczytaj dokumentację synchronizacji treści](https://blockstudio.dev/pl/docs/content-sync/)

### Bardziej niezawodna synchronizacja

Blockstudio wykrywa teraz zmiany w źródłach stron, manifestach kolekcji, plikach loaderów i układów, metadanych oraz powiązanych ścieżkach. Jeśli którykolwiek z tych elementów się zmieni, zsynchronizowana strona WordPress zostanie zaktualizowana.

Potok obsługi stron uwzględnia też szczegóły, dzięki którym dokumentacja oparta na plikach sprawdza się w rzeczywistych projektach:

- Źródła stron Markdown synchronizują się jako natywna treść blokowa, wraz z atrybutami bloków
- metadane frontmatter są dostępne dla pomocników frontendowych i układów
- strony kolekcji zachowują stałą tożsamość między synchronizacjami
- zagnieżdżone strony spoza kolekcji są łączone ze stroną nadrzędną
- zagnieżdżone strony spoza kolekcji mogą dziedziczyć najbliższe ustawienie `layout.php` przodka
- usunięte źródła kolekcji porządkują wygenerowane strony WordPress
- zmiana typu kolekcji ze strony `page` na niestandardowy typ wpisu migruje istniejące zsynchronizowane wpisy zamiast tworzyć duplikaty
- kolejność stron jest zachowywana przez `menu_order`

## Prefiksy tagów bloków

Tagi bloków obsługują teraz konfigurowalne prefiksy przestrzeni nazw. Projekt może zarejestrować jeden krótki prefiks i pozwolić Blockstudio rozpoznawać blok w jednej lub kilku przestrzeniach nazw:

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

  return $prefixes;
});
```

Dzięki temu `<theme-card>` może wskazywać `theme-components/card`, `<theme-button>` może użyć zapasowo `bsui/button`, a `<theme-ui-feature-matrix>` może wskazywać `theme-components/ui-feature-matrix`.

Jawne `tag_aliases` nadal mają pierwszeństwo, gdy projekt potrzebuje jednorazowego nadpisania. Tagi z nieznanym prefiksem pozostają bez zmian, a istniejące filtry zezwalające na tagi bloków lub ich zabraniające nadal obejmują bloki rozpoznane na podstawie prefiksu.

[Przeczytaj dokumentację tagów bloków](https://blockstudio.dev/pl/docs/blocks/rendering/#prefix-shorthands)

## Poprawki działania i edytora

Wersja 7.4 zawiera też zestaw poprawek wynikających z pracy nad rzeczywistymi projektami.

- Opcje wypełniane dynamicznie na podstawie zapytania pozostają aktualne po zmianie wpisów, taksonomii, użytkowników lub powiązanych metadanych, a wybór zapytania `populate.fetch: true` pobiera aktualne opcje przy pustych wyszukiwaniach w edytorze.
- Programowe tagi bloków `core/query` i `core/comments` zachowują `className` w generowanych znacznikach opakowujących.
- Pseudokomponenty szablonów zachowują właściwości camelCase, dzięki czemu właściwości takie jak `allowedFormats` i `withoutInteractiveFormatting` trafiają do komponentu edytora zamiast zostać wcześniej odrzucone.
- `bsui/select` lepiej obsługuje dane opcji i przepełnione menu, zwłaszcza w bardziej rozbudowanych kontrolkach edytora.
- `blockstudio/phpstan` rozpoznaje pola zadeklarowane wewnątrz kontenerów `tabs`, dzięki czemu walidacja szablonów, Twig/Blade i tagów bloków obsługuje ten sam kształt pól Blockstudio używany w projektach.
- Usunięcie wiersza pola powtarzalnego z RichText jest zachowywane po zapisaniu. Nieaktualne wartości RichText nie mogą już przywrócić usuniętego wiersza.

## Dlaczego to wydanie ma znaczenie

Motywem wersji 7.4 jest przenośność.

Kolekcje stron zamieniają całe witryny z dokumentacją w foldery plików źródłowych. Strony Markdown ułatwiają tworzenie tych treści i ich późniejszy odczyt. Content Sync rozszerza ten sam model oparty na plikach na wybrane treści z bazy danych, dzięki czemu wpisy, terminy i relacje mogą być przechowywane w git i przenoszone między środowiskami. Prefiksy tagów bloków ułatwiają czytanie szablonów w dużych bibliotekach bloków.

Blockstudio nadal bazuje na plikach. Bloki nadal są folderami. Strony nadal są plikami. Wersja 7.4 pozwala po prostu przechowywać w tych plikach większą część projektu, jego struktur stron i wyselekcjonowanej treści oraz przenosić ją razem z nimi.
