Gå til indhold

Opbygning af et dokumentationswebsted

Dokumentationen hører hjemme ved siden af den kode, den beskriver. Skribenter foretrækker Markdown, anmeldere vil se ændringer i en pull request, og en release bør indeholde dokumentationen i samme commit. WordPress foretrækker til gengæld indlæg i databasen: Det er her, søgning, permalinks, versioner og editoren findes.

Blockstudio-sidekollektioner forbinder de to. En mappe med Markdown-filer bliver til en samling ægte WordPress-indlæg med sin egen indlægstype, en URL-base og et hierarki af over- og undersider. En layout.php-fil omslutter hver side i kollektionen med navigation, der bygger på de samme data. Filerne forbliver den autoritative kilde, og en eksplicit synkroniseringskommando skriver dem til databasen.

Denne vejledning bygger trin for trin en lille dokumentationssektion til et tema kaldet acme: et manifest, Markdown-sider, en loader, der genererer en changelog, synkronisering og et layout med sidemenu samt links til forrige og næste side.

Det bygger du

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

Efter synkronisering viser kollektionen disse URL’er:

Kilde Offentlig 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/
loaderindgang /docs/changelog/

Trin 1: Kollektionsmanifestet

En kollektion er en mappe i pages/, som indeholder et pages.json-manifest. Opret pages/docs/pages.json:

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

collection er kollektionens slug og bliver den offentlige URL-base. postType sender hver side i kollektionen til en dedikeret indlægstype, så dokumentationen ikke blandes med dine normale sider i admin. Hvis indlægstypen ikke findes endnu, registrerer Blockstudio den. Registreringens standardindstillinger er offentlig, hierarkisk, tilgængelig i REST API, med understøttelse af titel, editor, sideattributter, miniaturebillede, uddrag og versioner samt en rewrite-slug, der svarer til kollektionens slug. postTypeArgs sammenflettes med disse standardindstillinger, så dette manifest kun ændrer adminetiketten.

defaults anvender sideegenskaber på alle sider i kollektionen. Her udgives hver side ved synkronisering og låses til redigering af indhold alene, så redaktører kan rette en slåfejl i editoren, men ikke ændre strukturen, som Markdown definerer.

Trin 2: Skriv siderne i Markdown

I en kollektion er hver Markdown-fil en side. Filens placering angiver identiteten, så frontmatter er valgfri. Brug det til titlen, sorteringsrækkefølgen og eventuelle ekstra data, du vil læse senere.

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

Guidens sektion er en mappe med sin egen index.md, som bliver overordnet side for siderne ved siden af den:

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 udleder en logisk sti og et sidenavn fra hver fil:

Fil Sti Sidenavnet
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 og guide/install/index.md giver samme sti, så du senere kan skifte mellem en flad fil og en mappe uden at ændre URL.

order sorterer sider på samme niveau og skrives til indlæggets menurækkefølge. Sider uden rækkefølge placeres efter sider med angivet rækkefølge og sorteres derefter efter titel. Frontmatter-nøgler, som Blockstudio ikke genkender, f.eks. description ovenfor, gemmes i sidens meta– array.

Under synkronisering fortolkes Markdown som GitHub Flavored Markdown, konverteres til HTML og fortolkes derefter til native blokke. Det gemte indlæg indeholder blokke, ikke Markdown-teksten. Overskrifter får et stabilt anker, tabeller bliver til core/table, blokcitater bliver til core/quote, og indrammet kode bliver til en core/preformatted-blok, der bevarer sprogklassen. Dette er det gemte indhold på installationssiden (med overflødige mellemrum fjernet):

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

Trin 3: Generér sider med en loader

Nogle sider egner sig bedre til at blive genereret end skrevet. En changelog er et godt eksempel: versionsdataene findes allerede, og manuel kopiering til Markdown giver risiko for uoverensstemmelser. En kollektion kan indeholde en loader.php, der returnerer ekstra sidedefinitioner.

Opbevar versionsdataene i kollektionen:

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

Byg derefter én Markdown-side ud fra dem:

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

Loaderen køres under eksplicit registrering og synkronisering, aldrig ved normal sidevisning. Hold den deterministisk og lokal: Det er fint at læse en fil i temaet, men ikke at hente en ekstern API, da synkroniseringen så afhænger af, at tjenesten er tilgængelig.

Loader-sider markeres som genererede. Hvis en post forsvinder fra loaderens output, behandler næste synkronisering dens indlæg som forældreløst og håndterer det via filteret blockstudio/pages/orphan_action, som som standard flytter det til papirkurven.

En loader kan også returnere paths for at tilføje andre lokale mapper med Markdown til kollektionen, eventuelt under et præfiks. Mapper uden for kollektionens rod kræver filteret blockstudio/pages/allow_external_loader_path. Se Kollektionsloadere for den fulde struktur.

Trin 4: Synkroniser

Intet skrives til databasen, før du beder om det:

Shell
wp bs pages sync

Kommandoen finder alle sidekilder, registrerer indlægstypen acme_docs, opretter eller opdaterer indlæggene og udskriver en opsummeringsrække med antallene for discovered, created, updated, unchanged, removed og failed. Køres den igen uden ændringer, rapporteres alle sider som uændrede, og ingen indlæg skrives. Tilføj --format=json, hvis et implementeringsscript har brug for hele rapporten.

Efter synkroniseringen afspejler indlæggene filtræet. guide/install er en underside af guide, som er en underside af kollektionens rod, og hvert indlægs menurækkefølge er dets frontmatter-order. Kollektionens URL’er kombinerer kollektionens slug med hver sides logiske sti:

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

Du behøver ikke at gemme permalinks igen. Kollektionens rewrite-regler opdateres automatisk, når registrerede kollektionsindlægstyper ændres.

Gør synkroniseringen til en del af implementeringen. Frontend- og adminanmodninger finder aldrig sider, så en implementering, der kopierer nye Markdown-filer uden at køre wp bs pages sync, fortsætter med at vise det tidligere indhold.

Trin 5: Layoutet

Indlæggene findes nu, men hver side vises med temaets normale enkeltskabelon uden navigation. En layout.php ved siden af pages.json omslutter frontendvisningen af hver side i kollektionen:

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') returnerer kollektionen som indlejrede noder, sorteret efter order og derefter titel, med hvert nodes undersider i children. Her har den én rod, introduktionssiden, med de andre sider under sig. Hver node indeholder key, title, path og permalink. Ved at flade træet ud i denne rækkefølge får man læserækkefølgen, som er alt, hvad links til forrige og næste side behøver.

blockstudio_page_content() udskriver sideindholdet, som WordPress ville generere gennem the_content. Udelad det, og indholdet skjules. Ved /docs/guide/install/ af et websted på https://example.com gengiver layoutet dette (forkortet):

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>

Layoutet køres kun ved frontendanmodninger til enkeltsider i hovedløkken. Det ændrer ikke det gemte post_content og omslutter ikke editorens lærred. Stien gemmes på hvert synkroniseret indlæg og indgår i sidens fingeraftryk, så ændringer af layoutet træder i kraft ved næste synkronisering.

Læsning af kollektionsdata i PHP

Layoutets hjælpefunktioner er tynde omslag om klassen Blockstudio\Pages. Brug en af formerne i skabeloner, blokke eller plugins:

Hjælper Klassemetode Returnerer
blockstudio_pages('docs') Pages::pages('docs') Flad liste over samlingens sider, sorteret efter sidens nøgle
blockstudio_page_tree('docs') Pages::tree('docs') Indlejrede noder med children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Direkte undersider af én side
blockstudio_page_collection('docs') Pages::collection('docs') Samlingsdata fra manifestet
blockstudio_current_page() Pages::current_page() Siden, der gengives, eller null
Pages::get_page('docs-guide-install') Én side efter navn

Sidearrayer indeholder de synkroniserede post_id, permalink, name, key, title, path, order, collection, postType og arrayet meta. Ekstra frontmatter ender i meta, så et layout kan vise introduktionens resumé:

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

Ved frontend-anmodninger læser disse funktioner allerede synkroniserede indlæg og den konfiguration, der blev gemt ved den seneste synkronisering. De læser aldrig Markdown-filerne, så de kræver ingen filsystemadgang. Kun offentliggjorte sider er tilgængelige på frontend.

Rå Markdown til værktøjer

Da siderne kommer fra Markdown-filer, kan Blockstudio også levere den oprindelige kilde. Anmod om en side med suffikset .md, f.eks. /docs/guide/install.md, eller send Accept: text/markdown til den almindelige URL. Svaret udelader frontmatter og henviser tilbage til siden HTML med en kanonisk Link-header. Det er nyttigt for søgeindekser, assistenter og andre værktøjer, der læser ren tekst. Sider, der genereres fra inline-loaderindhold, har ingen kildefil og derfor intet .md-svar.

Slå det fra med ét filter:

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

Tips

Lad stierne definere strukturen. Flyt en fil, så følger dens sti, overordnede side og URL med ved næste synkronisering. Brug kun frontmatter path, når URL skal afvige fra filens placering.

Kombinér page.json med Markdown, når en side har brug for mere. En mappe med page.json og index.md bruger JSON til sideegenskaber som postId eller templateLock og Markdown til indhold. Frontmatter i index.md har forrang frem for tilsvarende værdier i page.json.

Skriv i filerne, ikke i editoren. Med templateLock: "contentOnly" kan redaktører rette tekst direkte, men næste synkronisering af en ændret kilde overskriver det gemte indhold med filens indhold. Brug Markdown som stedet, hvor dokumentationen skrives. En side, der i stedet skal tilhøre redaktørerne, får "sync": false i en page.json; almindelige synkroniseringer springer den derefter over, og Blockstudio\Pages::force_sync() opretter den én gang.

Det er sikkert at ændre indlægstypen. Hvis en samling skifter fra page til en brugerdefineret indlægstype, overføres allerede synkroniserede indlæg på stedet, når deres gemte identitet stemmer overens, så indlægs-id’er bevares.

Næste trin