Pular para o conteúdo

Criando um site de documentação

A documentação deve ficar junto ao código que descreve. Quem escreve prefere Markdown; quem revisa quer ver as alterações em uma solicitação de pull; e uma versão deve incluir a documentação no mesmo commit. WordPress, por outro lado, armazena as publicações no banco de dados: é lá que ficam a pesquisa, os links permanentes, as revisões e o editor.

As coleções de páginas Blockstudio conectam os dois. Uma pasta de arquivos Markdown se transforma em um conjunto de publicações WordPress reais, com tipo de publicação próprio, base URL e hierarquia de páginas pai e filhas. Um arquivo layout.php envolve cada página da coleção com navegação gerada a partir dos mesmos dados. Os arquivos continuam sendo a fonte da verdade, e um comando explícito de sincronização os grava no banco de dados.

Este guia ensina, passo a passo, a criar uma pequena seção de documentação para um tema chamado acme: um manifesto, páginas Markdown, um carregador que gera um registro de alterações, a sincronização e um layout com navegação lateral e links para a página anterior e a próxima.

O que você vai criar

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

Após a sincronização, a coleção disponibiliza estes URLs:

Fonte 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 do carregador /docs/changelog/

Etapa 1: O manifesto da coleção

Uma coleção é uma pasta dentro de pages/ que contém um manifesto pages.json. Crie pages/docs/pages.json:

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

collection é o identificador da coleção e se torna a base pública URL. postType direciona cada página da coleção para um tipo de publicação dedicado, para que a documentação não se misture às páginas comuns no admin. Se esse tipo de publicação ainda não existir, Blockstudio o registra. Por padrão, o registro é público e hierárquico, fica disponível no REST API, oferece suporte a título, editor, atributos de página, miniatura, resumo e revisões, e usa o identificador da coleção como slug de reescrita. postTypeArgs é mesclado com esses padrões; por isso, este manifesto altera apenas o rótulo do admin.

defaults aplica propriedades de página a todas as páginas da coleção. Neste exemplo, todas são publicadas durante a sincronização e ficam limitadas à edição apenas do conteúdo. Assim, os editores podem corrigir erros de digitação no editor, mas não podem reorganizar a estrutura definida por Markdown.

Etapa 2: Escrever as páginas em Markdown

Dentro de uma coleção, cada arquivo Markdown representa uma página. O local do arquivo fornece a identidade, então o frontmatter é opcional. Use-o para o título, a ordem de classificação e quaisquer dados adicionais que você queira ler depois.

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

A seção do guia é uma pasta com seu próprio index.md, que se torna a página pai das páginas ao lado:

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 deriva um caminho lógico e um nome de página de cada arquivo:

Arquivo Caminho Nome da 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 e guide/install/index.md geram o mesmo caminho; assim, mais tarde você pode alternar entre um arquivo simples e uma pasta sem alterar o URL.

order ordena as páginas irmãs e é gravado como a ordem do menu da publicação. Páginas sem ordem aparecem depois das páginas ordenadas e, em seguida, são classificadas pelo título. As chaves do frontmatter que Blockstudio não reconhece, como description acima, são mantidas na matriz meta da página.

Durante a sincronização, Markdown é analisado como GitHub Flavored Markdown, convertido para HTML e, em seguida, analisado em blocos nativos. A publicação armazenada contém blocos, não o texto Markdown. Os títulos recebem uma âncora estável, as tabelas se tornam core/table, as citações em bloco se tornam core/quote e o código entre cercas se torna um bloco core/preformatted que mantém a classe de linguagem. Este é o conteúdo armazenado da página de instalação (espaços em branco removidos):

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

Etapa 3: Gerar páginas com um carregador

Algumas páginas funcionam melhor quando geradas do que quando escritas. Um registro de alterações é um bom exemplo: os dados das versões já existem, e copiá-los manualmente para Markdown pode causar divergências. Uma coleção pode incluir um loader.php que retorna definições adicionais de páginas.

Mantenha os dados das versões na coleção:

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

Em seguida, gere uma página Markdown a partir deles:

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',
		),
	),
);

O carregador é executado durante a descoberta e a sincronização explícitas, nunca durante a visualização normal de uma página. Mantenha-o determinístico e local: ler um arquivo no tema é aceitável, mas buscar um API remoto não é, pois a sincronização dependeria da disponibilidade desse serviço.

As páginas do carregador são marcadas como geradas. Se uma entrada desaparecer da saída do carregador, na próxima sincronização sua publicação será tratada como órfã e processada pelo filtro blockstudio/pages/orphan_action, que, por padrão, a move para a lixeira.

Um carregador também pode retornar paths para montar outras pastas locais de Markdown na coleção, opcionalmente sob um prefixo. Pastas fora da raiz da coleção precisam do filtro blockstudio/pages/allow_external_loader_path. Consulte Carregadores de coleção para ver a estrutura completa.

Etapa 4: Sincronização

Nada é gravado no banco de dados até você solicitar:

Shell
wp bs pages sync

O comando descobre todas as fontes de páginas, registra o tipo de publicação acme_docs, cria ou atualiza as publicações e imprime uma linha de resumo com as contagens de discovered, created, updated, unchanged, removed e failed. Se executado novamente sem alterações, informa que todas as páginas estão inalteradas e não grava nenhuma publicação. Adicione --format=json quando um script de implantação precisar do relatório completo.

Após a sincronização, as publicações espelham a árvore de arquivos. guide/install é filha de guide, que por sua vez é filha da raiz da coleção; a ordem de menu de cada publicação corresponde a order do frontmatter. Os URLs da coleção combinam o identificador da coleção com o caminho lógico de cada página:

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

Não é necessário salvar novamente os links permanentes. As regras de reescrita da coleção são atualizadas automaticamente quando os tipos de publicação registrados para a coleção mudam.

Inclua a sincronização na implantação. As solicitações do frontend e do admin nunca executam a descoberta de páginas. Portanto, uma implantação que copie novos arquivos Markdown sem executar wp bs pages sync continuará exibindo o conteúdo anterior.

Etapa 5: O layout

As publicações já existem, mas cada uma é exibida com o modelo individual habitual do tema e sem navegação. Um layout.php ao lado de pages.json envolve a renderização no frontend de cada página da coleção:

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') retorna a coleção como nós aninhados, ordenados por order e depois pelo título, com os filhos de cada nó em children. Neste exemplo, há uma raiz, a página de introdução, com as outras páginas abaixo dela. Cada nó contém key, title, path e permalink. Percorrer a árvore nessa ordem produz a sequência de leitura necessária para gerar todos os links para a página anterior e a próxima.

blockstudio_page_content() imprime o corpo da página que WordPress renderizaria por meio de the_content. Se você o omitir, o conteúdo ficará oculto. Na /docs/guide/install/ de um site em https://example.com, o layout renderiza este trecho (resumido):

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>

O layout só é executado em solicitações individuais do frontend durante o loop principal. Ele não altera o post_content armazenado nem envolve a área de edição do editor. Seu caminho é armazenado em cada publicação sincronizada e faz parte da impressão digital da página, então uma alteração no layout é aplicada na próxima sincronização.

Ler dados de coleção em PHP

Os auxiliares de layout são invólucros simples em torno da classe Blockstudio\Pages. Use qualquer uma das formas em modelos, blocos ou plugins:

Auxiliar Método da classe Retorna
blockstudio_pages('docs') Pages::pages('docs') Lista plana das páginas da coleção, indexada pela chave da página, em ordem
blockstudio_page_tree('docs') Pages::tree('docs') Nós aninhados com children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Filhos diretos de uma página
blockstudio_page_collection('docs') Pages::collection('docs') Dados da coleção do manifesto
blockstudio_current_page() Pages::current_page() A página que está sendo renderizada, ou null
Pages::get_page('docs-guide-install') Uma página pelo nome

Os arrays de páginas incluem os post_id, permalink, name, key, title sincronizados, path, order, collection, postType e o array meta. Os extras do frontmatter vão para meta, então um layout pode exibir o resumo da introdução:

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

Nas solicitações do frontend, essas funções leem as publicações já sincronizadas e a configuração armazenada na última sincronização. Elas nunca leem os arquivos Markdown, portanto não realizam operações no sistema de arquivos. Apenas páginas publicadas ficam disponíveis no frontend.

Markdown bruto para Tools

Como as páginas vêm de arquivos Markdown, Blockstudio também pode servir o código-fonte original. Solicite uma página com o sufixo .md, como em /docs/guide/install.md, ou envie Accept: text/markdown para o URL normal. A resposta omite o frontmatter e aponta de volta para a página HTML com um cabeçalho Link canônico. Isso é útil para indexadores de pesquisa, assistentes e outras ferramentas que leem texto simples. Páginas geradas a partir de conteúdo de carregador inline não têm arquivo de origem e, portanto, não têm resposta .md.

Desative com um único filtro:

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

Dicas

Deixe os caminhos definirem a estrutura. Mova um arquivo e o caminho, o pai e o URL acompanham a mudança na próxima sincronização. Use o path do frontmatter somente quando o URL deve ser diferente do local do arquivo.

Combine page.json com Markdown quando uma página precisar de mais. Uma pasta com page.json e index.md usa o JSON para propriedades da página, como postId ou templateLock, e o Markdown para o conteúdo. O frontmatter em index.md prevalece sobre valores correspondentes de page.json.

Escreva nos arquivos, não no editor. Com templateLock: "contentOnly", os editores podem corrigir o texto diretamente, mas a próxima sincronização de uma fonte alterada reescreve o conteúdo armazenado a partir do arquivo. Considere o Markdown como o local onde a documentação é escrita. Uma página que deve pertencer aos editores recebe "sync": false em um page.json; as sincronizações normais então a ignoram, e Blockstudio\Pages::force_sync() a cria uma vez.

É seguro mudar o tipo de publicação. Se uma coleção passar de page para um tipo de publicação personalizado, as publicações já sincronizadas são migradas no mesmo local quando a identidade armazenada corresponde, preservando os IDs das publicações.

Próximas etapas