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
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:
{
"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.
---
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
```
Guidens sektion er en mappe med sin egen index.md, som bliver overordnet side
for siderne ved siden af den:
---
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 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):
<!-- 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:
[
{ "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
$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:
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:
/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
$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):
<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 $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:
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
- Sider – reference: hver egenskab for
page.jsonogpages.json, indlæsere, layouts og afstemningsrapporten. - Oprettelse af filbaserede sider: låsning af skabeloner, redigeringstilstande for blokke og nøglebaseret sammenfletning af sider, som kunder redigerer.
- Skabeloner og dele til webstedseditoren fra filer: samme filbaserede tilgang til sidehoveder, sidefødder og temas skabeloner.