Vai al contenuto

Dennis · 21 giugno 2026

Blockstudio 7.4

Blockstudio La versione 7.4 punta a rendere più portabili i progetti basati su file. La 7.2 ha semplificato l’ispezione e la distribuzione dei progetti più grandi, mentre la 7.3 ha aggiunto un livello di UI. La 7.4 si concentra sul trasferire più elementi del progetto, delle sue pagine e dei suoi contenuti selezionati dal database a file sottoposti al controllo delle versioni.

La novità principale sono le raccolte di pagine: un modo per indicare a Blockstudio una cartella di sorgenti di pagine e generare da essa una struttura completa di pagine annidate WordPress. La sorgente può essere PHP, Twig, Blade, HTML, Markdown oppure un loader attendibile che restituisce pagine da un’altra sorgente locale.

In breve:

  • Raccolte di pagine: pages.json può definire un insieme completo di pagine annidate, valori predefiniti, comportamento dei tipi di contenuto, layout, loader e metadati della raccolta.
  • Pagine Markdown: index.md può essere usato come contenuto della pagina, con page.json oppure da solo con i metadati frontmatter.
  • Layout delle pagine frontend: layout.php può racchiudere il contenuto sincronizzato delle pagine e usare helper come blockstudio_page_tree() e blockstudio_page_content().
  • Sorgenti di documentazione esterne: i loader delle raccolte possono generare pagine da file locali o da Markdown/HTML restituiti.
  • Output Markdown grezzo: le sorgenti di pagine Markdown possono essere servite come .md o tramite Accept: text/markdown.
  • Tipi di contenuto personalizzati per le raccolte: le raccolte possono gestire URL puliti, aggiornamento automatico delle regole di riscrittura, route Markdown grezze e migrazioni da pagine a CPT senza adattamenti nel tema.
  • Content Sync: wp bs content pull, wp bs content push e wp bs content status rendono portabili in file i post, i termini, le relazioni e i riferimenti ai metadati consentiti dal progetto.
  • Prefissi dei tag dei blocchi: i prefissi del progetto, come <theme-card>, possono essere risolti in spazi dei nomi ordinati senza alias per ogni blocco.
  • Sincronizzazione più affidabile: le modifiche alle pagine vengono rilevate nei manifest, nei loader, nei layout, nei metadati e nei file sorgente.
  • Correzioni per runtime ed editor: le opzioni dinamiche restano aggiornate, le classi dei blocchi query sopravvivono al rendering programmatico, bsui/select funziona meglio nei moduli densi, le proprietà RichText arrivano all’editor e l’eliminazione di righe ripetute con RichText viene mantenuta dopo il salvataggio.

Pagine basate su file

La maggior parte delle novità della versione 7.4 si basa sulle pagine basate su file.

Raccolte di pagine

Prima della versione 7.4, le pagine basate su file erano soprattutto una funzionalità a livello di cartella: create un page.json, aggiungete un index.php o index.twig e Blockstudio sincronizza quella singola pagina in WordPress.

Questo continua a funzionare. La versione 7.4 aggiunge una seconda modalità per le strutture più grandi.

Aggiungete a una cartella un manifest pages.json e quella cartella diventa una raccolta:

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

Ogni sorgente di pagina all’interno della raccolta viene individuata, normalizzata, sincronizzata e collegata in base al percorso. Una pagina in guide/install diventa figlia di guide; se manca la pagina guide, Blockstudio crea una pagina contenitore generata, così la gerarchia WordPress continua a rispecchiare la struttura del filesystem.

Le raccolte possono usare il tipo di contenuto nativo page o un proprio tipo. Quando una raccolta dichiara un tipo di contenuto che ancora non esiste, Blockstudio lo registra da postTypeArgs. Anche il manifest postType diventa il valore predefinito per ogni pagina della raccolta, così i progetti non devono ripeterlo in defaults.

I tipi di contenuto delle raccolte usano lo slug della raccolta come base pubblica URL. Una raccolta docs risolve la propria pagina principale in /docs/, una pagina con path: "getting-started" in /docs/getting-started/ e i percorsi annidati sotto la stessa base. Gli URL duplicati, come /docs/docs/, reindirizzano alla posizione canonica. Le regole di riscrittura vengono aggiornate automaticamente quando cambia il routing del tipo di contenuto della raccolta, quindi una nuova raccolta non richiede un salvataggio manuale dei permalink.

È questo che rende naturali in WordPress le sorgenti di documentazione esterne, i manuali di prodotto, le basi di conoscenza e le librerie di pagine: la sorgente resta nei file, ma il risultato è comunque contenuto WordPress reale e modificabile.

Markdown come contenuto della pagina

Markdown è ora una sorgente di pagine di primo livello.

Le pagine Markdown autonome usano i metadati frontmatter:

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

# About

This Markdown content is synced as native WordPress blocks.

Potete anche abbinare page.json a index.md quando volete tenere configurazione e contenuto in file separati. Il frontmatter in index.md può sostituire i campi corrispondenti di page.json e le chiavi frontmatter sconosciute vengono conservate come metadati.

Markdown viene convertito in HTML e poi elaborato dallo stesso analizzatore di pagine usato per i template PHP, Twig e Blade, così il contenuto finale è markup di blocchi nativo.

Layout e helper per le pagine

Le raccolte possono includere un file layout.php. Sul frontend, Blockstudio racchiude il contenuto sincronizzato della pagina con quel 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>

I nuovi helper espongono la raccolta come dati strutturati:

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

In questo modo avete gli elementi necessari per creare una struttura completa per la documentazione: la navigazione deriva dall’albero delle pagine, i metadati delle pagine dal frontmatter e il contenuto sincronizzato del blocco WordPress funge da area principale.

Loader e Markdown grezzo

Le raccolte possono includere un file locale loader.php attendibile. Può restituire pagine direttamente oppure indicare a Blockstudio altre directory locali da individuare.

PHP
<?php

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

È utile quando la sorgente viene già generata altrove: una cartella di documentazione di un pacchetto, un’esportazione Markdown o una fase di build che restituisce un elenco di pagine.

Le sorgenti di pagine Markdown possono anche fornire la sorgente Markdown grezza. Richiedete la pagina con il suffisso .md oppure inviate Accept: text/markdown. Il frontmatter viene rimosso dalla risposta, così gli strumenti ricevono il corpo leggibile del documento. Funziona anche con i tipi di contenuto delle raccolte, inclusi URL come /docs.md e /docs/getting-started.md.

Leggi la documentazione di Pages

Content Sync

La versione 7.4 introduce anche Content Sync, un flusso di lavoro WP-CLI per i team che vogliono rappresentare più elementi del proprio progetto WordPress come file.

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

Blockstudio già conserva nel progetto blocchi, campi, template, pattern e pagine basate su file. Content Sync aggiunge contenuti selezionati del database a questo flusso di lavoro basato sui file: post, termini, relazioni e metadati consentiti possono essere trasferiti nei file, revisionati in git e inviati a un altro ambiente.

È intenzionalmente esplicito. Lo abilitate in blockstudio.json, consentite i tipi di contenuto e le tassonomie che volete gestire e dichiarate i riferimenti ai metadati da riscrivere tra ambienti.

Con l’importazione, Blockstudio scrive nei file post, termini, relazioni e metadati consentiti e portabili del tema. Con l’esportazione, convalida il piano prima di scrivere e riconduce i riferimenti post, term e attachment dichiarati agli ID del database locale. Non presume che numeri interi arbitrari siano ID.

L’ambito della versione 7.4 è volutamente prudente: post, termini, relazioni tra termini, metadati consentiti, UID portabili, manifest degli allegati, simulazioni, gestione della potatura, entità bloccate e report sullo stato. La registrazione delle definizioni delle tassonomie, la copia dei file multimediali e la riscrittura degli ID nel markup dei blocchi sono volutamente escluse da questa prima versione.

Questo offre ai team un modo semplice per gestire con il controllo delle versioni contenuti selezionati, come membri del team, casi di studio, località, voci di documentazione o altri record strutturati, senza trasformare l’intero database di produzione in una migrazione. È pensato per insiemi di contenuti che si possono ancora revisionare come file: decine o centinaia di righe e, in alcuni progetti, poche migliaia quando il contenuto è strutturato e cambia poco. Non sostituisce i backup del database, la sincronizzazione di ecommerce o ordini, le analisi, i log, gli invii dei moduli o altri dati ad alto volume.

Leggi la documentazione di Content Sync

Sincronizzazione più affidabile

Blockstudio ora rileva le modifiche nelle sorgenti di pagine, nei manifest delle raccolte, nei file loader e layout, nei metadati e nei percorsi correlati. Se uno di questi elementi cambia, la pagina WordPress sincronizzata viene aggiornata.

La pipeline delle pagine gestisce anche i dettagli che rendono pratiche le documentazioni basate su file nei progetti reali:

  • Le sorgenti di pagine Markdown vengono sincronizzate come contenuto di blocchi nativo, inclusi gli attributi dei blocchi
  • I metadati frontmatter sono disponibili agli helper e ai layout del frontend
  • Le pagine delle raccolte mantengono un’identità stabile tra una sincronizzazione e l’altra
  • Le pagine annidate non appartenenti a raccolte vengono collegate alla pagina genitore
  • Le pagine annidate non appartenenti a raccolte possono ereditare il valore layout.php dell’antenato più vicino
  • Le sorgenti rimosse dalle raccolte eliminano le pagine WordPress generate
  • Se una raccolta passa da page a un tipo di contenuto personalizzato, i post sincronizzati esistenti vengono migrati invece di essere duplicati
  • L’ordine delle pagine viene mantenuto tramite menu_order

Prefissi dei tag dei blocchi

I tag dei blocchi ora supportano prefissi configurabili per gli spazi dei nomi. Un progetto può registrare un prefisso breve e lasciare che Blockstudio risolva il blocco in uno o più spazi dei nomi:

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

  return $prefixes;
});

Con questa configurazione, <theme-card> può essere risolto in theme-components/card, <theme-button> può ricadere su bsui/button e <theme-ui-feature-matrix> può essere risolto in theme-components/ui-feature-matrix.

Gli tag_aliases espliciti continuano ad avere la precedenza quando un progetto necessita di un override occasionale. I tag con prefisso sconosciuto restano invariati e i filtri esistenti di consentimento e blocco dei tag dei blocchi si applicano anche ai blocchi risolti tramite prefisso.

Leggi la documentazione dei Block Tags

Correzioni per runtime ed editor

La versione 7.4 include anche una serie di correzioni emerse dall’uso in progetti reali.

  • Le opzioni compilate dinamicamente dalle query restano aggiornate quando cambiano post, termini, utenti o metadati correlati; inoltre, i campi di selezione query populate.fetch: true recuperano opzioni aggiornate nelle ricerche vuote dell’editor.
  • I tag dei blocchi core/query e core/comments generati programmaticamente conservano className nel markup wrapper generato.
  • I pseudo-componenti dei template conservano le proprietà camelCase, così proprietà come allowedFormats e withoutInteractiveFormatting raggiungono il componente dell’editor invece di essere scartate in precedenza.
  • bsui/select gestisce con maggiore affidabilità i dati delle opzioni e i menu che eccedono i limiti, soprattutto nei controlli più densi dell’editor.
  • blockstudio/phpstan riconosce i campi dichiarati all’interno dei contenitori tabs, così la convalida di template, Twig/Blade e tag dei blocchi comprende la stessa struttura dei campi usata da Blockstudio nei progetti.
  • L’eliminazione di una riga ripetuta con RichText viene mantenuta dopo il salvataggio. I valori RichText obsoleti non possono più ripristinare la riga eliminata.

Perché questa release è importante

Il tema della versione 7.4 è la portabilità.

Le raccolte di pagine trasformano interi siti di documentazione in cartelle di file sorgente. Le pagine Markdown rendono facile scrivere quei contenuti e rileggerli. Content Sync estende lo stesso modello basato sui file ai contenuti selezionati del database, così post, termini e relazioni possono risiedere in git e passare da un ambiente all’altro. I prefissi dei tag dei blocchi mantengono leggibili nei template le grandi librerie di blocchi.

Blockstudio continua a basarsi su file. I blocchi sono ancora cartelle. Le pagine sono ancora file. La versione 7.4 permette semplicemente a più elementi del progetto, delle sue strutture di pagine e dei suoi contenuti selezionati, di risiedere in quei file e di viaggiare con essi.