Ga naar de inhoud

Een documentatiesite bouwen

Documentatie hoort thuis naast de code die ze beschrijft. Schrijvers werken graag in Markdown, reviewers willen wijzigingen in een pull request zien en bij een release moeten de documenten in dezelfde commit worden opgenomen. WordPress wil daarentegen berichten in de database: daar vind je zoeken, permalinks, revisies en de editor.

Blockstudio-paginacollecties verbinden die twee. Een map met Markdown-bestanden wordt een verzameling echte WordPress-berichten met een eigen berichttype, een URL-basis en een hiërarchie van bovenliggende en onderliggende pagina’s. Een bestand layout.php voorziet elke pagina in de collectie van een lay-out met navigatie die uit dezelfde gegevens is opgebouwd. De bestanden blijven de bron van waarheid en een expliciete synchronisatieopdracht schrijft ze naar de database.

Deze handleiding bouwt stap voor stap een kleine documentatiesectie voor een thema met de naam acme: een manifest, pagina’s in Markdown, een loader die een changelog genereert, de synchronisatie en een lay-out met een zijbalk en vorige- en volgende-links.

Wat je gaat bouwen

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

Na synchronisatie zijn deze URL’s beschikbaar voor de collectie:

Bron Openbare URL
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/
loadervermelding /docs/changelog/

Stap 1: Het collectiemanifest

Een collectie is een map in pages/ met een manifest pages.json. Maak pages/docs/pages.json aan:

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

collection is de collectieslug en wordt de openbare URL-basis. postType stuurt elke pagina in de collectie naar een speciaal berichttype, zodat documentatie in de admin niet door je gewone pagina’s wordt gemengd. Als dit berichttype nog niet bestaat, registreert Blockstudio het. De standaardinstellingen zijn: openbaar, hiërarchisch en beschikbaar in REST API, met ondersteuning voor titel, editor, pagina-attributen, thumbnail, samenvatting en revisies. De herschrijfslug is gelijk aan de collectieslug. postTypeArgs wordt samengevoegd met die standaardinstellingen, dus dit manifest wijzigt alleen het label in de admin.

defaults past pagina-eigenschappen toe op elke pagina in de collectie. Hier wordt elke pagina bij synchronisatie gepubliceerd en is alleen inhoud bewerken toegestaan. Redacteuren kunnen dus een typefout in de editor herstellen, maar de structuur die door Markdown wordt bepaald niet herschikken.

Stap 2: Schrijf de pagina’s in Markdown

Binnen een collectie is elk bestand Markdown een pagina. De bestandslocatie bepaalt de identiteit, dus frontmatter is optioneel. Gebruik die voor de titel, de sorteervolgorde en eventuele aanvullende gegevens die je later wilt uitlezen.

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

De handleidingsectie is een map met een eigen index.md. Dat wordt de bovenliggende pagina van de pagina’s ernaast:

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 leidt uit elk bestand een logisch pad en een paginanaam af:

Bestand Pad Paginanaam
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 en guide/install/index.md leveren hetzelfde pad op, dus je kunt later wisselen tussen een plat bestand en een map zonder de URL te wijzigen.

order sorteert pagina’s op hetzelfde niveau en wordt opgeslagen als de menuvolgorde van het bericht. Pagina’s zonder volgorde komen na de pagina’s met een volgorde en worden vervolgens op titel gesorteerd. Frontmatter-sleutels die Blockstudio niet herkent, zoals description hierboven, worden bewaard in de array meta van de pagina.

Tijdens de synchronisatie wordt Markdown geparseerd als GitHub Flavored Markdown, omgezet naar HTML en vervolgens geparseerd naar native blokken. Het opgeslagen bericht bevat blokken, niet de tekst Markdown. Koppen krijgen een stabiele ankerlink, tabellen worden core/table, blokcitaten worden core/quote en afgeschermde code wordt een core/preformatted-blok waarin de taalklasse behouden blijft. Dit is de opgeslagen inhoud van de installatiepagina, zonder overtollige witruimte:

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

Stap 3: Pagina’s genereren met een loader

Sommige pagina’s kun je beter genereren dan schrijven. Een changelog is een goed voorbeeld: de releasegegevens bestaan al en ze handmatig kopiëren naar Markdown kan voor verschillen zorgen. Een collectie kan een loader.php bevatten die aanvullende paginadefinities retourneert.

Bewaar de releasegegevens in de collectie:

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

Maak daar vervolgens één Markdown-pagina van:

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

De loader wordt uitgevoerd tijdens expliciete ontdekking en synchronisatie, nooit bij een normale paginaweergave. Zorg ervoor dat de uitvoering deterministisch en lokaal blijft: een bestand in het thema lezen is prima, maar een externe API ophalen niet, want dan is de synchronisatie afhankelijk van de bereikbaarheid van die service.

Loaderpagina’s worden gemarkeerd als gegenereerd. Als een vermelding niet meer in de uitvoer van de loader voorkomt, behandelt de volgende synchronisatie het bijbehorende bericht als verweesd en verwerkt het via het filter blockstudio/pages/orphan_action, dat het standaard naar de prullenbak verplaatst.

Een loader kan ook paths retourneren om andere lokale mappen met Markdown aan de collectie toe te voegen, eventueel met een voorvoegsel. Voor mappen buiten de hoofdmap van de collectie is het filter blockstudio/pages/allow_external_loader_path nodig. Zie Collectieloaders voor de volledige opzet.

Stap 4: Synchroniseren

Er wordt pas iets naar de database geschreven wanneer je daar opdracht toe geeft:

Shell
wp bs pages sync

De opdracht ontdekt elke paginabron, registreert het berichttype acme_docs, maakt de berichten aan of werkt ze bij en drukt een samenvattende rij af met aantallen voor discovered, created, updated, unchanged, removed en failed. Als je de opdracht opnieuw uitvoert zonder wijzigingen, worden alle pagina’s als ongewijzigd aangemerkt en worden er geen berichten weggeschreven. Voeg --format=json toe als een implementatiescript het volledige rapport nodig heeft.

Na de synchronisatie weerspiegelen de berichten de bestandsstructuur. guide/install is een onderliggende pagina van guide, die zelf onder de hoofdmap van de collectie valt. De menuvolgorde van elk bericht komt overeen met de frontmatter order. Collectie-URL’s bestaan uit de collectieslug en het logische pad van elke pagina:

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

Je hoeft permalinks niet opnieuw op te slaan. Herschrijfregels voor collecties worden automatisch vernieuwd wanneer de geregistreerde berichttypen van de collectie veranderen.

Neem de synchronisatie op in je implementatieproces. Frontend- en admin-verzoeken starten nooit paginadetectie. Als je bij een implementatie nieuwe Markdown-bestanden kopieert zonder wp bs pages sync uit te voeren, blijft de vorige inhoud beschikbaar.

Stap 5: De lay-out

De berichten bestaan nu, maar elk ervan wordt weergegeven met de normale enkelvoudige template van het thema en zonder navigatie. Een layout.php naast pages.json voorziet de frontendweergave van elke pagina in de collectie van een lay-out:

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') retourneert de collectie als geneste knooppunten, gesorteerd op order en vervolgens op titel, waarbij de onderliggende pagina’s van elk knooppunt in children staan. Hier is er één hoofdpagina, de introductiepagina, met de overige pagina’s eronder. Elk knooppunt bevat key, title, path en permalink. Door de boomstructuur in die volgorde af te vlakken, krijg je de leesvolgorde die nodig is voor alle vorige- en volgende-links.

blockstudio_page_content() toont de paginainhoud die WordPress via the_content zou renderen. Laat dit weg en de inhoud blijft verborgen. Bij /docs/guide/install/ van een site op https://example.com rendert de lay-out dit (ingekort):

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>

De lay-out wordt alleen uitgevoerd bij frontend-verzoeken voor afzonderlijke pagina’s in de hoofdloop. De opgeslagen post_content wordt niet gewijzigd en de lay-out wordt niet toegepast op het canvas van de editor. Het pad wordt opgeslagen bij elk gesynchroniseerd bericht en maakt deel uit van de paginavingerafdruk. Een bewerkte lay-out wordt daarom bij de volgende synchronisatie opgehaald.

Collectiegegevens uitlezen in PHP

De lay-outhelpers zijn dunne wrappers rond de klasse Blockstudio\Pages. Gebruik een van beide vormen in templates, blokken of plug-ins:

Helper Class-methode Retourneert
blockstudio_pages('docs') Pages::pages('docs') Platte lijst met pagina’s van de collectie, gesorteerd op paginasleutel
blockstudio_page_tree('docs') Pages::tree('docs') Geneste knooppunten met children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Directe subpagina’s van één pagina
blockstudio_page_collection('docs') Pages::collection('docs') Collectiegegevens uit het manifest
blockstudio_current_page() Pages::current_page() De pagina die wordt weergegeven, of null
Pages::get_page('docs-guide-install') Eén pagina op naam

Pagina-arrays bevatten de gesynchroniseerde post_id, permalink, name, key, title, path, order, collection, postType en de array meta. Extra frontmatter komt terecht in meta, zodat een lay-out de samenvatting van de introductie kan weergeven:

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

Bij frontendverzoeken lezen deze functies reeds gesynchroniseerde berichten en de configuratie die bij de laatste synchronisatie is opgeslagen. Ze lezen nooit de bestanden Markdown, dus ze belasten het bestandssysteem niet. Alleen gepubliceerde pagina’s zijn beschikbaar op de frontend.

Onbewerkte Markdown voor tools

Omdat de pagina’s afkomstig zijn uit bestanden van Markdown, kan Blockstudio ook de oorspronkelijke bron aanbieden. Vraag een pagina op met het achtervoegsel .md, zoals /docs/guide/install.md, of stuur Accept: text/markdown naar de normale URL. Het antwoord laat de frontmatter weg en verwijst met een canonieke Link-header terug naar de pagina HTML. Dit is handig voor zoekindexeerders, assistenten en andere tools die platte tekst lezen. Pagina’s die zijn gegenereerd op basis van inline loaderinhoud hebben geen bronbestand en dus ook geen antwoord met .md.

Schakel dit uit met één filter:

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

Tips

Laat paden de structuur bepalen. Verplaats een bestand en het pad, de bovenliggende pagina en URL volgen bij de volgende synchronisatie. Gebruik frontmatter path alleen als de URL moet afwijken van de bestandslocatie.

Combineer page.json met Markdown als een pagina meer nodig heeft. Een map met page.json en index.md gebruikt de JSON voor pagina-eigenschappen zoals postId of templateLock, en de Markdown voor inhoud. Frontmatter in index.md heeft voorrang op overeenkomende waarden in page.json.

Schrijf in de bestanden, niet in de editor. Met templateLock: "contentOnly" kunnen editors tekst ter plekke corrigeren, maar bij de volgende synchronisatie van een gewijzigd bronbestand wordt de opgeslagen inhoud overschreven door de inhoud uit het bestand. Gebruik de Markdown als plek om documentatie te schrijven. Een pagina die bij editors hoort, krijgt in plaats daarvan "sync": false in een page.json; normale synchronisaties slaan die dan over en Blockstudio\Pages::force_sync() maakt de pagina één keer aan.

Het berichttype wijzigen is veilig. Als een collectie overstapt van page naar een aangepast berichttype, worden reeds gesynchroniseerde berichten ter plekke gemigreerd als hun opgeslagen identiteit overeenkomt, zodat de bericht-ID’s behouden blijven.

Volgende stappen