
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:

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

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:

```md title="pages/about/index.md"
---
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 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>
```

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 title="pages/docs/loader.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](https://blockstudio.dev/it/docs/pages-and-patterns/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.

```bash
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](https://blockstudio.dev/it/docs/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](https://blockstudio.dev/it/docs/blocks/rendering/#prefix-shorthands)

## 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.
