Zum Inhalt springen

Dennis · 21. Juni 2026

Blockstudio 7.4

Blockstudio 7.4 macht dateibasierte Projekte portabler. Während 7.2 die Untersuchung und Verteilung größerer Projekte erleichterte und 7.3 eine UI-Ebene hinzufügte, verlagert 7.4 mehr Bestandteile eines Projekts – seine Seiten und kuratierten Inhalte – aus der Datenbank in versionierte Dateien.

Das wichtigste neue Feature sind Seitensammlungen: Damit kannst du Blockstudio auf einen Ordner mit Seitenquellen verweisen und daraus eine vollständige, verschachtelte WordPress-Seitenstruktur erzeugen. Als Quelle dienen PHP, Twig, Blade, HTML, Markdown oder ein vertrauenswürdiger Loader, der Seiten aus einer anderen lokalen Quelle zurückgibt.

Kurz gesagt:

  • Seitensammlungen: Mit pages.json kannst du eine vollständige Sammlung verschachtelter Seiten mit Standardwerten, Verhalten des Beitragstyps, Layouts, Loadern und Sammlungsmetadaten definieren.
  • Markdown-Seiten: index.md kann als Seiteninhalt dienen, mit page.json oder allein mit Frontmatter.
  • Frontend-Seitenlayouts: layout.php kann synchronisierte Seiteninhalte umschließen und Helfer wie blockstudio_page_tree() und blockstudio_page_content() verwenden.
  • Externe Dokuquellen: Sammlungs-Loader können Seiten aus lokalen Dateien oder zurückgegebenen Markdown/HTML erzeugen.
  • Unverarbeitete Markdown-Ausgabe: Markdown-Seitenquellen können als .md oder über Accept: text/markdown bereitgestellt werden.
  • Benutzerdefinierte Beitragstypen für Sammlungen: Sammlungen können eigene, saubere URLs, automatische Rewrite-Aktualisierungen, unverarbeitete Markdown-Routen und Migrationen von Seiten zu CPTs ohne Theme-seitige Anpassungen bereitstellen.
  • Content Sync: Mit wp bs content pull, wp bs content push und wp bs content status kannst du freigegebene Beiträge, Begriffe, Beziehungen und deklarierte Meta-Referenzen in portable Dateien überführen.
  • Block-Tag-Präfixe: Projektpräfixe wie <theme-card> können über geordnete Namespaces hinweg aufgelöst werden, ohne Aliase für einzelne Blöcke zu benötigen.
  • Zuverlässigere Synchronisierung: Änderungen an Manifesten, Loadern, Layouts, Metadaten und Quelldateien werden erkannt.
  • Laufzeit- und Editor-Korrekturen: Dynamische Optionen bleiben aktuell, Abfrage-Blockklassen bleiben beim programmatischen Rendern erhalten, bsui/select funktioniert in umfangreichen Formularen besser, RichText-Props erreichen den Editor und das Löschen von Repeater-Zeilen mit RichText bleibt nach dem Speichern bestehen.

Dateibasierte Seiten

Der Großteil von 7.4 baut auf dateibasierten Seiten auf.

Seitensammlungen

Vor 7.4 waren dateibasierte Seiten vor allem ein Feature auf Ordnerebene: Erstelle eine page.json, füge eine index.php oder index.twig hinzu und Blockstudio synchronisiert diese einzelne Seite mit WordPress.

Das funktioniert weiterhin. 7.4 ergänzt einen zweiten Modus für größere Strukturen.

Füge einem Ordner ein pages.json-Manifest hinzu, und der Ordner wird zu einer Sammlung:

Text
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}

Jede Seitenquelle innerhalb der Sammlung wird erkannt, vereinheitlicht, synchronisiert und anhand ihres Pfads verknüpft. Eine Seite unter guide/install wird zum Unterelement von guide. Fehlt die guide-Seite, erstellt Blockstudio eine generierte Containerseite, damit die WordPress-Hierarchie weiterhin der Dateisystemstruktur entspricht.

Sammlungen können den nativen Beitragstyp page oder einen eigenen Beitragstyp verwenden. Gibt eine Sammlung einen Beitragstyp an, der noch nicht existiert, registriert Blockstudio ihn anhand von postTypeArgs. Das Manifest-postType wird außerdem zum Standard für jede Seite in dieser Sammlung, sodass Projekte es nicht in defaults wiederholen müssen.

Bei Beitragstypen von Sammlungen dient der Sammlungs-Slug als öffentliche URL-Basis. Eine Sammlung docs löst ihre Stammseite unter /docs/ auf, eine Seite mit path: "getting-started" unter /docs/getting-started/ und verschachtelte Pfade unter derselben Basis. Doppelte URLs wie /docs/docs/ werden an den kanonischen Ort weitergeleitet. Rewrite-Regeln werden automatisch aktualisiert, wenn sich das Routing des Sammlungs-Beitragstyps ändert. Für eine neue Sammlung musst du daher die Permalinks nicht manuell speichern.

Damit werden externe Dokumentationen, Produkthandbücher, Wissensdatenbanken und Seitensammlungen in WordPress ganz selbstverständlich: Die Quelle bleibt in Dateien, das Ergebnis ist aber weiterhin echter, bearbeitbarer WordPress-Inhalt.

Markdown als Seiteninhalt

Markdown ist jetzt eine vollwertige Seitenquelle.

Eigenständige Markdown-Seiten verwenden Frontmatter:

Markdown
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.

Du kannst page.json auch mit index.md kombinieren, wenn du Konfiguration und Inhalt auf mehrere Dateien aufteilen möchtest. Frontmatter in index.md kann übereinstimmende Felder in page.json überschreiben. Unbekannte Frontmatter-Schlüssel bleiben als Metadaten erhalten.

Markdown wird in HTML umgewandelt und anschließend vom selben Seitenparser verarbeitet wie PHP-, Twig- und Blade-Vorlagen. Der endgültige Inhalt ist daher natives Block-Markup.

Layouts und Seitenhelfer

Sammlungen können eine layout.php-Datei enthalten. Im Frontend umschließt Blockstudio den synchronisierten Seiteninhalt mit diesem 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>

Die neuen Helfer stellen die Sammlung als strukturierte Daten bereit:

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

Damit hast du alles, was du für eine vollständige Dokumentationsoberfläche brauchst: Navigation aus dem Seitenbaum, Seitenmetadaten aus Frontmatter und den synchronisierten WordPress-Blockinhalt als Hauptbereich.

Loader und unverarbeitetes Markdown

Sammlungen können eine vertrauenswürdige lokale loader.php-Datei enthalten. Sie kann Seiten direkt zurückgeben oder Blockstudio auf weitere lokale Verzeichnisse verweisen, die durchsucht werden sollen.

PHP
<?php

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

Das ist nützlich, wenn die Quelle bereits anderswo generiert wird: etwa in einem Paket-Dokuordner, einem Markdown-Export oder einem Build-Schritt, der eine Seitenliste zurückgibt.

Markdown-Seitenquellen können auch ihren unverarbeiteten Markdown-Quelltext bereitstellen. Rufe die Seite mit dem Suffix .md ab oder sende Accept: text/markdown. Frontmatter wird aus der Antwort entfernt, damit Tools den lesbaren Dokumentinhalt erhalten. Das funktioniert auch bei Beitragstypen von Sammlungen, darunter URLs wie /docs.md und /docs/getting-started.md.

Lies die Pages-Dokumentation

Content Sync

7.4 führt außerdem Content Sync ein, einen WP-CLI-Workflow für Teams, die mehr von ihrem WordPress-Projekt als Dateien abbilden möchten.

Shell
wp bs content pull
wp bs content push --dry-run
wp bs content status

Blockstudio verwaltet bereits Blöcke, Felder, Templates, Patterns und dateibasierte Seiten in deinem Projekt. Content Sync ergänzt diesen dateibasierten Workflow um ausgewählte Datenbankinhalte: freigegebene Beiträge, Begriffe, Beziehungen und deklarierte Metadaten lassen sich in Dateien übernehmen, in git überprüfen und in eine andere Umgebung übertragen.

Das ist bewusst explizit gehalten. Aktiviere es in blockstudio.json, gib die Beitragstypen und Taxonomien frei, die du verwalten möchtest, und deklariere die Meta-Referenzen, die zwischen Umgebungen angepasst werden sollen.

Beim Abruf schreibt Blockstudio portable Beiträge, Begriffe, Beziehungen und freigegebene Metadaten in Dateien in deinem Theme. Beim Übertragen validiert es den Plan vor dem Schreiben und löst deklarierte Referenzen auf post, term und attachment wieder in lokale Datenbank-IDs auf. Beliebige Ganzzahlen werden nicht automatisch als IDs interpretiert.

Der Umfang von 7.4 ist bewusst konservativ: Beiträge, Begriffe, Begriff-Beziehungen, freigegebene Metadaten, portable UIDs, Anhang-Manifeste, Probeläufe, Bereinigung, gesperrte Entitäten und Statusberichte. Das Erfassen von Taxonomiedefinitionen, das Kopieren von Mediendateien und das Umschreiben von IDs im Block-Markup sind in dieser ersten Version bewusst nicht enthalten.

So können Teams kuratierte Inhalte wie Teammitglieder, Fallstudien, Standorte, Dokumentationseinträge oder andere strukturierte Datensätze sauber versionieren, ohne die gesamte Produktionsdatenbank migrieren zu müssen. Gedacht ist das für Inhaltssammlungen, die sich weiterhin als Dateien überprüfen lassen: Dutzende oder Hunderte Einträge, in manchen Projekten bei strukturierten und selten geänderten Inhalten auch einige Tausend. Es ersetzt keine Datenbanksicherungen und eignet sich nicht für E-Commerce- oder Bestellsynchronisierung, Analysen, Protokolle, Formulareinsendungen oder andere große Datenmengen.

Lies die Content-Sync-Dokumentation

Zuverlässigere Synchronisierung

Blockstudio erkennt jetzt Änderungen an Seitenquellen, Sammlungsmanifesten, Loader-Dateien, Layout-Dateien, Metadaten und zugehörigen Pfaden. Bei einer Änderung wird die synchronisierte WordPress-Seite aktualisiert.

Die Seitenpipeline berücksichtigt außerdem Details, die dateibasierte Dokumentationen in echten Projekten praktisch machen:

  • Markdown-Seitenquellen werden als native Blockinhalte synchronisiert, einschließlich Blockattributen
  • Frontmatter-Metadaten stehen Frontend-Helfern und Layouts zur Verfügung
  • Seiten in Sammlungen behalten bei der Synchronisierung ihre stabile Identität
  • Verschachtelte Seiten außerhalb von Sammlungen werden mit ihrer übergeordneten Seite verknüpft
  • Verschachtelte Seiten außerhalb von Sammlungen können die nächstgelegene übergeordnete layout.php übernehmen
  • Entfernte Sammlungsquellen bereinigen ihre generierten WordPress-Seiten
  • Wird eine Sammlung von page in einen benutzerdefinierten Beitragstyp umgewandelt, werden vorhandene synchronisierte Beiträge migriert, statt Duplikate anzulegen
  • Die Seitenreihenfolge wird über menu_order gespeichert

Block-Tag-Präfixe

Block-Tags unterstützen jetzt konfigurierbare Namespace-Präfixe. Ein Projekt kann ein kurzes Präfix registrieren und Blockstudio den Block in einem oder mehreren Namespaces auflösen lassen:

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

  return $prefixes;
});

Damit kann <theme-card> zu theme-components/card aufgelöst werden, <theme-button> auf bsui/button zurückfallen und <theme-ui-feature-matrix> zu theme-components/ui-feature-matrix aufgelöst werden.

Explizite tag_aliases haben weiterhin Vorrang, wenn ein Projekt eine einmalige Überschreibung benötigt. Tags mit unbekanntem Präfix bleiben unverändert, und die bestehenden Zulassungs- und Sperrfilter für Block-Tags gelten weiterhin für über Präfixe aufgelöste Blöcke.

Lies die Block-Tags-Dokumentation

Laufzeit- und Editor-Korrekturen

7.4 enthält außerdem mehrere Korrekturen, die sich aus der Nutzung in echten Projekten ergeben haben.

  • Dynamisch per Abfrage gefüllte Optionen bleiben aktuell, wenn sich Beiträge, Begriffe, Benutzer oder zugehörige Metadaten ändern. Außerdem rufen populate.fetch: true-Abfrageauswahlen bei leeren Suchen im Editor aktuelle Optionen ab.
  • Programmatisch verwendete core/query– und core/comments-Block-Tags erhalten className im erzeugten Wrapper-Markup.
  • Pseudo-Komponenten in Vorlagen erhalten camelCase-Props. Dadurch erreichen Props wie allowedFormats und withoutInteractiveFormatting die Editor-Komponente, statt vorher verworfen zu werden.
  • bsui/select verarbeitet Optionsdaten und überlaufende Menüs zuverlässiger, insbesondere in kompakteren Editor-Steuerelementen.
  • blockstudio/phpstan erkennt Felder, die in tabs-Containern deklariert sind. Dadurch verstehen Vorlagen-, Twig-/Blade- und Block-Tag-Validierung dieselbe Feldstruktur wie Blockstudio in Projekten.
  • Das Löschen einer Repeater-Zeile mit RichText bleibt nach dem Speichern bestehen. Veraltete RichText-Werte können die gelöschte Zeile nicht mehr wiederherstellen.

Warum dieses Release wichtig ist

Das Thema von 7.4 ist Portabilität.

Seitensammlungen machen aus ganzen Dokumentationswebsites Ordner mit Quelldateien. Markdown-Seiten lassen sich einfach schreiben und wieder auslesen. Content Sync überträgt dasselbe dateibasierte Modell auf kuratierte Datenbankinhalte, sodass Beiträge, Begriffe und Beziehungen in git liegen und zwischen Umgebungen wechseln können. Block-Tag-Präfixe sorgen dafür, dass große Blockbibliotheken in Templates übersichtlich bleiben.

Blockstudio bleibt dateibasiert. Blöcke bleiben Ordner. Seiten bleiben Dateien. 7.4 ermöglicht lediglich, mehr Bestandteile eines Projekts – seine Seitenstrukturen und kuratierten Inhalte – in diesen Dateien abzulegen und mit ihnen zu übertragen.