Vai al contenuto

Creare un sito di documentazione

La documentazione dovrebbe stare accanto al codice che descrive. Chi scrive preferisce Markdown, chi revisiona vuole vedere le modifiche in una pull request e ogni release dovrebbe includere la documentazione nello stesso commit. WordPress, invece, vuole i post nel database: è lì che si trovano la ricerca, i permalink, le revisioni e l’editor.

Le raccolte di pagine Blockstudio collegano i due aspetti. Una cartella di file Markdown diventa un insieme di post WordPress reali, con un tipo di post dedicato, una base URL e una gerarchia di pagine principali e secondarie. Un file layout.php racchiude ogni pagina della raccolta in un layout con navigazione basata sugli stessi dati. I file restano la fonte attendibile e un comando di sincronizzazione esplicito li scrive nel database.

Questa guida crea passo dopo passo una piccola sezione di documentazione per un tema chiamato acme: un manifest, pagine Markdown, un loader che genera un changelog, la sincronizzazione e un layout con barra laterale e link alla pagina precedente e successiva.

Cosa realizzerete

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

Dopo la sincronizzazione, la raccolta sarà disponibile a questi URL:

Origine URL pubblici
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/
voce del loader /docs/changelog/

Passaggio 1: il manifest della raccolta

Una raccolta è una cartella all’interno di pages/ che contiene un manifest pages.json. Create pages/docs/pages.json:

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

collection è lo slug della raccolta e diventa la base pubblica URL. postType assegna ogni pagina della raccolta a un tipo di post dedicato, così la documentazione non si mescola alle normali pagine nell’area di amministrazione. Se quel tipo di post non esiste ancora, Blockstudio lo registra. Le impostazioni predefinite della registrazione sono: pubblico, gerarchico, disponibile nell’REST API, con supporto per titolo, editor, attributi di pagina, immagine in evidenza, riassunto e revisioni, e uno slug di riscrittura uguale a quello della raccolta. postTypeArgs viene unito a queste impostazioni predefinite, quindi questo manifest modifica solo l’etichetta nell’area di amministrazione.

defaults applica le proprietà delle pagine a tutte le pagine della raccolta. In questo caso ogni pagina viene pubblicata durante la sincronizzazione e consente solo modifiche al contenuto: gli editor possono correggere un refuso nell’editor, ma non riordinare la struttura definita da Markdown.

Passaggio 2: scrivere le pagine in Markdown

All’interno di una raccolta, ogni file Markdown è una pagina. La posizione del file ne determina l’identità, quindi il frontmatter è facoltativo. Usatelo per il titolo, l’ordine di visualizzazione e qualsiasi dato aggiuntivo vogliate leggere in seguito.

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 sezione della guida è una cartella con il proprio index.md, che diventa l’elemento principale delle pagine che 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 ricava da ogni file un percorso logico e un nome di pagina:

File Percorso Nome della pagina
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 producono lo stesso percorso, quindi in seguito potete passare da un file semplice a una cartella senza modificare l’URL.

order ordina le pagine sorelle e viene scritto nell’ordine del menu del post. Le pagine senza un ordine vengono dopo quelle ordinate e poi in ordine alfabetico per titolo. Le chiavi del frontmatter che Blockstudio non riconosce, come description nell’esempio sopra, vengono conservate nell’array meta della pagina.

Durante la sincronizzazione, Markdown viene analizzato come GitHub Flavored Markdown, convertito in HTML e poi analizzato in blocchi nativi. Il post memorizzato contiene blocchi, non il testo Markdown. I titoli ricevono un’ancora stabile, le tabelle diventano core/table, le citazioni diventano core/quote e il codice delimitato da fence diventa un blocco core/preformatted che mantiene la classe del linguaggio. Questo è il contenuto memorizzato della pagina di installazione (spazi iniziali e finali rimossi):

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

Passaggio 3: generare pagine con un loader

Alcune pagine sono più adatte a essere generate che scritte. Un changelog è un buon esempio: i dati delle release esistono già e copiarli a mano in Markdown può causare divergenze. Una raccolta può includere un loader.php che restituisce definizioni di pagine aggiuntive.

Conservate i dati delle release nella raccolta:

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

Quindi create una pagina Markdown a partire da essi:

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

Il loader viene eseguito durante l’individuazione e la sincronizzazione esplicite, mai durante la normale visualizzazione di una pagina. Mantenetelo deterministico e locale: leggere un file nel tema va bene, recuperare un API remoto no, perché la sincronizzazione dipenderebbe dalla disponibilità di quel servizio.

Le pagine del loader sono contrassegnate come generate. Se una voce scompare dall’output del loader, alla sincronizzazione successiva il relativo post viene considerato orfano e gestito dal filtro blockstudio/pages/orphan_action, che per impostazione predefinita lo sposta nel cestino.

Un loader può anche restituire paths per includere nella raccolta altre cartelle locali di file Markdown, facoltativamente sotto un prefisso. Le cartelle al di fuori della radice della raccolta richiedono il filtro blockstudio/pages/allow_external_loader_path. Per tutti i dettagli, consultate Loader delle raccolte.

Passaggio 4: sincronizzare

Il database non viene modificato finché non lo chiedete:

Shell
wp bs pages sync

Il comando individua tutte le origini delle pagine, registra il tipo di post acme_docs, crea o aggiorna i post e stampa una riga di riepilogo con i conteggi di discovered, created, updated, unchanged, removed e failed. Se lo eseguite di nuovo senza modifiche, tutte le pagine risultano invariate e non viene scritto alcun post. Aggiungete --format=json quando uno script di deploy ha bisogno del report completo.

Dopo la sincronizzazione, i post rispecchiano l’albero dei file. guide/install è una pagina secondaria di guide, che a sua volta dipende dalla radice della raccolta; l’ordine del menu di ogni post corrisponde al valore del frontmatter order. Gli URL della raccolta combinano lo slug della raccolta con il percorso logico di ogni pagina:

Codice
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/

Non è necessario salvare di nuovo i permalink. Le regole di riscrittura della raccolta vengono aggiornate automaticamente quando cambiano i tipi di post registrati per la raccolta.

Includete la sincronizzazione nel deploy. Le richieste del frontend e dell’area di amministrazione non individuano mai le pagine, quindi un deploy che copia nuovi file Markdown senza eseguire wp bs pages sync continua a servire i contenuti precedenti.

Passaggio 5: il layout

I post ora esistono, ma ognuno viene visualizzato con il normale template per i post singoli del tema e senza navigazione. Un layout.php accanto a pages.json racchiude il rendering frontend di ogni pagina della raccolta:

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') restituisce la raccolta sotto forma di nodi annidati, ordinati per order e poi per titolo, con i figli di ogni nodo in children. In questo caso c’è un solo nodo radice, la pagina introduttiva, con le altre pagine sottostanti. Ogni nodo contiene key, title, path e permalink. Appiattendo l’albero in quest’ordine si ottiene la sequenza di lettura necessaria per tutti i link alla pagina precedente e successiva.

blockstudio_page_content() stampa il corpo della pagina che WordPress genererebbe tramite the_content. Se lo omettete, il contenuto resta nascosto. Durante /docs/guide/install/ di un sito su https://example.com, il layout genera quanto segue (ridotto):

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>

Il layout viene eseguito solo nelle richieste frontend per singoli contenuti nel loop principale. Non modifica il post_content memorizzato né avvolge l’area dell’editor. Il relativo percorso è memorizzato in ogni post sincronizzato e fa parte dell’impronta digitale della pagina, quindi un layout modificato viene applicato alla sincronizzazione successiva.

Leggere i dati della raccolta in PHP

Gli helper del layout sono semplici wrapper attorno alla classe Blockstudio\Pages. Usate una delle due forme nei template, nei blocchi o nei plugin:

Helper Metodo della classe Restituisce
blockstudio_pages('docs') Pages::pages('docs') Elenco piatto delle pagine della raccolta, indicizzate per chiave di pagina e ordinate
blockstudio_page_tree('docs') Pages::tree('docs') Nodi annidati con children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Figli diretti di una pagina
blockstudio_page_collection('docs') Pages::collection('docs') Dati della raccolta dal manifest
blockstudio_current_page() Pages::current_page() La pagina in fase di rendering oppure null
Pages::get_page('docs-guide-install') Una pagina per nome

Gli array delle pagine includono gli elementi sincronizzati post_id, permalink, name, key, title, path, order, collection, postType e l’array meta. Gli extra del frontmatter finiscono in meta, così un layout può visualizzare il riepilogo dell’introduzione:

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

Nelle richieste frontend, queste funzioni leggono i post già sincronizzati e la configurazione salvata con l’ultima sincronizzazione. Non leggono mai i file Markdown, quindi non comportano operazioni sul filesystem. Sul frontend sono disponibili solo le pagine pubblicate.

Markdown grezzo per gli strumenti

Poiché le pagine provengono da file Markdown, Blockstudio può anche fornire il sorgente originale. Richiedi una pagina con il suffisso .md, ad esempio /docs/guide/install.md, oppure invia Accept: text/markdown al normale URL. La risposta omette il frontmatter e rimanda alla pagina HTML con un’intestazione canonica Link. È utile per gli indicizzatori di ricerca, gli assistenti e altri strumenti che leggono testo semplice. Le pagine generate dal contenuto del loader inline non hanno un file sorgente e quindi non dispongono di una risposta .md.

Disattivala con un solo filtro:

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

Suggerimenti

Lascia che siano i percorsi a definire la struttura. Sposta un file e, alla sincronizzazione successiva, lo seguiranno il percorso, il genitore e URL. Usa il frontmatter path solo quando URL deve essere diverso dalla posizione del file.

Abbina page.json a Markdown quando una pagina ha bisogno di altro. Una cartella con page.json e index.md usa JSON per le proprietà della pagina, come postId o templateLock, e Markdown per il contenuto. Il frontmatter in index.md prevale sui valori corrispondenti di page.json.

Scrivi nei file, non nell’editor. Con templateLock: "contentOnly", gli editor possono correggere il testo direttamente, ma la sincronizzazione successiva di una sorgente modificata riscrive il contenuto salvato a partire dal file. Considera Markdown il luogo in cui si scrive la documentazione. Una pagina destinata agli editor riceve invece "sync": false in un page.json; le normali sincronizzazioni la ignorano, mentre Blockstudio\Pages::force_sync() la crea una sola volta.

Cambiare il tipo di post è sicuro. Se una raccolta passa da page a un tipo di post personalizzato, i post già sincronizzati vengono migrati sul posto quando la loro identità salvata corrisponde, quindi gli ID dei post restano invariati.

Passaggi successivi