Créer un site de documentation
La documentation a sa place à 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 une version devrait inclure sa documentation dans le même commit. WordPress, en revanche, stocke les publications 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 relient les deux. Un dossier de fichiers Markdown devient un ensemble de publications WordPress réelles, avec leur propre type de publication, une base URL et une hiérarchie parent-enfant. Un fichier layout.php enveloppe chaque page de la collection dans une mise en page avec une navigation construite à partir des mêmes données. Les fichiers restent la source de vérité ; une commande de synchronisation explicite les enregistre dans la base de données.
Ce guide vous accompagne pas à pas dans la création d’une petite section de documentation pour un thème appelé 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 et des liens vers les pages précédente et suivante.
Ce que vous allez créer
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, la collection est accessible à ces URL :
| Source | URL publique |
|---|---|
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 :
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection est l’identifiant de la collection et devient la base publique URL. postType associe chaque page de la collection à un type de publication dédié afin que la documentation ne soit pas mélangée aux pages habituelles dans l’administration. Si ce type de publication n’existe pas encore, Blockstudio l’enregistre. Par défaut, ce type est public, hiérarchique, disponible dans REST API, et prend en charge le titre, l’éditeur, les attributs de page, l’image mise en avant, l’extrait et les révisions. Son identifiant de réécriture est celui de la collection. postTypeArgs est fusionné avec ces valeurs par défaut ; ce manifeste ne modifie donc que le libellé dans l’administration.
defaults applique des propriétés à chaque page de la collection. Ici, chaque page est publiée lors de la synchronisation et limitée à la modification du contenu : 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é, le frontmatter est donc facultatif. Utilisez-le pour le titre, l’ordre de tri et toute autre donnée que vous souhaitez consulter ultérieurement.
---
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
```
La section du guide est un dossier doté de son propre index.md, qui devient le parent des pages situées à côté :
---
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 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 plat à un dossier sans changer URL.
order trie les pages sœurs et est enregistré comme ordre de menu de la publication. Les pages sans ordre sont classées après celles qui en ont un, puis par titre. Les clés de frontmatter 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 GitHub Flavored Markdown, converti en HTML, puis analysé en blocs natifs. La publication enregistrée contient des blocs, pas le texte Markdown. Les titres reçoivent une ancre stable, les tableaux deviennent des core/table, les citations des core/quote et le code clôturé un bloc core/preformatted qui conserve la classe de langage. Voici le contenu enregistré pour la page d’installation (espaces blancs supprimés) :
<!-- 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 sont mieux générées que rédigées. Un journal des modifications en est un bon exemple : les données des versions existent déjà et les recopier manuellement 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 des versions dans la collection :
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Créez ensuite une page Markdown à partir de ces données :
<?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 pendant la découverte et la synchronisation explicites, jamais lors de l’affichage normal d’une page. Préférez un traitement déterministe et local : lire un fichier du thème convient, mais récupérer un API distant ne convient pas, 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 synchronisation suivante considère sa publication comme orpheline et la traite avec le filtre blockstudio/pages/orphan_action, qui la met à la corbeille par défaut.
Un chargeur peut aussi renvoyer paths pour intégrer d’autres dossiers locaux de Markdown à la collection, é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 Chargeurs de collection pour connaître leur structure complète.
Étape 4 : Synchroniser
Rien n’est écrit dans la base de données tant que vous ne le demandez pas :
wp bs pages sync
La commande découvre chaque source de page, enregistre le type de publication acme_docs, crée ou met à jour les publications et affiche une ligne récapitulative avec les nombres de discovered, created, updated, unchanged, removed et failed. Si vous la relancez sans changement, elle indique que chaque page est inchangée et n’écrit aucune publication. Ajoutez --format=json si un script de déploiement a besoin du rapport complet.
Après la synchronisation, les publications reflètent l’arborescence des fichiers. guide/install est un enfant de guide, lui-même enfant de la racine de la collection, et l’ordre de menu de chaque publication correspond à la valeur frontmatter order. Les URL de la collection combinent son identifiant et le chemin logique de chaque page :
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Vous n’avez pas besoin d’enregistrer à nouveau les permaliens. Les règles de réécriture de la collection sont automatiquement actualisées lorsque les types de publication de la 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 servir l’ancien contenu.
Étape 5 : La mise en page
Les publications existent désormais, mais chacune s’affiche avec le modèle d’article habituel du thème et sans navigation. Un fichier layout.php placé à côté de pages.json enveloppe le rendu frontend de chaque page de la collection :
<?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, la page d’introduction est l’unique racine, et les autres pages se trouvent en dessous. Chaque nœud contient key, title, path et permalink. En parcourant l’arbre dans cet ordre, on obtient la séquence de lecture nécessaire aux liens vers les pages précédente et suivante.
blockstudio_page_content() affiche le corps de la page que WordPress générerait via the_content. Si vous l’omettez, le contenu est masqué. Lors de /docs/guide/install/ d’un site sur https://example.com, la mise en page génère cet extrait (raccourci) :
<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 ne s’exécute que pour les requêtes frontend individuelles dans la boucle principale. Elle ne modifie pas le post_content enregistré et n’enveloppe pas la zone de travail de l’éditeur. Son chemin est enregistré sur chaque publication synchronisée et fait partie de l’empreinte de la page ; une mise en page modifiée est donc prise en compte lors de la synchronisation suivante.
Lire les données de collection dans PHP
Les fonctions d’aide à la mise en page sont de simples enveloppes autour de la classe Blockstudio\Pages. Utilisez l’une ou l’autre forme dans les modèles, les blocs ou les extensions :
| Aide | Méthode de classe | Renvoie |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Liste à plat des pages de la collection, indexées par clé de page et triées |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Nœuds imbriqués avec children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Enfants directs d’une page |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Données de la collection provenant du manifeste |
blockstudio_current_page() |
Pages::current_page() |
Page en cours de rendu, ou null |
Pages::get_page('docs-guide-install') |
Une page par nom |
Les tableaux de pages incluent les post_id, permalink, name, key, title synchronisés,
path, order, collection, postType, ainsi que le tableau meta. Les
informations supplémentaires du frontmatter se retrouvent dans meta, ce qui permet à une mise en page d’afficher le résumé de l’introduction :
<?php $summary = $current['meta']['description'] ?? ''; ?>
Sur les requêtes du frontend, ces fonctions lisent les publications déjà synchronisées et la configuration enregistrée lors de la dernière synchronisation. Elles ne lisent jamais les fichiers Markdown et n’entraînent donc aucun accès au système de fichiers. Seules les pages publiées sont accessibles sur le frontend.
Markdown brut pour les outils
Comme les pages proviennent de fichiers Markdown, Blockstudio peut aussi fournir la source d’origine. Demandez une page avec le suffixe .md, par exemple /docs/guide/install.md, ou envoyez Accept: text/markdown vers le URL habituel. La réponse omet le frontmatter et renvoie vers la page HTML avec un en-tête canonique Link. C’est utile pour les indexeurs de recherche, les assistants et les autres outils qui lisent du texte brut. Les pages générées à partir du contenu du chargeur intégré n’ont pas de fichier source et ne produisent donc aucune réponse .md.
Désactivez-le avec un seul filtre :
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Conseils
Laissez les chemins définir la structure. Déplacez un fichier : son chemin, son parent et URL suivront à la prochaine synchronisation. N’utilisez le frontmatter path que si le URL doit différer de l’emplacement du fichier.
Associez page.json à Markdown pour enrichir une page. Un dossier contenant page.json et index.md utilise le JSON pour les propriétés de page telles que postId ou templateLock, et le Markdown pour le contenu. Le frontmatter de index.md a priorité sur les valeurs page.json correspondantes.
Écrivez dans les fichiers, pas dans l’éditeur. Avec templateLock: "contentOnly", les éditeurs peuvent corriger le texte sur place, mais la prochaine synchronisation d’une source modifiée réécrit le contenu enregistré à partir du fichier. Considérez Markdown comme l’endroit où rédiger la documentation. Une page destinée aux éditeurs reçoit plutôt "sync": false dans un page.json ; les synchronisations normales l’ignorent alors, et Blockstudio\Pages::force_sync() la crée une seule fois.
Le changement de type de publication est sans risque. Si une collection passe de page à un type de publication personnalisé, les publications déjà synchronisées sont migrées sur place lorsque leur identité enregistrée correspond, ce qui préserve leurs ID.
Étapes suivantes
- Référence des pages : chaque propriété
page.jsonetpages.json, les chargeurs, les mises en page et le rapport de rapprochement. - Créer des pages à partir de fichiers : verrouillage des modèles, modes d’édition des blocs et fusion par clé pour les pages modifiées par les clients.
- Modèles et parties de l’éditeur de site à partir de fichiers : la même approche privilégiant les fichiers pour les en-têtes, pieds de page et modèles de thème.