Saltar al contenido

Dennis · 21 de junio de 2026

Blockstudio 7.4

Blockstudio La versión 7.4 busca que los proyectos basados en archivos sean más portátiles. La 7.2 facilitó la inspección y distribución de proyectos grandes, y la 7.3 añadió una capa UI; la 7.4 se centra en sacar más partes de un proyecto —sus páginas y su contenido seleccionado— de la base de datos y llevarlas a archivos con control de versiones.

La función estrella son las colecciones de páginas: permiten indicar a Blockstudio una carpeta de fuentes de páginas y generar a partir de ella una estructura completa de páginas anidadas de WordPress. La fuente puede ser PHP, Twig, Blade, HTML, Markdown o un cargador de confianza que devuelva páginas de otra fuente local.

En resumen:

  • Colecciones de páginas: pages.json puede definir un conjunto completo de páginas anidadas, valores predeterminados, comportamiento del tipo de contenido, diseños, cargadores y metadatos de colección.
  • Páginas Markdown: index.md sirve como contenido de página, con page.json o por sí solo con metadatos iniciales.
  • Diseños de página del frontend: layout.php puede envolver el contenido de página sincronizado y usar funciones auxiliares como blockstudio_page_tree() y blockstudio_page_content().
  • Fuentes externas de documentación: los cargadores de colecciones pueden generar páginas a partir de archivos locales o de Markdown/HTML devueltos.
  • Salida Markdown sin procesar: las fuentes de páginas Markdown pueden servirse como .md o mediante Accept: text/markdown.
  • Tipos de contenido personalizados de colecciones: las colecciones pueden tener URL limpias, vaciar automáticamente las reglas de reescritura, rutas Markdown sin procesar y migrar páginas a tipos de contenido personalizados sin adaptaciones en el tema.
  • Sincronización de contenido: wp bs content pull, wp bs content push y wp bs content status permiten llevar a archivos portátiles entradas, términos, relaciones y referencias de metadatos declaradas incluidas en la lista de permitidos del proyecto.
  • Prefijos de etiquetas de bloques: los prefijos del proyecto, como <theme-card>, pueden resolverse en espacios de nombres ordenados sin alias por bloque.
  • Sincronización más fiable: se detectan los cambios en manifiestos, cargadores, diseños, metadatos y archivos de origen.
  • Correcciones de ejecución y del editor: las opciones dinámicas se mantienen actualizadas, las clases de bloques de consulta sobreviven al renderizado programático, bsui/select funciona mejor en formularios densos, las propiedades de RichText llegan al editor y la eliminación de filas del repetidor con RichText se conserva al guardar.

Páginas basadas en archivos

La mayor parte de la versión 7.4 se basa en páginas basadas en archivos.

Colecciones de páginas

Antes de la versión 7.4, las páginas basadas en archivos eran, sobre todo, una función a nivel de carpeta: crear un page.json, añadir un index.php o index.twig y Blockstudio sincroniza esa única página con WordPress.

Eso sigue funcionando. La versión 7.4 añade un segundo modo para estructuras más grandes.

Añade un manifiesto pages.json a una carpeta y esta se convierte en una colección:

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

Se detectan, normalizan y sincronizan todas las fuentes de páginas de la colección, que quedan enlazadas por ruta. Una página en guide/install pasa a ser hija de guide; si falta la página guide, Blockstudio crea una página contenedora generada para que la jerarquía de WordPress siga coincidiendo con la estructura del sistema de archivos.

Las colecciones pueden usar el tipo de contenido nativo page o uno propio. Cuando una colección declara un tipo de contenido que aún no existe, Blockstudio lo registra desde postTypeArgs. El manifiesto postType también pasa a ser el valor predeterminado para todas las páginas de esa colección, así que los proyectos no tienen que repetirlo en defaults.

Los tipos de contenido de las colecciones usan el slug de la colección como base pública de URL. Una colección docs resuelve su página raíz en /docs/, una página con path: "getting-started" en /docs/getting-started/ y las rutas anidadas bajo la misma base. Las URL duplicadas, como /docs/docs/, redirigen a la ubicación canónica. Las reglas de reescritura se vacían automáticamente cuando cambia el enrutamiento del tipo de contenido de una colección, por lo que una colección nueva no requiere guardar manualmente los enlaces permanentes.

Esto es lo que hace que la documentación externa, los manuales de productos, las bases de conocimiento y las bibliotecas de páginas encajen de forma natural en WordPress: la fuente permanece en archivos, pero el resultado sigue siendo contenido WordPress real y editable.

Markdown como contenido de página

Markdown ahora es una fuente de páginas de primer nivel.

Las páginas Markdown independientes usan metadatos iniciales:

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

# About

This Markdown content is synced as native WordPress blocks.

También puedes combinar page.json con index.md si quieres separar la configuración del contenido en distintos archivos. Los metadatos iniciales de index.md pueden anular los campos correspondientes de page.json, y las claves desconocidas de esos metadatos se conservan como metadatos.

Markdown se convierte en HTML y luego pasa por el mismo analizador de páginas que las plantillas PHP, Twig y Blade, por lo que el contenido final es marcado de bloques nativo.

Diseños y funciones auxiliares de página

Las colecciones pueden incluir un archivo layout.php. En el frontend, Blockstudio envuelve el contenido de página sincronizado con ese diseño.

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>

Las nuevas funciones auxiliares exponen la colección como datos estructurados:

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

Así tienes lo necesario para crear una estructura completa de documentación: navegación basada en el árbol de páginas, metadatos de página procedentes de los metadatos iniciales y el contenido de bloques sincronizado de WordPress como área principal.

Cargadores y Markdown sin procesar

Las colecciones pueden incluir un archivo local de loader.php de confianza. Puede devolver páginas directamente o indicar a Blockstudio directorios locales adicionales que debe explorar.

PHP
<?php

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

Esto resulta útil cuando la fuente ya se genera en otro lugar: una carpeta de documentación de un paquete, una exportación de Markdown o un paso de compilación que devuelve una lista de páginas.

Las fuentes de páginas Markdown también pueden ofrecer el código fuente Markdown sin procesar. Solicita la página con el sufijo .md o envía Accept: text/markdown. Los metadatos iniciales se eliminan de la respuesta para que las herramientas reciban el cuerpo legible del documento. También funciona con tipos de contenido de colecciones, incluidas URL como /docs.md y /docs/getting-started.md.

Consulta la documentación de Pages

Sincronización de contenido

La versión 7.4 también incorpora la sincronización de contenido, un flujo de trabajo WP-CLI para equipos que quieren representar más partes de su proyecto WordPress como archivos.

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

Blockstudio ya mantiene en el proyecto bloques, campos, plantillas, patrones y páginas basadas en archivos. La sincronización de contenido incorpora contenido seleccionado de la base de datos a ese flujo de trabajo centrado en archivos: las entradas, los términos, las relaciones y los metadatos declarados incluidos en la lista de permitidos pueden volcarse en archivos, revisarse en git y trasladarse a otro entorno.

Está diseñado para ser explícito. Se activa en blockstudio.json, se añaden a la lista de permitidos los tipos de contenido y las taxonomías que se quieren gestionar, y se declaran las referencias de metadatos que deben reescribirse entre entornos.

Al importar, Blockstudio escribe en archivos portátiles las entradas, los términos, las relaciones y los metadatos incluidos en la lista de permitidos. Al publicar, valida el plan antes de escribir y resuelve las referencias declaradas de post, term y attachment a los ID de la base de datos local. No presupone que los números enteros arbitrarios sean ID.

El alcance de la versión 7.4 es deliberadamente conservador: entradas, términos, relaciones entre términos, metadatos incluidos en la lista de permitidos, UID portátiles, manifiestos de adjuntos, simulaciones, gestión de elementos obsoletos, entidades bloqueadas e informes de estado. La captura de definiciones de taxonomías, la copia de archivos binarios multimedia y la reescritura de ID en el marcado de bloques quedan fuera de esta primera versión por decisión expresa.

Esto ofrece a los equipos una forma sencilla de versionar contenido seleccionado, como miembros del equipo, casos de éxito, ubicaciones, entradas de documentación u otros registros estructurados, sin convertir toda la base de datos de producción en una migración. Está pensado para conjuntos de contenido que aún se pueden revisar como archivos: docenas o cientos de filas y, en algunos proyectos, unos pocos miles cuando el contenido está estructurado y cambia poco. No sustituye a las copias de seguridad de bases de datos, la sincronización de comercio electrónico o pedidos, los análisis, los registros, los envíos de formularios ni otros datos de gran volumen.

Consulta la documentación de sincronización de contenido

Sincronización más fiable

Blockstudio ahora detecta cambios en las fuentes de páginas, los manifiestos de colecciones, los archivos de cargadores y diseños, los metadatos y las rutas relacionadas. Si cambia cualquiera de estos elementos, se actualiza la página WordPress sincronizada.

La canalización de páginas también gestiona los detalles que hacen prácticas las páginas basadas en archivos en proyectos reales:

  • Las fuentes de páginas Markdown se sincronizan como contenido de bloques nativo, incluidos los atributos de bloque
  • Los metadatos iniciales están disponibles para las funciones auxiliares del frontend y los diseños
  • Las páginas de colecciones mantienen una identidad estable entre sincronizaciones
  • Las páginas anidadas que no pertenecen a una colección enlazan con su página principal
  • Las páginas anidadas que no pertenecen a una colección pueden heredar el layout.php ancestro más cercano
  • Las fuentes de colecciones eliminadas limpian sus páginas WordPress generadas
  • Si una colección cambia de page a un tipo de contenido personalizado, se migran las entradas sincronizadas existentes en lugar de crear duplicados
  • El orden de las páginas se conserva mediante menu_order

Prefijos de etiquetas de bloques

Las etiquetas de bloques ahora admiten prefijos de espacio de nombres configurables. Un proyecto puede registrar un prefijo corto y permitir que Blockstudio resuelva el bloque en uno o varios espacios de nombres:

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

  return $prefixes;
});

Con esta configuración, <theme-card> puede resolverse como theme-components/card, <theme-button> puede recurrir a bsui/button y <theme-ui-feature-matrix> puede resolverse como theme-components/ui-feature-matrix.

Los tag_aliases explícitos siguen teniendo prioridad cuando un proyecto necesita una anulación puntual. Las etiquetas con prefijos desconocidos se dejan intactas, y los filtros existentes de autorización y bloqueo de etiquetas de bloques siguen aplicándose a los bloques resueltos mediante prefijos.

Consulta la documentación de etiquetas de bloques

Correcciones de ejecución y del editor

La versión 7.4 también incluye una serie de correcciones surgidas del uso en proyectos reales.

  • Las opciones obtenidas mediante consultas dinámicas se mantienen actualizadas cuando cambian las entradas, los términos, los usuarios o los metadatos relacionados, y los selectores de consulta populate.fetch: true obtienen opciones en tiempo real cuando las búsquedas del editor están vacías.
  • Las etiquetas de bloques core/query y core/comments generadas mediante programación conservan className en el marcado de envoltura generado.
  • Los pseudocomponentes de plantilla conservan las propiedades camelCase, para que propiedades como allowedFormats y withoutInteractiveFormatting lleguen al componente del editor en lugar de descartarse antes.
  • bsui/select gestiona los datos de opciones y los menús desbordados con más fiabilidad, especialmente dentro de controles de edición más densos.
  • blockstudio/phpstan reconoce los campos declarados dentro de contenedores tabs, de modo que la validación de plantillas, Twig/Blade y etiquetas de bloques entiende la misma forma de campo que Blockstudio usa en los proyectos.
  • La eliminación de una fila del repetidor con RichText se conserva al guardar. Los valores obsoletos de RichText ya no pueden hacer que reaparezca la fila eliminada.

Por qué importa esta versión

El tema central de la versión 7.4 es la portabilidad.

Las colecciones de páginas convierten sitios enteros de documentación en carpetas de archivos fuente. Las páginas Markdown facilitan la escritura de ese contenido y su posterior lectura. La sincronización de contenido amplía el mismo modelo centrado en archivos al contenido seleccionado de la base de datos, para que las entradas, los términos y las relaciones puedan guardarse en git y trasladarse entre entornos. Los prefijos de etiquetas de bloques mantienen legibles las bibliotecas grandes de bloques en las plantillas.

Blockstudio sigue basándose en archivos. Los bloques siguen siendo carpetas. Las páginas siguen siendo archivos. La versión 7.4 permite que más partes de un proyecto —sus estructuras de páginas y su contenido seleccionado— residan en esos archivos y se trasladen con ellos.