Saltar al contenido

Páginas

Las páginas son plantillas basadas en archivos que se sincronizan con la base de datos de WordPress como entradas. La sincronización es explícita: ejecuta wp bs pages sync o llama a API de Pages cuando quieras aplicar cambios de origen. Cargar la interfaz pública o el administrador de WordPress nunca realiza un descubrimiento completo de páginas ni modifica las entradas de página.

Las páginas pueden definirse como una única carpeta page.json, como archivos Markdown independientes o como una colección con un manifiesto pages.json. Las colecciones son útiles para documentación, bases de conocimiento, bibliotecas de páginas de destino o cualquier conjunto de páginas anidadas que deba generarse a partir de archivos.

page.json

Para una página definida mediante JSON, añade un archivo de configuración page.json:

JSON
{
  "name": "about",
  "title": "About Us",
  "slug": "about-us",
  "postType": "page",
  "postStatus": "publish",
  "templateLock": "all"
}

Propiedades

Propiedad Tipo Valor predeterminado Descripción
name string obligatorio Identificador único de la página
title string Automático a partir del nombre Título de la página
slug string Igual que el nombre Slug URL de la página
path string "." Ruta lógica dentro de una colección
order integer 0 Orden del menú para la entrada sincronizada
postType string "page" Tipo de entrada WordPress
postStatus string "draft" Estado de las nuevas entradas (publish, draft, pending, private)
postId integer – Fija la página a un ID de entrada WordPress específico
blockEditingMode string – Modo de edición de bloques: "default", "contentOnly" o "disabled"
templateLock string|false "all" Modo de bloqueo: "all", "insert", "contentOnly" o false
templateFor string|null null Se establece como plantilla predeterminada para un tipo de entrada
sync boolean true Indica si la reconciliación explícita normal puede crear o actualizar la entrada
render string|object|false – Renderiza la página con un renderizador de páginas registrado (consulta Páginas de componentes)

Entre page.json, el frontmatter y las entradas del cargador, las claves reconocidas incluyen blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock y title. Cualquier clave que no figure arriba se guarda en el array meta de la página.

Fuentes de contenido

La definición de una página determina qué entrada WordPress debe existir. La fuente de contenido determina qué marcado de bloques se escribe en esa entrada.

Cuando una carpeta de página tiene un archivo page.json, Blockstudio busca un archivo de origen contiguo en este orden:

Archivo Uso
index.php Marcado de bloques similar a HTML, se lee tal cual (el código PHP no se ejecuta)
index.blade.php Contenido de plantilla Blade
index.twig Contenido de plantilla Twig
index.md Contenido Markdown

page.json también puede incluir markdown o html en línea en lugar de usar un archivo contiguo:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "name": "notice",
  "title": "Notice",
  "html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}

Las colecciones añaden dos modos de origen más:

  • Archivos Markdown detectados directamente en el árbol de la colección.
  • Entradas del cargador devueltas por loader.php.

Las entradas del cargador pueden usar markdown, html o content con contentType. También pueden apuntar a un archivo file o template local. El tipo de las fuentes de archivos y plantillas se deduce a partir de la extensión, salvo que contentType se defina explícitamente.

Los valores contentType admitidos son php, blade, twig, markdown y html. Markdown se convierte primero a HTML y luego se analiza en bloques nativos de WordPress. Las fuentes PHP, Blade, Twig y HTML pasan por el analizador de páginas normal de Blockstudio.

Clases en bloques del núcleo

Un class en un elemento HTML asignado a un bloque del núcleo se convierte en su className. Una etiqueta explícita de bloque del núcleo puede usar directamente className. Ambas formas conservan las clases en el contenedor guardado del bloque, junto con las clases que genera WordPress:

HTML
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
  <h2 class="title">Feature</h2>
</block>

Si ambas propiedades están presentes, className tiene prioridad. Esta conversión solo se aplica a los bloques del núcleo: una asignación de bloque personalizada mantiene sin cambios su campo class. Las clases de estilo del botón, como is-style-outline, pertenecen al contenedor del botón, no a su enlace.

Ejecuta wp bs pages sync para aplicar las correcciones del analizador a las páginas sincronizadas anteriormente. Las actualizaciones del analizador se reconocen en la siguiente sincronización explícita, aunque no se haya editado ningún archivo de origen. Las páginas bloqueadas y las páginas con sync: false conservan sus protecciones habituales; las solicitudes del frontend nunca realizan esta sincronización.

Bloques WordPress serializados

Las fuentes de páginas y patrones también pueden contener bloques serializados copiados del editor de código WordPress:

HTML
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->

Cuando la fuente contiene un delimitador de bloque <!-- wp:... -->, Blockstudio usa el analizador de bloques nativo de WordPress para toda la fuente. Los atributos, los bloques anidados, los bloques dinámicos como Query Loop y los bloques Blockstudio conservan su estructura serializada. El contenido HTML fuera de los comentarios de bloque sigue siendo HTML libre nativo; no se asigna a bloques adicionales. No mezcle las etiquetas de bloque HTML de Blockstudio con este formato esperando que se conviertan. Los comentarios ordinarios de HTML no activan el modo de bloques serializados.

Páginas Markdown

Usa Markdown cuando el texto deba estar en archivos, pero convertirse en contenido de bloques WordPress editable después de la sincronización. La fuente Markdown se convierte en marcado de bloques durante la sincronización. La entrada sincronizada guarda bloques, no el cuerpo Markdown sin procesar.

Markdown puede usarse de tres maneras:

Fuente ¿Se requiere frontmatter? Notas
pages/example/index.md independiente Sí El frontmatter proporciona la identidad de la página.
page.json junto con index.md No page.json define la página y Markdown proporciona el contenido.
Markdown dentro de una colección No La colección deduce name y path a partir de la ubicación del archivo.

Un index.md independiente sin frontmatter se omite porque Blockstudio no tiene una identidad de página que sincronizar. Markdown de colección no necesita frontmatter porque el manifiesto de la colección y la ruta del archivo proporcionan esa identidad.

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. En ese caso, page.json define la página y index.md proporciona el contenido. El frontmatter de index.md prevalece sobre los valores coincidentes de page.json.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
title: API Reference
order: 20
---

# Reference

This page uses `page.json` with Markdown content.

Para Markdown de colección, la ruta del archivo se convierte en la ruta lógica de la página, salvo que el frontmatter la reemplace:

Archivo Ruta predeterminada
pages/docs/index.md .
pages/docs/getting-started.md getting-started
pages/docs/guide/install/index.md guide/install
pages/docs/guide/install.md guide/install

Las claves de frontmatter desconocidas se conservan en el arreglo meta de la página. Así puedes adjuntar datos como section o description y leerlos desde el PHP API.

Markdown se analiza como GitHub Flavored Markdown. Se permite HTML sin procesar, se eliminan los enlaces no seguros y los encabezados sin ID explícito reciben uno estable. El frontmatter YAML anidado requiere el analizador YAML incluido.

Markdown sin procesar

Las fuentes de archivos Markdown pueden exponer el Markdown original para herramientas externas y lectores de documentación. Markdown en línea no tiene un archivo de origen, así que se sincroniza con bloques, pero no genera una respuesta .md sin procesar.

Solicita la página con el sufijo .md, por ejemplo https://example.com/docs/reference.md. O envía un encabezado Accept: text/markdown a la URL normal de la página:

Shell
curl -H "Accept: text/markdown" https://example.com/docs/reference/

El frontmatter se elimina de la respuesta. Las respuestas Markdown sin procesar correctas envían Content-Type: text/markdown, X-Robots-Tag: noindex y un encabezado Link canónico a la página HTML. Las rutas .md inexistentes devuelven un 404 real.

La negociación funciona con el prerenderizado estático: una solicitud cuyo encabezado Accept contiene text/markdown nunca recibe respuesta del almacén de prerenderizado ni del complemento de servicio anticipado, por lo que llega a WordPress y al controlador Markdown. Las respuestas HTML prerenderizadas, la HTML de una página que también negocia Markdown y la Markdown respondida mediante Accept envían Vary: Accept, para que las cachés que respetan Vary mantengan ambas variantes separadas. Un CDN que basa su caché únicamente en URL necesita su propia regla para omitir la caché en esas solicitudes. Pages::negotiates_markdown( $post_id ) informa si una página responde a solicitudes Markdown.

La colección Markdown conserva la misma estructura de URL para Markdown sin procesar:

URL de página Ruta Markdown URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Desactiva las respuestas Markdown sin procesar con el filtro blockstudio/pages/serve_markdown:

PHP
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );

Una solicitud .md URL que no resuelve a una página respaldada por Markdown solo devuelve 404 si la ruta está dentro de una colección de páginas. Fuera de todas las colecciones, Blockstudio deja la solicitud intacta para que WordPress y otros plugins la gestionen.

Páginas de componentes

Una página de componente se renderiza mediante un renderizador de páginas en lugar de almacenarse como bloques. Blockstudio no incluye ningún renderizador. Un tema o plugin registra uno para los archivos de entrada que gestiona, como un renderizador React para page.tsx, y Blockstudio lo invoca con la página, la entrada WordPress y el contenido renderizado de la ranura.

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

render es explícito. Un directorio con index.php y page.tsx, pero sin render, sigue siendo una página normal, de modo que añadir un renderizador nunca renderiza dos veces una página existente. Los formatos son:

Valor Significado
"page.tsx" Solo entrada, sin cargador de datos
{ "entry": "page.tsx", "data": "data.php" } Entrada y cargador de datos
{ "entry": "page.tsx", "renderer": "react" } Entrada con un ID de renderizador explícito
false Sin renderizador, incluso si un valor predeterminado de la colección indica uno

Las rutas se resuelven en relación con el directorio de la página o con la raíz de la colección para las entradas del cargador. Deben permanecer dentro de la fuente de descubrimiento, salvo que blockstudio/pages/allow_external_loader_path lo permita. Sin renderer, se usa el renderizador que gestiona la extensión de la entrada. Un render que indique una entrada o un archivo de datos inexistente, un renderizador desconocido o una extensión que ningún renderizador gestione constituye un error de descubrimiento, que detiene la reconciliación antes de eliminar nada.

Qué almacena la sincronización

La sincronización almacena un bloque blockstudio/page. Si el directorio de la página también tiene una fuente index.*, esa fuente se analiza como cualquier otra fuente de página y se convierte en los bloques internos del bloque, es decir, su ranura:

HTML
<!-- wp:blockstudio/page /-->

<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->

Mantén el contenido propiedad de WordPress, como los shortcodes, en la ranura. Una fuente que solo contiene un shortcode, como [download_checkout], se almacena como un bloque core/shortcode, de modo que su salida no queda rodeada por ningún párrafo. Permanece en post_content, así que las comprobaciones de has_shortcode() la detectan, los bloques de ranura con clave se combinan con los cambios del editor igual que los bloques anidados con clave y do_shortcode expande los shortcodes una vez con su prioridad habitual de the_content, después de que el renderizador les haya dado estructura.

La definición del renderizado se almacena con la entrada como rutas portables theme:. La huella digital de la página incluye la definición, pero no los bytes de la entrada ni del cargador de datos: editar page.tsx o data.php deja la entrada sin cambios y llega a los visitantes mediante el renderizado y el grafo prerenderizado estático, que registra la entrada, el cargador de datos y todos los archivos que informa el renderizador.

Registrar un renderizador

Registra los renderizadores en la acción blockstudio/pages/renderers. Se ejecuta una vez por solicitud, antes del primer descubrimiento o renderizado, así que wp bs pages sync y las solicitudes del frontend ven el mismo registro.

PHP
add_action(
	'blockstudio/pages/renderers',
	static function (): void {
		Blockstudio\Page_Renderers::register(
			'react',
			array(
				'extensions' => array( 'tsx' ),
				'layouts'    => array( 'layout.tsx' ),
				'render'     => 'my_theme_render_page',
			)
		);
	}
);

Los ID de los renderizadores están en minúsculas. Cada extensión o nombre de diseño puede pertenecer a un solo renderizador, y layout.php sigue siendo el diseño propio de Blockstudio. La función invocable recibe una solicitud:

Clave Valor
kind page o layout para un diseño de renderizador
renderer ID del renderizador
entry Ruta absoluta de la entrada
data Ruta absoluta del cargador de datos o null
page Datos canónicos de la página, incluido meta
post_id ID de entrada WordPress
slot Contenido renderizado de la ranura o contenido de la página para un diseño
context frontend, rest, feed o cli

Devuelve el HTML, los archivos leídos durante el renderizado y los recursos opcionales:

PHP
function my_theme_render_page( array $request ): array {
	return array(
		'html'         => '<main>...</main>',
		'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
		'assets'       => array( array( 'path' => '/abs/path/to/page.js' ) ),
	);
}

context proviene del tipo de solicitud, nunca del visitante, así que un renderizador no puede alterar la paridad de bytes entre usuarios con y sin sesión al leerlo. Si un renderizador falla, lanza una excepción: la página no muestra un cuerpo vacío. En una vista previa del editor REST, el bloque muestra el error como aviso. Tras un renderizado correcto, la acción blockstudio/pages/rendered recibe la página, HTML y sus dependencias.

assets enumera los archivos de script y estilo que necesita la página. Se procesan como los recursos de bloque (la convención *.inline.*, los módulos ES, la minificación y ?ver), y la página los imprime una sola vez a través del mismo búfer que imprime los recursos de bloque, de modo que una página prerrepresentada los incluye. Un recurso puede establecer version para reemplazar su valor ?ver. El código que está fuera de un renderizador puede usar el mismo canal mediante Blockstudio\Assets::register_owner(), que devuelve el comentario marcador que se debe imprimir.

Editor

En el editor, blockstudio/page muestra una vista previa de la página renderizada en el servidor, con el espacio como bloques internos que siguen el templateLock de la página. El bloque no se puede insertar, duplicar ni anidar dentro de otro bloque.

Colecciones de páginas

Una colección es una carpeta con un manifiesto pages.json. Agrupa varias fuentes de páginas bajo un único slug de colección, aplica valores predeterminados, admite rutas anidadas y puede registrar automáticamente un tipo de entrada dedicado.

Código
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
Propiedad Tipo Descripción
collection / slug / name string Slug de la colección. collection es la forma más clara y se convierte en la base pública de URL.
title string Título legible de la colección.
postType string Tipo de contenido para las páginas generadas. De forma predeterminada, es page. Si no existe, Blockstudio lo registra.
postTypeArgs object Argumentos que se pasan a register_post_type() cuando Blockstudio registra el tipo de contenido de la colección.
defaults object Propiedades de página predeterminadas aplicadas a cada página de la colección. Un valor render predeterminado solo se aplica a una página cuando su entrada existe en el directorio de páginas.
scope string collection (predeterminado) o site. Consulta Colecciones del sitio.
meta object Metadatos personalizados de la colección. Las claves desconocidas del manifiesto también se almacenan en meta.

Las rutas de las páginas de una colección son rutas lógicas. Una página con path: "guide/install" se sincroniza como hija de guide, y guide se sincroniza como hija de la raíz de la colección cuando existen esas páginas principales.

Si una colección jerárquica contiene una página anidada, pero no existe la fuente de una página intermedia, Blockstudio genera una página contenedora vacía para esa ruta, lo que mantiene completa la jerarquía de WordPress. Los tipos de entrada no jerárquicos (sin compatibilidad con páginas principales mediante page-attributes) no generan contenedores vacíos. Usan la ruta de colección guardada, por lo que pueden coexistir rutas anidadas como guide/install y setup/install aunque ambas terminen en install.

Tipos de entrada y URL de colecciones

Define postType en el manifiesto de la colección para sincronizar todas sus páginas con ese tipo de entrada. No hace falta repetir el mismo valor en defaults. Las páginas individuales aún pueden reemplazar postType en el frontmatter o en page.json.

Si el tipo de entrada no existe, Blockstudio lo registra con show_in_rest: true, una configuración del editor similar a la de las páginas y el slug de la colección como base pública de URL. postTypeArgs puede reemplazar los argumentos de registro. Las reglas de reescritura del tipo de entrada de la colección se vacían automáticamente cuando cambian los tipos de entrada registrados o los argumentos de reescritura, así que no necesitas volver a guardar los enlaces permanentes de WordPress.

Las URL de las colecciones usan el slug de la colección seguido de la path lógica de cada página:

Ruta de origen Público URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Este modelo URL funciona tanto con tipos de contenido de colección jerárquicos como no jerárquicos. Blockstudio también redirige las URL duplicadas, como /docs/docs/ o /docs/docs/getting-started/, a la URL canónica URL.

Las páginas de colección exponen Markdown sin procesar en las mismas URL (consulta Markdown sin procesar).

Si cambias una colección de postType: "page" a un tipo de contenido personalizado, Blockstudio migra los contenidos de colección ya sincronizados en su lugar cuando coincide su identidad de página almacenada. Así se conservan los ID de contenido, los metadatos y el contenido existente, y se evita duplicar los contenidos antiguos. Los contenidos de colección obsoletos se limpian en todos los estados de contenido según el filtro blockstudio/pages/orphan_action.

Colecciones del sitio

Un manifiesto con "scope": "site" agrupa todas las páginas que contiene sin convertirlas en páginas de colección. Úsalo en la raíz del árbol de páginas de un sitio para aplicar valores predeterminados compartidos y enumerar las páginas del sitio con blockstudio_page_tree( 'my-site' ).

JSON
{
  "collection": "my-site",
  "title": "My Site",
  "scope": "site",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "all",
    "render": { "entry": "page.tsx", "data": "data.php" }
  }
}

Las páginas de una colección del sitio conservan exactamente la misma identidad que tienen sin el manifiesto, así que añadir una a un árbol existente no actualiza ninguna fila de contenido ni crea ni elimina nada:

  • Las claves siguen siendo globales: Pages::get_page( 'home' ) y las claves de página almacenadas siguen coincidiendo.
  • Las URL siguen siendo URL de página WordPress. No se aplican reglas de reescritura de colección, filtros de enlaces permanentes ni redirecciones de URL duplicadas; tampoco se generan páginas contenedoras vacías.
  • Las rutas lógicas, los slugs, los elementos superiores y las identidades de origen son los de las páginas independientes, y los diseños se resuelven según el antecesor más cercano.
  • Los manifiestos pages.json anidados conservan sus propias colecciones, y sus subárboles quedan fuera de la colección del sitio.
  • Los valores predeterminados se aplican por página: un valor render predeterminado solo se aplica a las páginas cuyo directorio contiene su entrada, por lo que las páginas de shortcode y Markdown conservan sus fuentes.

Cargadores de colecciones

Las colecciones pueden incluir un loader.php local de confianza. Úsalo cuando las páginas de la colección procedan de otra fuente local, como una carpeta externa de documentación, un paquete o un manifiesto generado.

El cargador se ejecuta durante la detección y sincronización explícitas de páginas. Debe ser determinista y local. Evita obtener contenido remoto desde loader.php, ya que eso haría que la sincronización del despliegue dependiera de ese servicio.

PHP
<?php

return array(
  'meta' => array(
    'source' => 'loader',
  ),
  'paths' => array(
    __DIR__ . '/external-docs',
    array(
      'path' => __DIR__ . '/cli-docs',
      'prefix' => 'cli',
      'meta' => array(
        'doc_set' => 'cli',
      ),
    ),
  ),
  'pages' => array(
    array(
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ),
    array(
      'name' => 'docs-template',
      'title' => 'Template',
      'path' => 'template',
      'file' => __DIR__ . '/template.md',
    ),
  ),
);

Un cargador puede devolver un arreglo con las claves pages, meta y paths:

Clave Descripción
pages Una lista de matrices de páginas. Cada página admite las mismas claves reconocidas que el contenido inicial page.json y Markdown.
meta Metadatos combinados con la matriz meta de cada página generada por el cargador.
paths Directorios locales adicionales que se deben buscar como parte de esta colección. Las entradas pueden ser cadenas u objetos de ruta.
render Una definición de renderizado para todas las páginas Markdown descubiertas a partir de paths.

Como forma abreviada, el cargador puede devolver una lista simple de arreglos de páginas.

Las entradas de página del cargador pueden proporcionar contenido de estas formas:

Forma Descripción
markdown Contenido Markdown en línea.
html Contenido HTML en línea.
content + contentType Contenido genérico en línea. contentType debe resolverse como markdown o html.
file Fuente de archivo local. El tipo se infiere de la extensión, salvo que se establezca contentType.
template Alias de file.

Las referencias a archivos del cargador pueden apuntar a fuentes PHP, Blade, Twig, Markdown o HTML. Las rutas relativas se resuelven desde la raíz de la colección. Las rutas absolutas y las rutas fuera de la raíz de la colección solo se permiten si el filtro blockstudio/pages/allow_external_loader_path las autoriza.

De forma predeterminada, las páginas del cargador usan generated: true. Cuando una página generada por el cargador desaparece de sus resultados, Blockstudio trata el contenido sincronizado como huérfano en la siguiente sincronización y lo limpia según el filtro blockstudio/pages/orphan_action.

Los directorios incluidos en paths se detectan como las carpetas normales de la colección. Pueden contener archivos Markdown o carpetas page.json. Si esas rutas están fuera de la raíz de la colección, se aplica el mismo filtro de rutas externas.

Usa una entrada de cadena cuando el directorio externo deba conservar sus propias rutas lógicas. Usa una entrada de objeto cuando el directorio deba montarse bajo un prefijo de ruta de la colección:

PHP
'paths' => array(
  array(
    'path' => __DIR__ . '/cli-docs',
    'prefix' => 'cli',
    'meta' => array(
      'doc_set' => 'cli',
    ),
  ),
),

Con esa configuración, cli-docs/index.md pasa a ser path: "cli" y cli-docs/getting-started.md pasa a ser path: "cli/getting-started" en la colección. Los prefijos también evitan colisiones entre nombres de páginas generadas, de modo que varios directorios montados pueden incluir cada uno index.md o getting-started.md. Establece preserveNames en true en el objeto de ruta si deben conservarse los valores explícitos de name del frontmatter page.json o Markdown.

Propiedades del objeto de ruta:

Propiedad Tipo Descripción
path string Directorio local que se debe buscar. Las rutas relativas se resuelven desde la raíz de la colección.
prefix string Prefijo opcional de ruta lógica dentro de la colección.
preserveNames boolean Conserva los nombres de página explícitos en lugar de generarlos a partir de la ruta con prefijo. De forma predeterminada, es false cuando se establece prefix.
meta object Metadatos combinados con cada página descubierta a partir de esta ruta. Los metadatos de la página prevalecen si hay claves duplicadas.
render string|object Definición de renderizado para las páginas Markdown de esta ruta, que reemplaza la de render del cargador.

Renderizar Markdown mediante un componente

Con render, las páginas Markdown que descubre un cargador se renderizan mediante un renderizador de páginas en lugar de almacenarse como bloques:

PHP
<?php

return array(
  'paths'  => array( __DIR__ . '/external-docs' ),
  'render' => array(
    'entry' => __DIR__ . '/document.tsx',
    'data'  => __DIR__ . '/document.php',
  ),
);

Siguen siendo páginas Markdown: el tipo de contenido, la ruta del contenido, las respuestas .md y el contenido inicial no cambian. La sincronización almacena un bloque blockstudio/page cuyo HTML interno es el Markdown convertido, saneado cuando la colección sanea su contenido, en lugar de bloques analizados, para que post_content conserve el texto del documento. El renderizador recibe ese HTML como espacio y puede leer la fuente desde page.content_path. Las rutas relativas se resuelven desde la raíz de la colección; se aplica el filtro de rutas externas igual que para las rutas. Si el contenido inicial de una página establece su propio render o render: false, esa página queda excluida.

Diseños

Un archivo layout.php envuelve la representación en el frontend de una página basada en archivos. No reemplaza el post_content sincronizado y almacenado en WordPress, ni envuelve el lienzo del editor. El diseño solo se ejecuta en solicitudes de páginas individuales del frontend.

En las colecciones, coloca layout.php junto a pages.json para envolver cada página del frontend de esa colección:

PHP
<?php $current = blockstudio_current_page(); ?>

<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
      <a
        href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
        <?php echo $is_current ? 'aria-current="page"' : ''; ?>
      >
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>

blockstudio_page_content() imprime el cuerpo de la página que WordPress normalmente mostraría mediante the_content. Si un diseño no genera blockstudio_page_content(), el contenido de la página queda oculto intencionalmente.

Los diseños pueden usar las funciones auxiliares de página:

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

Las páginas anidadas que no pertenecen a una colección también pueden heredar el layout.php del ancestro más cercano dentro del árbol pages. En las páginas de colección, el diseño de la raíz de la colección se almacena en cada contenido sincronizado y se supervisa como parte de la huella de la página, por lo que los cambios en el diseño se aplican en la siguiente sincronización.

Diseños de renderizador

Un diseño también puede ser una entrada de renderizador, como layout.tsx para un renderizador que registra layouts: ["layout.tsx"]. Se encuentra en los mismos lugares que layout.php, y un layout.data.php opcional junto a él actúa como cargador de datos. Al renderizar, el renderizador recibe kind: "layout" y el contenido renderizado de la página como slot, con la misma prioridad the_content que layout.php. Un directorio puede contener layout.php o un diseño de renderizador, pero no ambos; si contiene los dos, se produce un error de descubrimiento. Si falla un diseño, se activa blockstudio/pages/layout_error y el contenido de la página queda sin envolver, igual que con layout.php.

Modo de edición de bloques

La propiedad blockEditingMode controla cómo se pueden editar los bloques en el editor. Establece un valor predeterminado para la página en page.json y anúlalos por elemento en la plantilla:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
Valor Descripción
"default" Edición completa. Se pueden seleccionar, mover y editar los bloques.
"contentOnly" Solo edición de texto. El texto de los bloques se puede editar, pero la configuración y la estructura están bloqueadas.
"disabled" Sin edición. Los bloques son completamente inactivos.

Las anulaciones por elemento se establecen como atributos HTML en cualquier elemento (<h1>, <p>, <div>, etc.) o en elementos <block>. Los bloques contenedores antecesores de los elementos anulados se establecen automáticamente en contentOnly para que sus elementos secundarios sigan siendo accesibles. Esta cascada sube desde el elemento anulado hasta la raíz de la página, así que solo tienes que establecer blockEditingMode en los elementos que quieras hacer editables.

Bloqueo de plantilla

La propiedad templateLock controla cómo pueden editar los usuarios la página en el editor:

Valor Añadir/eliminar Mover Editar contenido
"all" No No No
"insert" No Sí Sí
"contentOnly" No No Sí
false Sí Sí Sí

Cuando se establece un templateLock, Blockstudio desactiva la posibilidad de desbloquear bloques mediante el UI del editor.

Rutas virtuales

Algunos documentos no tienen un contenido asociado: una referencia de componentes generada a partir de datos, un catálogo o un área de cuenta. Regístralos como rutas virtuales en lugar de gestionar template_redirect por tu cuenta:

PHP
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

La ruta es relativa a la página de inicio del sitio. Con prefix, la ruta también sirve todas las rutas que cuelgan de ella, y match recibe el resto de la ruta (una cadena vacía para la propia ruta) y devuelve el valor que recibe la función de devolución de llamada de representación, o null para dejar que URL gestione WordPress, que luego responde con 404 como de costumbre. La función de devolución de llamada de representación muestra el documento o lo devuelve como cadena; title es una cadena o un cierre que recibe el valor coincidente.

Para una solicitud coincidente, Blockstudio impide que WordPress la marque como 404 y que redirect_canonical la redirija, borra el estado de página individual que indica la consulta principal, envía el estado (status, 200 de forma predeterminada) y representa con prioridad Virtual_Routes::PRIORITY en template_redirect. Esto ocurre justo después de que el búfer de salida de Blockstudio se abra en Assets::BUFFER_PRIORITY, de modo que el documento final recibe los recursos de sus bloques, los recursos agrupados de UI y el Tailwind compilado como cualquier página, y antes de redirect_canonical en prioridad 10. Un controlador que representa un documento completo por sí mismo también debe ejecutarse después de Assets::BUFFER_PRIORITY; de lo contrario, se omite ese procesamiento. Las rutas de urls (de forma predeterminada, la propia ruta de la ruta virtual cuando no es una ruta de prefijo) se añaden a las compilaciones de prerrepresentación estática], y Virtual_Routes::urls() las devuelve como URL absolutas para un mapa del sitio. Virtual_Routes::match( $path ) resuelve una ruta del mismo modo que lo haría una solicitud.

Comportamiento de sincronización

Las publicaciones de página solo cambian mediante una operación de sincronización explícita:

Shell
wp bs pages sync

El comando detecta el inventario completo de fuentes, crea o actualiza las publicaciones modificadas, elimina los huérfanos confirmados, actualiza la configuración de enrutamiento de colecciones y de templateFor compilado, e informa de los cambios. Añade --authoritative para reemplazar el contenido administrado en lugar de conservar el contenido del editor asociado a claves, y --full para informar la ejecución como una reconciliación completa independientemente de la identidad de fuente almacenada:

Shell
wp bs pages sync --authoritative --full

Las solicitudes normales del frontend, el administrador, AJAX, REST, cron y el arranque genérico de WP-CLI no realizan la detección completa de páginas, no consultan el inventario de reconciliación administrado ni escriben publicaciones de página. Usan publicaciones WordPress ya sincronizadas, junto con la configuración compacta de colecciones y plantillas de tipo de contenido guardada en la última operación explícita. Una instalación nueva o una actualización pueden analizar los manifiestos de colección una vez para restaurar los metadatos de enrutamiento; ese arranque de solo lectura nunca sincroniza el contenido. El endpoint de actualización de Canvas autenticado y opcional es una API explícita de autoría: Canvas lo llama una vez al abrirse el espacio de trabajo para que las fuentes nuevas o modificadas aparezcan en el inventario inicial. El modo en vivo llama al mismo punto cuando detecta un cambio en la fuente de una página.

Blockstudio\Pages::init() ahora solo registra hooks en tiempo de solicitud. Las integraciones que antes pasaban un argumento force a ese método deben llamar a Blockstudio\Pages::reconcile() o ejecutar wp bs pages sync en su lugar.

Para evitar que una página se sobrescriba tras realizar ediciones manuales, establece "sync": false en page.json.

Ubicaciones portátiles de origen

Los archivos de tema sincronizados se almacenan como ubicaciones relativas al tema, en lugar de rutas de instalación absolutas. Los archivos del tema hijo y del tema padre conservan identidades distintas, incluso cuando tienen el mismo nombre de archivo relativo. Los asistentes de página siguen devolviendo valores template_path, content_path, layout_path y directory absolutos ya resueltos para la solicitud actual.

Esto permite que la sincronización de CLI y las solicitudes web usen raíces del sistema de archivos distintas, como en un alojamiento con acceso restringido, sin interrumpir las respuestas de Markdown, los diseños, el análisis del editor de Tailwind ni el seguimiento del código fuente prerenderizado. Las rutas absolutas de temas existentes se vuelven a asignar al leer si el nombre del directorio del tema no ha cambiado. No se requiere sincronización, migración de base de datos ni escritura de metadatos durante las solicitudes para leerlas; la siguiente sincronización explícita guarda las ubicaciones portátiles.

Un directorio de tema que sea un enlace simbólico, por ejemplo, a una copia de desarrollo, guarda las mismas ubicaciones de theme: tanto si el código fuente se lee mediante el enlace simbólico como si se lee mediante su destino, y las resuelve en el directorio de tema configurado.

Los archivos fuera de los temas secundarios y principales activos siguen siendo compatibles en sus rutas absolutas configuradas, sujetos a las restricciones de PHP open_basedir. No se pueden reubicar automáticamente: después de mover un origen externo, actualice su ruta configurada y ejecute una sincronización explícita.

Propiedad de los campos de las publicaciones

postStatus establece el estado inicial. Las sincronizaciones posteriores conservan los estados de borrador, pendiente, privado, publicado y programado existentes, también con --authoritative. Una publicación en borrador no vuelve a publicarse solo porque su archivo indique postStatus: "publish". El comportamiento existente de recuperación de elementos huérfanos no cambia: una sincronización explícita restaura una publicación administrada que se haya enviado a la papelera cuando su origen está presente. Bloquee la página o desactive la sincronización para evitar esa restauración.

El archivo sigue siendo la fuente de verdad para el título, el slug, el tipo de publicación, la página superior y el orden de menú configurado. Editarlos en WordPress no cambia la definición del origen. La siguiente sincronización explícita vuelve a aplicar los valores del archivo y enumera los campos afectados en pages.<name>.overwritten, con una advertencia en la salida de tabla de CLI. Siguen aplicándose los permisos nativos de WordPress, incluido su slug vacío para publicaciones pendientes cuando el usuario que sincroniza no puede publicarlas.

Use blockstudio/pages/update_post_data para una integración que gestione explícitamente una política de estado distinta. Los bloques con clave conservan el contenido de los bloques gestionado por el editor; las claves no cambian quién gestiona el título ni el slug de la publicación.

En las páginas de colección, las huellas abarcan el manifiesto, el cargador, la fuente de la página, el archivo de diseño, los metadatos y las rutas de origen relacionadas. La siguiente sincronización explícita aplica los cambios en esas entradas.

Cuando se elimina una fuente de colección, Blockstudio elimina la página generada para que las páginas antiguas de la colección no permanezcan tras borrar el archivo de origen. De forma predeterminada, las páginas de colección huérfanas se mueven a la papelera. Usa blockstudio/pages/orphan_action para devolver trash, delete o keep.

En las solicitudes del frontend, Blockstudio hidrata el registro de páginas a partir de las publicaciones publicadas ya sincronizadas. Las páginas en borrador y privadas están disponibles en el administrador y en los contextos de sincronización, pero los ayudantes del frontend solo hidratan páginas publicadas.

Reconciliación de despliegue

Blockstudio\Pages::reconcile() es el punto de entrada de despliegue de PHP. Detecta el inventario deseado completo, compara las huellas de las fuentes y del motor de sincronización, y devuelve un informe legible por máquina:

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
  'renames' => [
    [
      'from' => 'pages/old/index.php',
      'to' => 'pages/new/index.php',
    ],
  ],
]);

El informe contiene discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, resultados por página, errores de detección y un sourceIdentity determinista.

Las páginas bloqueadas tienen status: "locked" y se cuentan por separado de las páginas sin cambios. removedPages enumera el name, key, postId y el action real de cada página eliminada (trash o delete); las publicaciones conservadas o que ya estaban en la papelera no se cuentan como recién eliminadas. La salida de tabla de CLI también enumera las páginas creadas, actualizadas, bloqueadas, eliminadas y con contenido conservado, junto con sus IDs de publicación.

Tras analizar y combinar los bloques con clave, si la publicación final es idéntica, no se llama a wp_update_post(), no se modifica post_modified, no se crea una revisión ni se activan los hooks de actualización de publicaciones. El resultado es unchanged. Cuando el contenido del origen difiere del contenido de bloques con clave gestionado por el editor, preserved: true identifica esa decisión y el recuento de nivel superior de preserved la incluye. Aun así, se registran la nueva huella del origen y los metadatos de gestión para que la siguiente sincronización sin cambios no haga nada. preserved es una marca adicional, no un estado exclusivo: una página puede conservar el contenido de bloques con clave y, al mismo tiempo, actualizar un título gestionado por el archivo o añadir otro bloque.

authoritative: true puede eliminar un bloqueo de Page Sync y reemplaza el contenido por la definición del archivo en lugar de conservar el contenido del editor asociado a claves. Déjalo false para una sincronización explícita normal. plan_valid: false, full: true, broad: true, la ausencia de una identidad de fuente anterior o un cambio en la huella del motor de sincronización marcan la ejecución como una reconciliación completa (fullReconciliation en el informe). En cualquier caso, cada ejecución compara el inventario completo. Los registros de cambio de nombre Git solo son pistas de identidad. Nunca sustituyen la comparación del inventario completo.

Las huellas idénticas con rutas de ejecución sin cambios no generan escrituras en la publicación ni en los metadatos de la publicación, y tampoco activan hooks de actualización. Cuando una fuente sin cambios se traslada a un nuevo directorio de versión, la reconciliación solo actualiza sus rutas persistidas de plantilla, contenido, diseño y directorio; no actualiza post_content ni la marca de tiempo de modificación de la publicación. Las páginas administradas que falten solo se eliminan tras finalizar la reconciliación completa sin errores de detección ni de escritura de páginas.

La reconciliación directa de API no marca un despliegue como exitoso. Después de activar y verificar el artefacto estático y las rutas correspondientes, guarda explícitamente la identidad devuelta:

PHP
Blockstudio\Pages::store_successful_source_identity(
  $report['sourceIdentity']
);

wp bs pages sync guarda la identidad devuelta tras una ejecución exitosa. El arranque normal de WP-CLI solo registra los tipos de contenido y las reglas de reescritura de colecciones persistidos. No detecta ni sincroniza páginas.

Fijación del ID de publicación

De forma predeterminada, WordPress asigna automáticamente los ID de publicación. Si se elimina y se vuelve a crear una página, cambia su ID, lo que rompe referencias externas como los menús o los enlaces codificados de forma fija.

Usa postId para fijar una página a un ID específico:

JSON
{
  "name": "about",
  "title": "About Us",
  "postId": 42
}

Al crear la página, Blockstudio pasa el ID a WordPress mediante import_id. Si el ID está disponible, WordPress lo usa tal cual. Si ya está asignado a una publicación no relacionada, WordPress asigna silenciosamente un ID nuevo de forma automática.

Al buscar páginas existentes, Blockstudio comprueba primero el ID fijado, antes que los metadatos o el slug. Así, si se elimina y se vuelve a sincronizar una página, recupera el mismo ID.

Combinación de bloques con claves

De forma predeterminada, cuando cambia un archivo de plantilla, Blockstudio reemplaza todo el contenido de la publicación por la nueva plantilla. Esto significa que se pierden todas las ediciones realizadas en el editor WordPress.

Añade un atributo key a los bloques para conservar las ediciones de los usuarios entre sincronizaciones de plantillas. Cuando una plantilla contiene bloques con claves, Blockstudio combina los cambios de la plantilla con el contenido existente de la publicación en lugar de reemplazarlo.

Añadir claves

Usa el atributo key en cualquier elemento HTML o elemento <block>:

HTML
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>

<div key="features">
  <p>First feature.</p>
  <p>Second feature.</p>
</div>

<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h2>Hero Title</h2>
  <p>Hero description.</p>
</block>

<block
  name="acme/testimonial"
  key="featured-quote"
  quote="Default quote"
/>

Las claves deben ser únicas en toda la plantilla. Una clave protege el bloque completo y todo su contenido. No necesitas asignar claves a cada elemento secundario dentro de un elemento principal con clave. Los bloques con claves se pueden mover a cualquier posición o nivel de anidación entre actualizaciones de la plantilla, y su contenido de usuario se conservará.

Las claves funcionan igual en los bloques personalizados Blockstudio. key son metadatos estructurales de Page Sync; los valores de los campos personalizados siguen siendo atributos Blockstudio normales. Cuando un editor cambia esos campos, una sincronización posterior de la plantilla conserva los valores del editor y aplica a la vez los cambios independientes de la plantilla. Las páginas creadas con versiones anteriores que tengan la clave dentro de los datos del campo personalizado se migran automáticamente en la siguiente sincronización.

Cómo funciona la combinación

Cuando cambia un archivo de plantilla y se vuelve a sincronizar la página:

Bloque Comportamiento
Bloque con clave Se conservan el contenido del usuario y los valores de campo Blockstudio. Se aplican los atributos y la estructura controlados por la plantilla.
Bloque sin clave Se reemplaza por completo con la versión de la plantilla (igual que si no hubiera claves).

Ejemplos

Se conservan las ediciones del usuario en los bloques con clave:

  1. La plantilla define <p key="intro">Default intro.</p>
  2. El usuario edita el párrafo en el editor y escribe «Texto de introducción personalizado».
  3. El desarrollador actualiza la plantilla, añade un bloque nuevo y cambia el diseño.
  4. Al sincronizar: el párrafo conserva «Texto de introducción personalizado» y se aplica el diseño nuevo.

Los atributos de la plantilla siguen aplicándose:

  1. La plantilla tiene un bloque de portada con key="hero" y un atributo url.
  2. El desarrollador cambia el atributo url de la portada por una imagen de fondo nueva.
  3. Al sincronizar: se aplica la imagen de fondo nueva, pero se conservan las ediciones de contenido del usuario dentro de la portada.

Casos límite

Situación Comportamiento
Se añade un bloque nuevo con clave a la plantilla Aparece con el contenido predeterminado de la plantilla.
Se elimina de la plantilla un bloque con clave Se elimina de la publicación.
Cambia el tipo de bloque (misma clave) Prevalece por completo la plantilla; no se combina el contenido.
Claves duplicadas La segunda aparición se trata como si no tuviera clave.
La plantilla no contiene claves Se reemplaza todo el contenido (igual que si no hubiera claves).
Sincronización forzada Se reemplaza todo el contenido; se ignoran las claves.
Publicación bloqueada No se sincroniza.

Combinación con controles de edición

Las claves, templateLock y blockEditingMode se combinan para darte un control detallado sobre lo que tus clientes pueden hacer. Estos son algunos patrones de flujo de trabajo habituales.

Página completamente bloqueada

El desarrollador lo controla todo. La página es un diseño estático que los clientes no pueden modificar. Es útil para páginas legales, condiciones del servicio o cualquier página que solo deba cambiar mediante código.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>

No se necesitan claves. La plantilla es la única fuente de verdad. Cada sincronización sobrescribe por completo la página.

Diseño bloqueado con contenido editable

Es el patrón más habitual. Bloquea la estructura de la página para que los clientes no puedan añadir, quitar ni reorganizar bloques, pero permite que editen el texto en lugares específicos. Las claves hacen que sus ediciones se conserven al actualizar la plantilla.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Title</h1>
  <p blockEditingMode="contentOnly">Edit this description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">Contact Us</block>
</block>

El cliente puede editar el título principal, la descripción y la introducción de las características. Nada más. El texto del botón, URL y la imagen de fondo de portada están controlados por el desarrollador. Cuando el desarrollador actualiza la plantilla (e.g., añade un segundo botón), las secciones con clave conservan el texto del cliente.

Plantilla evolutiva con contenido preservado

Para páginas que crecen con el tiempo. El desarrollador añade secciones nuevas a la plantilla y cada sincronización incorpora el contenido nuevo sin tocar lo que el cliente ya personalizó.

HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
<div key="testimonials">
  <h2>Testimonials</h2>
  <p>What our clients say.</p>
</div>
<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
</block>

La nueva sección de testimonios y el botón aparecen al sincronizar. Las ediciones del cliente al título, la introducción y los servicios quedan intactas.

Estructura inicial de una sola vez

Cree una página con una estructura inicial y luego entréguela por completo. Configure sync como false para que la sincronización normal nunca cree ni actualice la página, y créela una vez con Blockstudio\Pages::force_sync('blog'). Después, el cliente será dueño absoluto de la página.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>

wp bs pages sync omite esta página, así que force_sync() la crea una vez. Después, el cliente puede añadir, eliminar y reorganizar bloques libremente. Los cambios en la plantilla se ignoran.

Enlaces de bloques

Una alternativa a la combinación por clave es usar WordPress las Vinculaciones de bloquesAPI de core para conectar bloques con los metadatos de las entradas. Esta no es una función de Blockstudio, sino una WordPress API nativa. Blockstudio simplemente pasa el atributo metadata al marcado generado del bloque. El contenido reside en los metadatos de la entrada en lugar de en el marcado del bloque, así que la sincronización de plantillas puede sobrescribir libremente el marcado, ya que el editor lee los metadatos, no innerHTML.

Pase el atributo metadata a cualquier elemento HTML o elemento <block>:

HTML
<h1
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
  Default Title
</h1>

<p
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
  Default description text.
</p>

<img
  metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>

Las claves de metadatos deben registrarse con show_in_rest habilitado:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest'  => true,
    'single'        => true,
    'type'          => 'string',
    'default'       => 'Default Title',
) );

Claves frente a enlaces

Aspecto Claves Enlaces
Contenido almacenado en Marcado del bloque (post_content) Metadatos de la entrada (wp_postmeta)
Se conserva al sincronizar la plantilla Sí (combinado por clave) Sí (los datos residen en los metadatos)
Se puede consultar mediante WP_Query No Sí (meta_query)
Disponible en REST API No Sí
Requiere registro No Sí (register_post_meta)
El usuario puede mover bloques No (la plantilla vuelve a imponer la estructura) No (la plantilla vuelve a imponer la estructura)

Ambos enfoques pueden usarse en la misma plantilla. Use claves para las secciones donde importa la estructura del bloque (e.g., un grupo con varios elementos secundarios). Use enlaces para campos individuales cuando también quiera que los datos estén disponibles fuera del editor de bloques.

Plantillas de tipos de contenido

Use templateFor para establecer una página como plantilla predeterminada de un tipo de contenido:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}

Todas las entradas nuevas de ese tipo comenzarán con la estructura de bloques definida.

Rutas personalizadas

De forma predeterminada, Blockstudio busca en get_template_directory() . '/pages'. Añada otras rutas con el filtro:

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

Las integraciones de ejecución que componen archivos desde varias raíces pueden reemplazar la búsqueda del sistema de archivos por una fuente de descubrimiento lógica. Los manifiestos de páginas, diseños, cargadores y plantillas de origen se resuelven entonces por ruta lógica, incluso si los archivos seleccionados se encuentran en distintas raíces.

Filtros y acciones

El descubrimiento de páginas, la sincronización y el enrutamiento de colecciones ofrecen estos puntos de extensión:

Hook Tipo Descripción
blockstudio/pages/paths Filtro Añade directorios en los que Blockstudio busca orígenes de páginas.
blockstudio/pages/collection_post_type_args Filtro Ajusta los argumentos de register_post_type() para un CPT de colección.
blockstudio/pages/template_candidates Filtro Ajusta los nombres de archivo de plantilla que se consideran para un origen de página.
blockstudio/pages/serve_markdown Filtro Activa o desactiva las respuestas sin procesar de Markdown.
blockstudio/pages/orphan_action Filtro Devuelve trash, delete o keep para la limpieza de elementos huérfanos.
blockstudio/pages/docs_allowed_html Filtro Ajusta los HTML permitidos para el contenido generado de documentación de Markdown.
blockstudio/pages/allow_external_loader_path Filtro Permite que el cargador paths quede fuera de la raíz de la colección.
blockstudio/pages/manifest_scan_interval Filtro Establece la antigüedad máxima de una caché de manifiesto heredada anterior a 7.6.2 que puede servir para inicializar la configuración persistente del entorno de ejecución durante una actualización.
blockstudio/pages/create_post_data Filtro Modifica los datos de la publicación antes de crear una página sincronizada.
blockstudio/pages/update_post_data Filtro Modifica los datos de la publicación antes de actualizar una página sincronizada.
blockstudio/pages/sync_engine_inputs Filtro Añade una versión de analizador, mapeo o migración que amplíe deliberadamente la reconciliación una vez.
blockstudio/pages/post_created Acción Se ejecuta después de crear una publicación de página sincronizada.
blockstudio/pages/post_updated Acción Se ejecuta después de actualizar una publicación de página sincronizada.
blockstudio/pages/synced Acción Se ejecuta después de que el registro de páginas termine de sincronizarse.
blockstudio/pages/reconciled Acción Se ejecuta después de una reconciliación explícita y recibe su informe legible por máquinas.
blockstudio/pages/renderers Acción Registra los renderizadores de páginas con Blockstudio\Page_Renderers::register(). Se ejecuta una vez por solicitud.
blockstudio/pages/rendered Acción Se ejecuta después de renderizar una página de componente y recibe la página, su HTML y sus dependencias.
blockstudio/pages/layout_error Acción Se ejecuta cuando no se puede renderizar un diseño y recibe el error, la ruta del diseño y la página.

PHP API

PHP
// Get all registered pages.
$pages = Blockstudio\Pages::pages();

// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');

// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');

// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');

// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');

// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');

// Get a specific page.
$page = Blockstudio\Pages::get_page('about');

// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');

// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');

// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();

// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);

// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');

// Unlock a page.
Blockstudio\Pages::unlock('about');

// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
  'extensions' => ['tsx'],
  'layouts' => ['layout.tsx'],
  'render' => 'my_theme_render_page',
]);

// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');

// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);

Consulte Conciliación del despliegue para ver la semántica de los argumentos, los campos del informe y el límite de identidad de origen verificado.

Las funciones auxiliares globales están disponibles para plantillas y diseños:

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

Los arrays de páginas devueltos por Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() y las funciones auxiliares globales incluyen la identidad de la entrada sincronizada, las rutas de origen y plantilla, los metadatos de colección y ruta, el tipo de contenido, la política de sincronización, el tipo y el estado de la entrada, la política de edición, los metadatos personalizados y una clave permalink. Los metadatos de colección se cargan desde la última conciliación explícita completada correctamente. Las solicitudes normales reconstruyen estos datos de ejecución a partir de la configuración persistida y los metadatos de las entradas sincronizadas, sin leer los árboles de origen de las páginas. La clase Pages no ofrece un método independiente para los enlaces permanentes.

Creación de páginas basadas en archivos

Bloqueo de plantillas, modos de edición de bloques, combinación por claves y control de lo que los clientes pueden editar.