Saltar al contenido

Crear un sitio de documentación

La documentación debe estar junto al código que describe. Quienes escriben prefieren Markdown; quienes revisan quieren ver los cambios en una solicitud de incorporación, y cada lanzamiento debería incluir la documentación en la misma confirmación. WordPress, por otro lado, necesita entradas en la base de datos: ahí están la búsqueda, los enlaces permanentes, las revisiones y el editor.

Blockstudio conecta ambos mundos mediante colecciones de páginas. Una carpeta de archivos Markdown se convierte en un conjunto de entradas WordPress reales con su propio tipo de contenido, una base de URL y una jerarquía de páginas principales y secundarias. Un archivo layout.php envuelve cada página de la colección con navegación creada a partir de los mismos datos. Los archivos siguen siendo la fuente principal y un comando de sincronización explícito los escribe en la base de datos.

Esta guía crea paso a paso una pequeña sección de documentación para un tema llamado acme: un manifiesto, páginas Markdown, un cargador que genera un registro de cambios, la sincronización y un diseño con barra lateral y enlaces a las páginas anterior y siguiente.

Lo que crearás

Código
theme/
└── pages/
    └── docs/
        ├── pages.json
        ├── layout.php
        ├── loader.php
        ├── index.md
        ├── getting-started.md
        ├── data/
        │   └── releases.json
        └── guide/
            ├── index.md
            ├── install.md
            └── configure.md

Después de sincronizar, la colección ofrece estas URL:

Fuente URL público
index.md /docs/
getting-started.md /docs/getting-started/
guide/index.md /docs/guide/
guide/install.md /docs/guide/install/
guide/configure.md /docs/guide/configure/
entrada del cargador /docs/changelog/

Paso 1: El manifiesto de la colección

Una colección es una carpeta dentro de pages/ que contiene un manifiesto pages.json. Crea pages/docs/pages.json:

JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "acme_docs",
  "postTypeArgs": {
    "label": "Docs"
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}

collection es el slug de la colección y se convierte en la base pública de URL. postType asigna cada página de la colección a un tipo de contenido propio para que la documentación no se mezcle con las páginas normales en el administrador. Si ese tipo aún no existe, Blockstudio lo registra. De forma predeterminada, el registro es público y jerárquico, está disponible en el REST API, admite título, editor, atributos de página, imagen destacada, extracto y revisiones, y usa el slug de la colección como slug de reescritura. postTypeArgs se combina con esos valores predeterminados, así que este manifiesto solo cambia la etiqueta del administrador.

defaults aplica propiedades de página a todas las páginas de la colección. Aquí, cada página se publica al sincronizar y se limita a la edición del contenido, para que quienes editan puedan corregir una errata en el editor, pero no cambiar la estructura definida por Markdown.

Paso 2: Escribir las páginas en Markdown

Dentro de una colección, cada archivo Markdown es una página. La ubicación del archivo determina su identidad, así que los metadatos iniciales son opcionales. Úsalos para el título, el orden y cualquier otro dato que quieras consultar más adelante.

Markdown
---
title: Introduction
order: 0
description: What Acme does and where to start.
---

# Introduction

Acme is a toolkit for building fast WordPress sites.
Start with [Getting Started](/docs/getting-started/).
Markdown
---
title: Getting Started
order: 10
---

# Getting Started

Install the theme, then activate it under **Appearance > Themes**.

```bash
wp theme activate acme
```

La sección de la guía es una carpeta con su propio index.md, que se convierte en la página principal de las páginas que contiene:

Markdown
---
title: Guide
order: 20
---

# Guide

Task-focused walkthroughs for everyday work.
Markdown
---
title: Installation
order: 10
---

# Installation

| Requirement | Version |
| --- | --- |
| WordPress | 6.7+ |
| PHP | 8.2+ |
Markdown
---
title: Configuration
order: 20
---

# Configuration

Settings live in `acme.json` at the theme root.

> Changes apply on the next deploy.

Blockstudio obtiene una ruta lógica y el nombre de una página de cada archivo:

Archivo Ruta Nombre de página
index.md . docs-home
getting-started.md getting-started docs-getting-started
guide/index.md guide docs-guide
guide/install.md guide/install docs-guide-install

guide/install.md y guide/install/index.md generan la misma ruta, así que después puedes alternar entre un archivo plano y una carpeta sin cambiar URL.

order ordena las páginas hermanas y se guarda como orden de menú de la entrada. Las páginas sin orden aparecen después de las ordenadas y, luego, se ordenan por título. Las claves de los metadatos iniciales que Blockstudio no reconoce, como description arriba, se conservan en la matriz meta de la página.

Durante la sincronización, Markdown se procesa como GitHub Flavored Markdown, se convierte a HTML y luego se transforma en bloques nativos. La entrada almacenada contiene bloques, no el texto Markdown. Los encabezados reciben un ancla estable, las tablas se convierten en core/table, las citas en bloque se convierten en core/quote y el código cercado en un bloque core/preformatted que conserva la clase del lenguaje. Este es el contenido almacenado de la página de instalación, sin espacios sobrantes:

HTML
<!-- wp:heading {"level":1,"anchor":"installation"} --><h1 id="installation" class="wp-block-heading">Installation</h1><!-- /wp:heading -->
<!-- wp:table --><figure class="wp-block-table"><table>
<thead><tr><th>Requirement</th><th>Version</th></tr></thead>
...
</table></figure><!-- /wp:table -->

Paso 3: Generar páginas con un cargador

Algunas páginas conviene generarlas en lugar de escribirlas. Un registro de cambios es un buen ejemplo: los datos de las versiones ya existen, y copiarlos a mano en Markdown puede provocar diferencias. Una colección puede incluir un loader.php que devuelva definiciones de páginas adicionales.

Guarda los datos de las versiones en la colección:

JSON
[
  { "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
  { "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]

Después, crea una página Markdown a partir de ellos:

PHP
<?php
$releases = json_decode(
	(string) file_get_contents( __DIR__ . '/data/releases.json' ),
	true
);

$markdown = "# Changelog\n";

foreach ( $releases as $release ) {
	$markdown .= "\n## {$release['version']}\n\n";
	$markdown .= "Released {$release['date']}. {$release['notes']}\n";
}

return array(
	'pages' => array(
		array(
			'name'        => 'docs-changelog',
			'title'       => 'Changelog',
			'path'        => 'changelog',
			'order'       => 90,
			'content'     => $markdown,
			'contentType' => 'markdown',
		),
	),
);

El cargador se ejecuta durante el descubrimiento y la sincronización explícitos, nunca al mostrar una página normal. Procura que sea determinista y local: leer un archivo del tema está bien, pero obtener un API remoto no, porque la sincronización dependería de que el servicio estuviera disponible.

Las páginas del cargador se marcan como generadas. Si una entrada desaparece del resultado del cargador, la siguiente sincronización considera que su entrada está huérfana y la gestiona mediante el filtro blockstudio/pages/orphan_action, que por defecto la mueve a la papelera.

Un cargador también puede devolver paths para incluir otras carpetas locales de Markdown en la colección, con un prefijo opcional. Las carpetas fuera de la raíz de la colección requieren el filtro blockstudio/pages/allow_external_loader_path. Consulta Cargadores de colecciones para ver todos los detalles.

Paso 4: Sincronizar

No se escribe nada en la base de datos hasta que lo solicites:

Shell
wp bs pages sync

El comando descubre todas las fuentes de páginas, registra el tipo de contenido de la colección acme_docs, crea o actualiza las entradas e imprime una fila de resumen con los recuentos de discovered, created, updated, unchanged, removed y failed. Si lo vuelves a ejecutar sin cambios, todas las páginas figuran como sin cambios y no se escribe ninguna entrada. Añade --format=json si un script de despliegue necesita el informe completo.

Después de sincronizar, las entradas reflejan el árbol de archivos. guide/install es una página secundaria de guide, que a su vez depende de la raíz de la colección, y el orden de menú de cada entrada es el order de sus metadatos iniciales. Las URL de la colección combinan el slug de esta con la ruta lógica de cada página:

Código
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/

No hace falta volver a guardar los enlaces permanentes. Las reglas de reescritura de la colección se actualizan automáticamente cuando cambian los tipos de contenido registrados para la colección.

Incluye la sincronización en tu despliegue. Las solicitudes del frontend y del administrador nunca descubren páginas, así que si un despliegue copia archivos Markdown nuevos sin ejecutar wp bs pages sync, seguirá mostrando el contenido anterior.

Paso 5: El diseño

Las entradas ya existen, pero cada una se muestra con la plantilla individual habitual del tema y sin navegación. Un archivo layout.php junto a pages.json envuelve la representación en el frontend de cada página de la colección:

PHP
<?php
$current = blockstudio_current_page();
$tree    = blockstudio_page_tree( 'docs' );

// Flatten the tree in reading order for previous and next links.
$flat    = array();
$flatten = function ( array $nodes ) use ( &$flatten, &$flat ) {
	foreach ( $nodes as $node ) {
		$flat[] = $node;
		$flatten( $node['children'] );
	}
};
$flatten( $tree );

$keys     = array_column( $flat, 'key' );
$position = array_search( $current['key'] ?? null, $keys, true );
$previous = false !== $position ? ( $flat[ $position - 1 ] ?? null ) : null;
$next     = false !== $position ? ( $flat[ $position + 1 ] ?? null ) : null;

$render_nav = function ( array $nodes ) use ( &$render_nav, $current ) {
	echo '<ul>';
	foreach ( $nodes as $node ) {
		$is_current = ( $node['key'] ?? null ) === ( $current['key'] ?? null );
		printf(
			'<li><a href="%s"%s>%s</a>',
			esc_url( $node['permalink'] ?? '#' ),
			$is_current ? ' aria-current="page"' : '',
			esc_html( $node['title'] )
		);
		if ( array() !== $node['children'] ) {
			$render_nav( $node['children'] );
		}
		echo '</li>';
	}
	echo '</ul>';
};
?>
<div class="docs">
	<nav class="docs-sidebar" aria-label="Documentation">
		<?php $render_nav( $tree ); ?>
	</nav>

	<article class="docs-content">
		<?php echo blockstudio_page_content(); ?>

		<nav class="docs-pager" aria-label="Previous and next">
			<?php if ( $previous ) : ?>
				<a rel="prev" href="<?php echo esc_url( $previous['permalink'] ?? '#' ); ?>">
					<?php echo esc_html( $previous['title'] ); ?>
				</a>
			<?php endif; ?>
			<?php if ( $next ) : ?>
				<a rel="next" href="<?php echo esc_url( $next['permalink'] ?? '#' ); ?>">
					<?php echo esc_html( $next['title'] ); ?>
				</a>
			<?php endif; ?>
		</nav>
	</article>
</div>

blockstudio_page_tree('docs') devuelve la colección como nodos anidados, ordenados por order y luego por título, con los nodos secundarios de cada uno en children. Aquí hay una raíz, la página de introducción, y las demás páginas aparecen debajo. Cada nodo incluye key, title, path y permalink. Al aplanar el árbol en ese orden se obtiene la secuencia de lectura que necesitan los enlaces a las páginas anterior y siguiente.

blockstudio_page_content() imprime el cuerpo de la página que WordPress generaría mediante the_content. Si se omite, el contenido queda oculto. En /docs/guide/install/ de un sitio en https://example.com, el diseño genera lo siguiente (recortado):

HTML
<nav class="docs-sidebar" aria-label="Documentation">
  <ul><li><a href="https://example.com/docs/">Introduction</a><ul>
    <li><a href="https://example.com/docs/getting-started/">Getting Started</a></li>
    <li><a href="https://example.com/docs/guide/">Guide</a><ul>
      <li><a href="https://example.com/docs/guide/install/" aria-current="page">Installation</a></li>
      <li><a href="https://example.com/docs/guide/configure/">Configuration</a></li>
    </ul></li>
    <li><a href="https://example.com/docs/changelog/">Changelog</a></li>
  </ul></li></ul>
</nav>
...
<a rel="prev" href="https://example.com/docs/guide/">Guide</a>
<a rel="next" href="https://example.com/docs/guide/configure/">Configuration</a>

El diseño solo se aplica a solicitudes del frontend para páginas individuales dentro del bucle principal. No cambia el post_content almacenado ni envuelve el lienzo del editor. Su ruta se guarda en cada entrada sincronizada y forma parte de la huella de la página, así que los cambios en el diseño se aplican en la siguiente sincronización.

Leer los datos de la colección en PHP

Los asistentes de diseño son envoltorios ligeros de la clase Blockstudio\Pages. Puedes usar cualquiera de las dos formas en plantillas, bloques o plugins:

Ayudante Método de clase Devuelve
blockstudio_pages('docs') Pages::pages('docs') Lista plana de las páginas de la colección, ordenadas y agrupadas por clave de página
blockstudio_page_tree('docs') Pages::tree('docs') Nodos anidados con children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Hijos directos de una página
blockstudio_page_collection('docs') Pages::collection('docs') Datos de la colección del manifiesto
blockstudio_current_page() Pages::current_page() La página que se está renderizando, o null
Pages::get_page('docs-guide-install') Una página por nombre

Los arrays de páginas incluyen los elementos sincronizados post_id, permalink, name, key, title, path, order, collection, postType y el array meta. Los campos adicionales de la información preliminar terminan en meta, así que un diseño puede mostrar el resumen de la introducción:

PHP
<?php $summary = $current['meta']['description'] ?? ''; ?>

En las solicitudes del frontend, estas funciones leen las entradas ya sincronizadas y la configuración guardada en la última sincronización. Nunca leen los archivos Markdown, así que no realizan operaciones en el sistema de archivos. En el frontend solo están disponibles las páginas publicadas.

Markdown sin procesar para herramientas

Como las páginas proceden de archivos Markdown, Blockstudio también puede servir el código fuente original. Solicite una página con el sufijo .md, como /docs/guide/install.md, o envíe Accept: text/markdown a URL, la ruta normal. La respuesta omite la información preliminar e incluye un encabezado Link canónico que apunta de vuelta a la página HTML. Esto resulta útil para indexadores de búsqueda, asistentes y otras herramientas que leen texto sin formato. Las páginas generadas a partir del contenido de un cargador integrado no tienen un archivo de origen y, por tanto, no ofrecen una respuesta .md.

Desactívelo con un solo filtro:

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

Consejos

Deje que las rutas definan la estructura. Al mover un archivo, su ruta, su padre y URL se actualizan en la siguiente sincronización. Use path en la información preliminar solo cuando URL deba diferir de la ubicación del archivo.

Combine page.json con Markdown cuando una página necesite algo más. Una carpeta con page.json y index.md usa JSON para las propiedades de la página, como postId o templateLock, y Markdown para el contenido. La información preliminar de index.md prevalece sobre los valores coincidentes de page.json.

Edite los archivos, no en el editor. Con templateLock: "contentOnly", los editores pueden corregir el texto directamente, pero la siguiente sincronización de una fuente modificada vuelve a escribir el contenido almacenado a partir del archivo. Considere Markdown el lugar donde se redacta la documentación. Para que una página pertenezca a los editores, asígnele "sync": false en un page.json; las sincronizaciones normales la omitirán y Blockstudio\Pages::force_sync() la creará una vez.

Es seguro cambiar el tipo de entrada. Si una colección pasa de page a un tipo de entrada personalizado, las entradas ya sincronizadas se migran directamente cuando coincide su identidad almacenada, por lo que conservan sus ID.

Próximos pasos