Zum Inhalt springen

Eine Dokumentationswebsite erstellen

Dokumentation gehört neben den Code, den sie beschreibt. Schreibende bevorzugen Markdown, Prüfende möchten Änderungen in einem Pull Request sehen, und ein Release sollte die Dokumentation im selben Commit enthalten. WordPress hingegen erwartet Beiträge in der Datenbank: Dort befinden sich Suche, Permalinks, Revisionen und der Editor.

Blockstudio-Seitensammlungen verbinden beides. Ein Ordner mit Markdown-Dateien wird zu einer Reihe echter WordPress-Beiträge mit eigenem Beitragstyp, einer URL-Basis und einer Hierarchie aus übergeordneten und untergeordneten Seiten. Eine layout.php-Datei umschließt jede Seite der Sammlung mit einer Navigation, die aus denselben Daten erstellt wird. Die Dateien bleiben die maßgebliche Quelle, und ein expliziter Sync-Befehl schreibt sie in die Datenbank.

Diese Anleitung erstellt Schritt für Schritt einen kleinen Dokumentationsbereich für ein Theme namens acme: ein Manifest, Markdown-Seiten, einen Loader, der ein Änderungsprotokoll generiert, den Sync und ein Layout mit Seitenleiste sowie Links zur vorherigen und nächsten Seite.

Das erstellst du

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

Nach dem Sync stellt die Sammlung diese URLs bereit:

Quelle Öffentliche 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/
Loadereintrag /docs/changelog/

Schritt 1: Das Sammlungsmanifest

Eine Sammlung ist ein Ordner innerhalb von pages/, der ein Manifest pages.json enthält. Erstelle pages/docs/pages.json:

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

collection ist der Slug der Sammlung und wird zur öffentlichen URL-Basis. postType weist jede Seite der Sammlung einem eigenen Beitragstyp zu, damit sich die Dokumentation im Adminbereich nicht mit deinen normalen Seiten vermischt. Wenn es diesen Beitragstyp noch nicht gibt, registriert Blockstudio ihn. Die Standardeinstellungen der Registrierung sind: öffentlich, hierarchisch, im REST API verfügbar, mit Unterstützung für Titel, Editor, Seitenattribute, Vorschaubild, Auszug und Revisionen sowie einem Rewrite-Slug, der dem Sammlungs-Slug entspricht. postTypeArgs wird mit diesen Standardeinstellungen zusammengeführt. Daher ändert dieses Manifest nur die Bezeichnung im Adminbereich.

defaults wendet Seiteneigenschaften auf alle Seiten der Sammlung an. Hier wird jede Seite beim Sync veröffentlicht und auf die Bearbeitung des Inhalts beschränkt. Redakteure können also Tippfehler im Editor korrigieren, aber nicht die von Markdown festgelegte Struktur verändern.

Schritt 2: Seiten in Markdown schreiben

Innerhalb einer Sammlung ist jede Markdown-Datei eine Seite. Der Speicherort der Datei legt ihre Identität fest, daher sind Frontmatter-Angaben optional. Verwende sie für den Titel, die Sortierreihenfolge und zusätzliche Daten, die du später auslesen möchtest.

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

Der Dokumentationsbereich ist ein Ordner mit einem eigenen index.md, das zum übergeordneten Eintrag der danebenliegenden Seiten wird:

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 leitet aus jeder Datei einen logischen Pfad und einen Seitennamen ab:

Datei Pfad Seitenname
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 und guide/install/index.md ergeben denselben Pfad. Du kannst also später zwischen einer flachen Datei und einem Ordner wechseln, ohne die URL zu ändern.

order sortiert gleichrangige Seiten und wird als Menü-Reihenfolge des Beitrags gespeichert. Seiten ohne Sortierwert stehen nach den sortierten Seiten, danach wird nach Titel sortiert. Frontmatter-Schlüssel, die Blockstudio nicht erkennt, wie das obige description, bleiben im Array meta der Seite erhalten.

Beim Sync wird Markdown als GitHub Flavored Markdown geparst, in HTML umgewandelt und anschließend in native Blöcke geparst. Der gespeicherte Beitrag enthält Blöcke, nicht den Markdown-Text. Überschriften erhalten einen stabilen Anker, Tabellen werden zu core/table, Blockzitate zu core/quote und eingerückter Code zu einem core/preformatted-Block, der die Sprachklasse beibehält. Dies ist der gespeicherte Inhalt der Installationsseite (Leerzeichen entfernt):

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

Schritt 3: Seiten mit einem Loader generieren

Manche Seiten lassen sich besser generieren als schreiben. Ein Änderungsprotokoll ist ein gutes Beispiel: Die Release-Daten liegen bereits vor, und wer sie von Hand in Markdown kopiert, riskiert Abweichungen. Eine Sammlung kann einen loader.php enthalten, der zusätzliche Seitendefinitionen zurückgibt.

Lege die Release-Daten in der Sammlung ab:

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

Erstelle daraus anschließend eine einzelne Markdown-Seite:

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

Der Loader läuft bei der expliziten Ermittlung und beim Sync, niemals beim normalen Anzeigen einer Seite. Halte ihn deterministisch und lokal: Eine Datei im Theme zu lesen ist in Ordnung, ein entferntes API abzurufen hingegen nicht, da der Sync sonst davon abhängig wäre, dass dieser Dienst erreichbar ist.

Loader-Seiten werden als generiert gekennzeichnet. Wenn ein Eintrag aus der Loader-Ausgabe verschwindet, behandelt der nächste Sync seinen Beitrag als verwaist und verarbeitet ihn über den Filter blockstudio/pages/orphan_action, der ihn standardmäßig in den Papierkorb verschiebt.

Ein Loader kann auch paths zurückgeben, um weitere lokale Markdown-Ordner in die Sammlung einzubinden, optional unter einem Präfix. Für Ordner außerhalb des Sammlungspfads ist der Filter blockstudio/pages/allow_external_loader_path erforderlich. Die vollständige Struktur findest du unter Collection Loaders.

Schritt 4: Synchronisieren

In die Datenbank wird erst geschrieben, wenn du es anforderst:

Shell
wp bs pages sync

Der Befehl ermittelt alle Seitenquellen, registriert den Beitragstyp acme_docs, erstellt oder aktualisiert die Beiträge und gibt eine Zusammenfassungszeile mit den Zählwerten für discovered, created, updated, unchanged, removed und failed aus. Wenn du ihn ohne Änderungen erneut ausführst, werden alle Seiten als unverändert gemeldet und es finden keine Schreibvorgänge an Beiträgen statt. Füge --format=json hinzu, wenn ein Deploy-Skript den vollständigen Bericht benötigt.

Nach dem Sync spiegeln die Beiträge den Dateibaum wider. guide/install ist ein untergeordneter Eintrag von guide, das wiederum dem Sammlungsstamm untergeordnet ist. Die Menü-Reihenfolge jedes Beitrags entspricht dem Frontmatter-Wert order. Sammlungs-URLs verbinden den Sammlungs-Slug mit dem logischen Pfad jeder Seite:

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

Permalinks musst du nicht erneut speichern. Rewrite-Regeln für Sammlungen werden automatisch geleert, wenn sich die registrierten Sammlungs-Beitragstypen ändern.

Mache den Sync zum Bestandteil deines Deployments. Frontend- und Admin-Anfragen führen keine Seitenermittlung aus. Wenn ein Deploy neue Markdown-Dateien kopiert, ohne wp bs pages sync auszuführen, werden weiterhin die vorherigen Inhalte ausgeliefert.

Schritt 5: Das Layout

Die Beiträge sind jetzt vorhanden, werden aber alle mit dem normalen Einzel-Template des Themes und ohne Navigation gerendert. Eine layout.php neben pages.json umschließt die Frontend-Darstellung jeder Seite der Sammlung:

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') gibt die Sammlung als verschachtelte Knoten zurück, sortiert nach order und anschließend nach Titel. Die untergeordneten Elemente jedes Knotens stehen in children. Hier gibt es einen Wurzelknoten, die Einführungsseite, unter der die übrigen Seiten liegen. Jeder Knoten enthält key, title, path und permalink. Werden die Knoten in dieser Reihenfolge abgeflacht, ergibt sich die Lesereihenfolge, die für die Links zur vorherigen und nächsten Seite benötigt wird.

blockstudio_page_content() gibt den Seiteninhalt aus, den WordPress über the_content rendern würde. Lässt du es weg, bleibt der Inhalt verborgen. Beim /docs/guide/install/ einer Website unter https://example.com rendert das Layout Folgendes (gekürzt):

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>

Das Layout wird nur bei Frontend-Anfragen für Einzelansichten innerhalb der Hauptschleife ausgeführt. Es ändert den gespeicherten post_content-Inhalt nicht und umschließt auch nicht die Editorfläche. Sein Pfad wird bei jedem synchronisierten Beitrag gespeichert und gehört zum Seitenfingerabdruck. Ein bearbeitetes Layout wird daher beim nächsten Sync übernommen.

Sammlungsdaten in PHP auslesen

Die Layout-Helfer sind einfache Wrapper um die Klasse Blockstudio\Pages. Verwende eine der beiden Formen in Templates, Blöcken oder Plugins:

Helfer Klassenmethode Rückgabe
blockstudio_pages('docs') Pages::pages('docs') Flache Liste der Seiten der Sammlung, nach Seitenschlüssel indiziert und sortiert
blockstudio_page_tree('docs') Pages::tree('docs') Verschachtelte Knoten mit children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Direkte untergeordnete Seiten einer Seite
blockstudio_page_collection('docs') Pages::collection('docs') Sammlungsdaten aus dem Manifest
blockstudio_current_page() Pages::current_page() Die gerade gerenderte Seite oder null
Pages::get_page('docs-guide-install') Eine Seite anhand ihres Namens

Seitenarrays enthalten die synchronisierten Werte post_id, permalink, name, key, title, path, order, collection und postType sowie das Array meta. Zusätzliche Frontmatter-Angaben landen in meta. Daher kann ein Layout die Zusammenfassung der Einführungsseite ausgeben:

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

Bei Frontend-Anfragen lesen diese Funktionen bereits synchronisierte Beiträge und die beim letzten Sync gespeicherte Konfiguration. Sie lesen niemals die Markdown-Dateien und verursachen daher keine Zugriffe auf das Dateisystem. Im Frontend sind nur veröffentlichte Seiten verfügbar.

Rohes Markdown für Tools

Da die Seiten aus Markdown-Dateien stammen, kann Blockstudio auch den Originalquelltext bereitstellen. Fordere eine Seite mit dem Suffix .md an, zum Beispiel /docs/guide/install.md, oder sende Accept: text/markdown an das normale URL. Die Antwort lässt das Frontmatter aus und verweist mit einem kanonischen Link-Header auf die HTML-Seite. Das ist nützlich für Suchindexierer, Assistenten und andere Tools, die Klartext verarbeiten. Aus inline Loader-Inhalten generierte Seiten haben keine Quelldatei und daher auch keine .md-Antwort.

Mit einem Filter deaktivierst du es:

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

Tipps

Lass die Pfade die Struktur bestimmen. Verschiebst du eine Datei, ändern sich beim nächsten Sync ihr Pfad, übergeordneter Eintrag und URL. Verwende Frontmatter-path nur, wenn sich das URL vom Speicherort der Datei unterscheiden soll.

Kombiniere page.json mit Markdown, wenn eine Seite mehr braucht. Ein Ordner mit page.json und index.md verwendet das JSON für Seiteneigenschaften wie postId oder templateLock und das Markdown für Inhalte. Frontmatter in index.md hat Vorrang vor übereinstimmenden Werten aus page.json.

Schreibe in die Dateien, nicht im Editor. Mit templateLock: "contentOnly" können Editoren Texte direkt bearbeiten, aber beim nächsten Sync einer geänderten Quelle wird der gespeicherte Inhalt aus der Datei überschrieben. Betrachte Markdown als den Ort, an dem die Doku geschrieben wird. Eine Seite, die Editoren gehören soll, erhält stattdessen "sync": false in einem page.json; normale Syncs überspringen sie dann, und Blockstudio\Pages::force_sync() erstellt sie einmalig.

Der Beitragstyp lässt sich sicher ändern. Wenn eine Sammlung von page zu einem benutzerdefinierten Beitragstyp wechselt, werden bereits synchronisierte Beiträge an Ort und Stelle migriert, wenn ihre gespeicherte Identität übereinstimmt. Ihre Beitrags-IDs bleiben erhalten.

Nächste Schritte