Pular para o conteúdo

Dennis · 21 de junho de 2026

Blockstudio 7.4

Blockstudio A versão 7.4 busca tornar mais portáteis os projetos baseados em arquivos. A versão 7.2 facilitou a inspeção e a distribuição de projetos maiores, e a 7.3 acrescentou uma camada de UI; a 7.4 se concentra em retirar mais elementos do projeto, de suas páginas e de seu conteúdo selecionado do banco de dados e colocá-los em arquivos sob controle de versão.

O principal destaque é o recurso de coleções de páginas: uma forma de apontar Blockstudio para uma pasta de fontes de páginas e gerar a partir dela uma estrutura completa de páginas aninhadas WordPress. Essa fonte pode ser PHP, Twig, Blade, HTML, Markdown ou um carregador confiável que retorna páginas de outra fonte local.

Em resumo:

  • Coleções de páginas: pages.json pode definir um conjunto completo de páginas aninhadas, padrões, comportamento de tipos de post, layouts, carregadores e metadados da coleção.
  • Páginas Markdown: index.md funciona como conteúdo de página, com page.json ou sozinho, com frontmatter.
  • Layouts de página do frontend: layout.php pode envolver conteúdo de página sincronizado e usar auxiliares como blockstudio_page_tree() e blockstudio_page_content().
  • Fontes de documentação externas: os carregadores de coleção podem gerar páginas a partir de arquivos locais ou de Markdown/HTML retornados.
  • Saída Markdown bruta: as fontes de páginas Markdown podem ser servidas como .md ou por meio de Accept: text/markdown.
  • Tipos de post personalizados de coleção: as coleções podem ter URLs limpas, atualização automática das regras de reescrita, rotas Markdown brutas e migrações de página para tipo de post personalizado sem adaptações no tema.
  • Content Sync: wp bs content pull, wp bs content push e wp bs content status permitem que posts, termos, relacionamentos e referências de metadados declaradas e incluídas na lista de permissões do projeto sejam armazenados em arquivos portáteis.
  • Prefixos de tags de bloco: prefixos do projeto, como <theme-card>, podem ser resolvidos em namespaces ordenados sem aliases por bloco.
  • Sincronização mais confiável: as alterações nas páginas são detectadas em manifestos, carregadores, layouts, metadados e arquivos de origem.
  • Correções de tempo de execução e do editor: as opções dinâmicas permanecem atualizadas, as classes de blocos de consulta sobrevivem à renderização programática, bsui/select funciona melhor em formulários densos, as propriedades RichText chegam ao editor e a exclusão de linhas do repetidor com RichText persiste após salvar.

Páginas baseadas em arquivos

A maior parte da versão 7.4 se baseia em páginas baseadas em arquivos.

Coleções de páginas

Antes da versão 7.4, as páginas baseadas em arquivos eram principalmente um recurso no nível de pasta: criar um page.json, adicionar um index.php ou index.twig, e Blockstudio sincroniza essa única página com WordPress.

Isso ainda funciona. A versão 7.4 adiciona um segundo modo para estruturas maiores.

Adicione um manifesto pages.json a uma pasta e ela se torna uma coleção:

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

Todas as fontes de páginas dentro da coleção são descobertas, normalizadas, sincronizadas e vinculadas pelo caminho. Uma página em guide/install se torna filha de guide; se a página guide estiver ausente, Blockstudio cria uma página contêiner gerada para que a hierarquia de WordPress ainda corresponda à estrutura do sistema de arquivos.

As coleções podem usar o tipo de post nativo page ou seu próprio tipo. Quando uma coleção declara um tipo de post que ainda não existe, Blockstudio o registra a partir de postTypeArgs. O manifesto postType também se torna o padrão para todas as páginas dessa coleção, então os projetos não precisam repeti-lo em defaults.

Os tipos de post de coleção usam o slug da coleção como base pública de URL. Uma coleção docs resolve sua página raiz em /docs/, uma página com path: "getting-started" em /docs/getting-started/ e os caminhos aninhados sob a mesma base. URLs duplicadas, como /docs/docs/, redirecionam para o endereço canônico. As regras de reescrita são atualizadas automaticamente quando o roteamento do tipo de post da coleção muda, então uma nova coleção não exige salvar manualmente os links permanentes.

É isso que faz com que documentação externa, manuais de produtos, bases de conhecimento e bibliotecas de páginas pareçam naturais em WordPress: a fonte permanece em arquivos, mas o resultado continua sendo conteúdo WordPress real e editável.

Markdown como conteúdo de página

Markdown agora é uma fonte de páginas de primeira classe.

Páginas Markdown independentes usam frontmatter:

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

# About

This Markdown content is synced as native WordPress blocks.

Você também pode combinar page.json com index.md quando quiser separar configuração e conteúdo em arquivos distintos. O frontmatter em index.md pode substituir campos correspondentes de page.json, e as chaves desconhecidas do frontmatter são preservadas como metadados.

Markdown é convertido em HTML e depois processado pelo mesmo analisador de páginas usado nos modelos PHP, Twig e Blade, então o conteúdo final é uma marcação de bloco nativa.

Layouts e auxiliares de página

As coleções podem incluir um arquivo layout.php. No frontend, Blockstudio envolve o conteúdo da página sincronizado com esse 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>

Os novos auxiliares expõem a coleção como dados estruturados:

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

Isso fornece os elementos necessários para criar toda a estrutura de um site de documentação: navegação a partir da árvore de páginas, metadados de página do frontmatter e o conteúdo de blocos WordPress sincronizado como área principal.

Carregadores e Markdown bruto

As coleções podem incluir um arquivo local confiável loader.php. Ele pode retornar páginas diretamente ou indicar a Blockstudio diretórios locais adicionais para descoberta.

PHP
<?php

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

Isso é útil quando a fonte já foi gerada em outro lugar: uma pasta de documentação de pacote, uma exportação Markdown ou uma etapa de compilação que retorna uma lista de páginas.

As fontes de páginas Markdown também podem servir sua fonte Markdown bruta. Solicite a página com o sufixo .md ou envie Accept: text/markdown. O frontmatter é removido da resposta, para que as ferramentas recebam o corpo legível do documento. Isso também funciona para tipos de post de coleção, inclusive URLs como /docs.md e /docs/getting-started.md.

Leia a documentação de Pages

Content Sync

A versão 7.4 também apresenta o Content Sync, um fluxo de trabalho WP-CLI para equipes que querem representar mais elementos do projeto WordPress em arquivos.

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

Blockstudio já mantém blocos, campos, modelos, padrões e páginas baseadas em arquivos no seu projeto. O Content Sync adiciona conteúdo selecionado do banco de dados a esse fluxo de trabalho que prioriza arquivos: posts, termos, relacionamentos e metadados declarados e incluídos na lista de permissões podem ser armazenados em arquivos, revisados em git e enviados para outro ambiente.

O processo é intencionalmente explícito. Você o ativa em blockstudio.json, inclui na lista de permissões os tipos de post e as taxonomias que quer gerenciar e declara as referências de metadados que devem ser reescritas entre ambientes.

Ao importar, Blockstudio grava posts, termos, relacionamentos e metadados permitidos em arquivos portáteis no seu tema. Ao enviar, valida o plano antes de gravar e resolve as referências post, term e attachment declaradas de volta para os IDs do banco de dados local. Ele não presume que números inteiros arbitrários sejam IDs.

O escopo da versão 7.4 é conservador por definição: posts, termos, relacionamentos entre termos, metadados permitidos, UIDs portáteis, manifestos de anexos, execuções de simulação, tratamento de remoções, entidades bloqueadas e relatórios de status. A captura de definições de taxonomia, a cópia de arquivos binários de mídia e a reescrita de IDs na marcação de blocos foram intencionalmente deixadas de fora desta primeira versão.

Isso oferece às equipes uma forma organizada de controlar em versões conteúdo selecionado, como membros da equipe, estudos de caso, locais, entradas de documentação ou outros registros estruturados, sem transformar todo o banco de dados de produção em uma migração. O recurso foi pensado para conjuntos de conteúdo que ainda podem ser revisados como arquivos: dezenas ou centenas de linhas e, em alguns projetos, poucos milhares quando o conteúdo é estruturado e sofre poucas alterações. Não substitui backups de banco de dados, sincronização de comércio eletrônico/pedidos, análises, logs, envios de formulários nem outros dados de grande volume.

Leia a documentação do Content Sync

Sincronização mais confiável

Blockstudio agora detecta alterações nas fontes de páginas, manifestos de coleção, arquivos de carregador, arquivos de layout, metadados e caminhos relacionados. Se qualquer um deles mudar, a página WordPress sincronizada será atualizada.

O fluxo de páginas também lida com os detalhes que tornam prática a documentação baseada em arquivos em projetos reais:

  • As fontes de páginas Markdown são sincronizadas como conteúdo de bloco nativo, incluindo atributos de bloco
  • os metadados de frontmatter ficam disponíveis para auxiliares e layouts do frontend
  • as páginas de coleção mantêm uma identidade estável entre sincronizações
  • páginas aninhadas que não pertencem a coleções são vinculadas à página pai
  • páginas aninhadas que não pertencem a coleções podem herdar o layout.php ancestral mais próximo
  • a remoção de fontes de coleção limpa as páginas WordPress geradas
  • a alteração de uma coleção de page para um tipo de post personalizado migra os posts sincronizados existentes em vez de criar duplicatas
  • a ordem das páginas é preservada por meio de menu_order

Prefixos de tags de bloco

As tags de bloco agora aceitam prefixos de namespace configuráveis. Um projeto pode registrar um prefixo curto e permitir que Blockstudio resolva o bloco em um ou mais namespaces:

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

  return $prefixes;
});

Com isso, <theme-card> pode ser resolvido como theme-components/card, <theme-button> pode recorrer a bsui/button e <theme-ui-feature-matrix> pode ser resolvido como theme-components/ui-feature-matrix.

Os tag_aliases explícitos ainda têm prioridade quando um projeto precisa de uma substituição pontual. Tags de prefixo desconhecidas são mantidas intactas, e os filtros existentes para permitir ou bloquear tags de bloco continuam valendo para blocos resolvidos por prefixo.

Leia a documentação de Block Tags

Correções de tempo de execução e do editor

A versão 7.4 também inclui um conjunto de correções resultantes do uso em projetos reais.

  • As opções preenchidas por consulta dinâmica continuam atualizadas quando posts, termos, usuários ou metadados relacionados mudam, e os seletores de consulta populate.fetch: true buscam opções em tempo real quando as pesquisas do editor não retornam resultados.
  • Tags de bloco core/query e core/comments geradas programaticamente preservam className na marcação de wrapper gerada.
  • Pseudocomponentes de modelo preservam propriedades em camelCase, então propriedades como allowedFormats e withoutInteractiveFormatting chegam ao componente do editor em vez de serem descartadas antes.
  • bsui/select lida de forma mais confiável com dados de opções e menus que extrapolam o espaço disponível, especialmente em controles mais compactos do editor.
  • blockstudio/phpstan reconhece campos declarados em contêineres tabs, para que a validação de modelos, Twig/Blade e tags de bloco entenda o mesmo formato de campo Blockstudio usado nos projetos.
  • A exclusão de uma linha do repetidor com RichText persiste após salvar. Valores RichText desatualizados não podem mais fazer a linha excluída reaparecer.

Por que esta versão é importante

O tema da versão 7.4 é a portabilidade.

As coleções de páginas transformam sites inteiros de documentação em pastas de arquivos-fonte. As páginas Markdown facilitam a criação e a leitura desse conteúdo. O Content Sync estende o mesmo modelo que prioriza arquivos ao conteúdo selecionado do banco de dados, permitindo que posts, termos e relacionamentos sejam armazenados em git e transferidos entre ambientes. Os prefixos de tags de bloco mantêm legíveis os modelos de grandes bibliotecas de blocos.

Blockstudio continua baseado em arquivos. Os blocos continuam sendo pastas. As páginas continuam sendo arquivos. A versão 7.4 apenas permite que mais elementos do projeto, de suas estruturas de páginas e de seu conteúdo selecionado sejam armazenados nesses arquivos e acompanhados por eles.