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
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:
{
"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.
---
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/).
---
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:
---
title: Guide
order: 20
---
# Guide
Task-focused walkthroughs for everyday work.
---
title: Installation
order: 10
---
# Installation
| Requirement | Version |
| --- | --- |
| WordPress | 6.7+ |
| PHP | 8.2+ |
---
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):
<!-- 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:
[
{ "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
$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:
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:
/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
$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):
<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 $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:
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
- Referência de páginas: todas as propriedades
page.jsonepages.json, carregadores, layouts e o relatório de reconciliação. - Criação de páginas baseadas em arquivos: bloqueio de modelos, modos de edição de blocos e mesclagem por chave para páginas editadas pelos clientes.
- Modelos e partes do Editor do site a partir de arquivos: a mesma abordagem que prioriza arquivos para cabeçalhos, rodapés e modelos de tema.