Treci la conținut

Créer un site de documentation

La documentation doit se trouver à côté du code qu’elle décrit. Les rédacteurs préfèrent Markdown, les réviseurs veulent voir les changements dans une pull request, et les documents d’une version devraient être livrés dans le même commit. WordPress, en revanche, stocke les articles dans la base de données : c’est là que se trouvent la recherche, les permaliens, les révisions et l’éditeur.

Les collections de pages Blockstudio font le lien entre les deux. Un dossier de fichiers Markdown devient un ensemble d’articles WordPress réels, avec leur propre type d’article, une base URL et une hiérarchie de pages parentes et enfants. Un fichier layout.php entoure chaque page de la collection d’une navigation construite à partir des mêmes données. Les fichiers restent la source de référence ; une commande de synchronisation explicite les écrit dans la base de données.

Ce guide vous montre étape par étape comment créer une petite section de documentation pour un thème nommé acme : un manifeste, des pages Markdown, un chargeur qui génère un journal des modifications, la synchronisation et une mise en page avec une barre latérale ainsi que des liens vers les pages précédente et suivante.

Ce que vous allez créer

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

Après la synchronisation, les URL suivantes seront disponibles pour la collection :

Source URL public
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/
entrée du chargeur /docs/changelog/

Étape 1 : Le manifeste de la collection

Une collection est un dossier dans pages/ qui contient un manifeste pages.json. Créez pages/docs/pages.json :

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

collection est le slug de la collection et devient la base publique URL. postType associe chaque page de la collection à un type d’article dédié, afin que les documents ne se mélangent pas aux pages habituelles dans l’administration. Si ce type d’article n’existe pas encore, Blockstudio l’enregistre. Par défaut, il est public et hiérarchique, disponible dans le REST API, avec prise en charge du titre, de l’éditeur, des attributs de page, de l’image mise en avant, de l’extrait et des révisions, ainsi qu’un slug de réécriture identique au slug de la collection. postTypeArgs remplace ces valeurs par défaut ; ce manifeste ne modifie donc que le libellé dans l’administration.

defaults applique des propriétés de page à toutes les pages de la collection. Ici, chaque page est publiée lors de la synchronisation et son contenu seul peut être modifié : les éditeurs peuvent corriger une faute dans l’éditeur, mais pas réorganiser la structure définie par Markdown.

Étape 2 : Rédiger les pages en Markdown

Dans une collection, chaque fichier Markdown est une page. Son emplacement détermine son identité, donc les métadonnées YAML en tête de fichier sont facultatives. Utilisez-les pour le titre, l’ordre de tri et toute autre donnée à récupérer plus tard.

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 section du guide est un dossier avec son propre index.md, qui devient le parent des pages situées à côté :

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 déduit un chemin logique et un nom de page à partir de chaque fichier :

Fichier Chemin Nom de la page
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 et guide/install/index.md produisent le même chemin. Vous pouvez donc passer plus tard d’un fichier seul à un dossier sans changer le URL.

order trie les pages sœurs et est enregistré dans l’ordre de menu de l’article. Les pages sans ordre défini sont placées après celles qui en ont un, puis triées par titre. Les clés des métadonnées YAML en tête de fichier que Blockstudio ne reconnaît pas, comme description ci-dessus, sont conservées dans le tableau meta de la page.

Lors de la synchronisation, Markdown est analysé en tant que GitHub Flavored Markdown, converti en HTML, puis analysé en blocs natifs. L’article stocké contient des blocs, et non le texte Markdown. Les titres reçoivent une ancre stable, les tableaux deviennent core/table, les citations deviennent core/quote et les blocs de code délimités deviennent un bloc core/preformatted qui conserve la classe du langage. Voici le contenu stocké de la page d’installation (espaces superflus supprimés) :

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

Étape 3 : Générer des pages avec un chargeur

Certaines pages se prêtent mieux à la génération qu’à la rédaction. Un journal des modifications en est un bon exemple : les données de version existent déjà, et les recopier à la main dans Markdown risque de créer des divergences. Une collection peut inclure un loader.php qui renvoie des définitions de pages supplémentaires.

Conservez les données de version dans la collection :

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

Puis créez une page Markdown à partir de ces données :

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

Le chargeur s’exécute lors d’une découverte et d’une synchronisation explicites, jamais à l’affichage normal d’une page. Faites en sorte qu’il soit déterministe et local : lire un fichier du thème convient, mais récupérer un API distant est à éviter, car la synchronisation dépendrait alors de la disponibilité de ce service.

Les pages du chargeur sont marquées comme générées. Si une entrée disparaît du résultat du chargeur, la prochaine synchronisation considère son article comme orphelin et le traite selon le filtre blockstudio/pages/orphan_action, qui le place par défaut dans la corbeille.

Un chargeur peut également renvoyer paths pour intégrer à la collection d’autres dossiers locaux de Markdown, éventuellement sous un préfixe. Les dossiers situés en dehors de la racine de la collection nécessitent le filtre blockstudio/pages/allow_external_loader_path. Consultez la Documentation sur les chargeurs de collections pour connaître toutes les possibilités.

Étape 4 : Synchroniser

Rien n’est écrit dans la base de données tant que vous ne l’avez pas demandé :

Shell
wp bs pages sync

La commande découvre toutes les sources de pages, enregistre le type d’article acme_docs, crée ou met à jour les articles et affiche une ligne récapitulative avec les nombres de discovered, created, updated, unchanged, removed et failed. Si vous la relancez sans changement, toutes les pages sont indiquées comme inchangées et aucun article n’est écrit. Ajoutez --format=json si un script de déploiement a besoin du rapport complet.

Après la synchronisation, les articles reflètent l’arborescence des fichiers. guide/install est une page enfant de guide, elle-même enfant de la racine de la collection ; l’ordre de menu de chaque article correspond à la valeur order des métadonnées YAML en tête de fichier. Les URL de la collection associent le slug de la collection au chemin logique de chaque page :

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

Vous n’avez pas besoin d’enregistrer de nouveau les permaliens. Les règles de réécriture de la collection sont automatiquement vidées lorsque les types d’articles de collection enregistrés changent.

Intégrez la synchronisation à votre déploiement. Les requêtes du frontend et de l’administration ne lancent jamais la découverte des pages ; un déploiement qui copie de nouveaux fichiers Markdown sans exécuter wp bs pages sync continue donc de diffuser l’ancien contenu.

Étape 5 : La mise en page

Les articles existent maintenant, mais chacun utilise le modèle d’article unique habituel du thème, sans navigation. Un layout.php placé à côté de pages.json enveloppe le rendu frontend de chaque page de la collection :

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') renvoie la collection sous forme de nœuds imbriqués, triés par order puis par titre, avec les enfants de chaque nœud dans children. Ici, elle a une seule racine, la page d’introduction, et les autres pages en sont les enfants. Chaque nœud contient key, title, path et permalink. L’aplatissement de l’arborescence dans cet ordre donne la séquence de lecture nécessaire aux liens vers les pages précédente et suivante.

blockstudio_page_content() afișează corpul paginii pe care WordPress l-ar reda prin the_content. Dacă îl omiteți, conținutul este ascuns. La /docs/guide/install/ unui site la https://example.com, aspectul redă următoarele (prescurtat):

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>

La mise en page s’exécute uniquement lors des requêtes frontend visant un contenu unique dans la boucle principale. Elle ne modifie pas le post_content stocké et n’enveloppe pas le canevas de l’éditeur. Son chemin est enregistré sur chaque article synchronisé et fait partie de l’empreinte de la page ; une mise en page modifiée est donc prise en compte lors de la prochaine synchronisation.

Lire les données d’une collection dans PHP

Les fonctions d’aide de mise en page sont de simples enveloppes autour de la classe Blockstudio\Pages. Vous pouvez utiliser l’une ou l’autre forme dans les modèles, les blocs ou les extensions :

Ajutor Metodă de clasă Returnează
blockstudio_pages('docs') Pages::pages('docs') Lista plată a paginilor colecției, sortată și indexată după cheia paginii
blockstudio_page_tree('docs') Pages::tree('docs') Noduri imbricate cu children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Copiii direcți ai unei pagini
blockstudio_page_collection('docs') Pages::collection('docs') Datele colecției din manifest
blockstudio_current_page() Pages::current_page() Pagina redată sau null
Pages::get_page('docs-guide-install') O pagină după nume

Tablourile de pagini includ post_id, permalink, name, key, title, path, order, collection, postType sincronizate și tabloul meta. Datele suplimentare din frontmatter ajung în meta, astfel încât un aspect poate afișa rezumatul introducerii:

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

La cererile frontend, aceste funcții citesc articolele deja sincronizate și configurația stocată la ultima sincronizare. Nu citesc niciodată fișierele Markdown, așa că nu implică operațiuni asupra sistemului de fișiere. În frontend sunt disponibile doar paginile publicate.

Markdown brut pentru instrumente

Deoarece paginile provin din fișiere Markdown, Blockstudio poate furniza și sursa originală. Solicitați o pagină cu sufixul .md, de exemplu /docs/guide/install.md, sau trimiteți Accept: text/markdown către URL obișnuit. Răspunsul omite frontmatter-ul și indică pagina HTML printr-un antet Link canonic. Acest lucru este util pentru indexatoare de căutare, asistenți și alte instrumente care citesc text simplu. Paginile generate din conținutul unui loader inline nu au fișier sursă și, prin urmare, nu oferă un răspuns .md.

Dezactivați-l cu un singur filtru:

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

Sfaturi

Lăsați căile să definească structura. Mutați un fișier, iar calea, părintele și URL îl vor urma la următoarea sincronizare. Folosiți frontmatter-ul path doar când URL trebuie să fie diferit de locația fișierului.

Asociați page.json cu Markdown când o pagină are nevoie de mai mult. Un folder cu page.json și index.md folosește JSON pentru proprietățile paginii, precum postId sau templateLock, și Markdown pentru conținut. Valorile din frontmatter-ul index.md au prioritate față de valorile page.json corespunzătoare.

Scrieți în fișiere, nu în editor. Cu templateLock: "contentOnly", editorii pot corecta textul direct, dar următoarea sincronizare a unei surse modificate rescrie conținutul stocat din fișier. Considerați Markdown locul în care se scriu documentele. O pagină care ar trebui să le aparțină editorilor primește în schimb "sync": false într-un page.json; sincronizările obișnuite o ignoră, iar Blockstudio\Pages::force_sync() o creează o singură dată.

Schimbarea tipului de articol este sigură. Dacă o colecție trece de la page la un tip de articol personalizat, articolele deja sincronizate sunt migrate pe loc când identitatea stocată corespunde, astfel încât ID-urile articolelor se păstrează.

Pașii următori