Bygga en dokumentationswebbplats
Dokumentation hör hemma intill koden den beskriver. Skribenter föredrar Markdown, granskare vill se ändringar i en pull request och en version bör leverera dokumentationen i samma commit. WordPress vill däremot ha inlägg i databasen: där finns sökning, permalänkar, versioner och redigeraren.
Blockstudio-sidsamlingar förenar de två. En mapp med Markdown-filer blir en uppsättning riktiga WordPress-inlägg med en egen inläggstyp, en URL-bas samt en hierarki med över- och undersidor. En layout.php-fil omsluter varje sida i samlingen med navigering som byggs från samma data. Filerna förblir den enda sanningskällan, och ett uttryckligt synkroniseringskommando skriver in dem i databasen.
Den här guiden bygger steg för steg en liten dokumentationssektion för ett tema som heter acme: ett manifest, sidor i Markdown, en laddare som genererar en ändringslogg, synkroniseringen och en layout med sidofält samt föregående- och nästalänkar.
Det här ska du bygga
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 synkroniseringen visas följande URL:er för samlingen:
| Källa | 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/ |
| laddarpost | /docs/changelog/ |
Steg 1: Samlingens manifest
En samling är en mapp i pages/ som innehåller ett pages.json-manifest. Skapa pages/docs/pages.json:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection är samlingens kortnamn och blir den offentliga URL-basen. postType skickar varje sida i samlingen till en särskild inläggstyp, så att dokumentationen inte blandas med vanliga sidor i adminpanelen. Om inläggstypen inte redan finns registrerar Blockstudio den. Standardinställningarna för registreringen är offentlig, hierarkisk och tillgänglig i REST API, med stöd för titel, redigerare, sidattribut, miniatyrbild, utdrag och versioner samt en omskrivningsslug som är lika med samlingens slug. postTypeArgs slås ihop med standardinställningarna, så det här manifestet ändrar bara adminetiketten.
defaults tillämpar sidegenskaper på varje sida i samlingen. Här publiceras varje sida vid synkroniseringen och den låses till innehållsbaserad redigering. Redaktörer kan rätta stavfel i redigeraren, men inte ändra strukturen som Markdown definierar.
Steg 2: Skriv sidorna i Markdown
I en samling är varje Markdown-fil en sida. Filens plats anger identiteten, så frontmatter är valfritt. Använd det för titeln, sorteringsordningen och andra data som du vill läsa senare.
---
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
```
Guidesektionen är en mapp med ett eget index.md, som blir överordnad de närliggande sidorna:
---
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 härleder en logisk sökväg och ett sidnamn från varje fil:
| Fil | Sökväg | Sidnamn |
|---|---|---|
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 och guide/install/index.md ger samma sökväg, så du kan senare växla mellan en platt fil och en mapp utan att ändra URL.
order sorterar syskonsidor och skrivs till inläggets menyordning. Sidor utan ordning sorteras efter sidor med ordning och sedan efter titel. Frontmatter-nycklar som Blockstudio inte känner igen, till exempel description ovan, behålls i sidans meta-array.
Vid synkronisering tolkas Markdown som GitHub Flavored Markdown, konverteras till HTML och tolkas sedan som inbyggda block. Det sparade inlägget innehåller block, inte Markdown-text. Rubriker får ett stabilt ankare, tabeller blir core/table, citatblock blir core/quote och kodblock blir ett core/preformatted-block som behåller språkklassen. Här visas installationens sparade innehåll (inledande och avslutande blanksteg borttagna):
<!-- 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 -->
Steg 3: Generera sidor med en laddare
Vissa sidor lämpar sig bättre för att genereras än för att skrivas för hand. En ändringslogg är ett bra exempel: versionsdata finns redan, och om den kopieras till Markdown för hand kan innehållet börja avvika. En samling kan innehålla en loader.php som returnerar ytterligare siddefinitioner.
Behåll versionsdata i samlingen:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Skapa sedan en enda Markdown-sida från den:
<?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',
),
),
);
Laddaren körs vid uttrycklig identifiering och synkronisering, aldrig vid visning av en vanlig sida. Se till att den är deterministisk och lokal: det går bra att läsa en fil i temat, men hämta inte en fjärrbaserad API, eftersom synkroniseringen då skulle vara beroende av att tjänsten är tillgänglig.
Laddarsidor markeras som genererade. Om en post saknas i laddarens utdata behandlar nästa synkronisering dess inlägg som överblivet och hanterar det via filtret blockstudio/pages/orphan_action, som som standard flyttar det till papperskorgen.
En laddare kan även returnera paths för att montera andra lokala mappar med Markdown i samlingen, eventuellt under ett prefix. Mappar utanför samlingens rot kräver filtret blockstudio/pages/allow_external_loader_path. Mer information finns i Samlingsladdare om hur det fungerar.
Steg 4: Synkronisera
Inget skrivs till databasen förrän du ber om det:
wp bs pages sync
Kommandot hittar alla sidkällor, registrerar inläggstypen acme_docs, skapar eller uppdaterar inläggen och skriver ut en sammanfattningsrad med antal för discovered, created, updated, unchanged, removed och failed. Om du kör det igen utan ändringar rapporteras alla sidor som oförändrade och inga inlägg skrivs. Lägg till --format=json när ett driftsättningsskript behöver hela rapporten.
Efter synkroniseringen speglar inläggen filträdet. guide/install är en undersida till guide, som är en undersida till samlingens rot, och varje inläggs menyordning hämtas från frontmatter order. Samlingens URL:er kombinerar samlingens slug med varje sidas logiska sökväg:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Du behöver inte spara om permalänkarna. Omskrivningsreglerna för samlingen rensas automatiskt när de registrerade inläggstyperna för samlingen ändras.
Gör synkroniseringen till en del av driftsättningen. Frontend- och adminförfrågningar kör aldrig sididentifiering, så en driftsättning som kopierar nya Markdown-filer utan att köra wp bs pages sync fortsätter att visa det tidigare innehållet.
Steg 5: Layouten
Inläggen finns nu, men vart och ett återges med temats vanliga singelmall och utan navigering. En layout.php bredvid pages.json omsluter frontendåtergivningen för varje sida i samlingen:
<?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') returnerar samlingen som nästlade noder, sorterade efter order och sedan titel, med varje nods undersidor i children. Här finns en rot, introduktionssidan, med övriga sidor under den. Varje nod innehåller key, title, path och permalink. Om trädet plattas ut i den ordningen får man läsordningen som alla föregående- och nästalänkar behöver.
blockstudio_page_content() skriver ut sidans innehåll som WordPress skulle rendera via the_content. Utelämna den så döljs innehållet. Vid /docs/guide/install/ av en webbplats på https://example.com renderar layouten detta (förkortat):
<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>
Layouten körs endast vid frontendförfrågningar för enskilda objekt i huvudloopen. Den ändrar inte det sparade post_content och omsluter inte redigerarens arbetsyta. Sökvägen sparas på varje synkroniserat inlägg och ingår i sidans fingeravtryck, så en ändrad layout hämtas vid nästa synkronisering.
Läsa samlingsdata i PHP
Layoutens hjälpfunktioner är tunna omslag runt klassen Blockstudio\Pages. Använd valfri form i mallar, block eller tillägg:
| Hjälpfunktion | Klassmetod | Returnerar |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Platt lista över samlingens sidor, sorterade efter sidnyckel |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Nästlade noder med children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Direkta undersidor till en sida |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Samlingsdata från manifestet |
blockstudio_current_page() |
Pages::current_page() |
Sidan som renderas, eller null |
Pages::get_page('docs-guide-install') |
En sida efter namn |
Sidarrayer innehåller de synkroniserade post_id, permalink, name, key, title,
path, order, collection, postType och arrayen meta. Extra frontmatter hamnar i meta, så en layout kan skriva ut introduktionens sammanfattning:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Vid frontendförfrågningar läser dessa funktioner redan synkroniserade inlägg och konfigurationen som sparades vid den senaste synkroniseringen. De läser aldrig filerna Markdown, så de kräver inget filsystemsarbete. Endast publicerade sidor är tillgängliga i frontend.
Råa Markdown för verktyg
Eftersom sidorna kommer från Markdown-filer kan Blockstudio också tillhandahålla
originalkällan. Begär en sida med suffixet .md, till exempel
/docs/guide/install.md, eller skicka Accept: text/markdown till den vanliga URL. Svaret utelämnar frontmatter och pekar tillbaka på sidan HTML med en kanonisk Link-header. Det är användbart för sökindexerare, assistenter och andra verktyg som läser oformaterad text. Sidor som genereras från inline-loaderinnehåll har ingen källfil och därför inget .md-svar.
Stäng av det med ett filter:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Tips
Låt sökvägarna bära strukturen. Flytta en fil, så följer dess sökväg, överordnade sida och URL med vid nästa synkronisering. Använd frontmatter path endast när URL ska skilja sig från filens plats.
Kombinera page.json med Markdown när en sida behöver mer. En mapp med page.json och index.md använder JSON för sidegenskaper som postId eller templateLock och Markdown för innehåll. Frontmatter i index.md har företräde framför matchande värden i page.json.
Skriv i filerna, inte i redigeraren. Med templateLock: "contentOnly" kan redigerare korrigera text direkt, men nästa synkronisering av en ändrad källa skriver över det lagrade innehållet med filens innehåll. Se Markdown som platsen där dokumentationen skrivs. En sida som i stället ska tillhöra redigerarna får "sync": false i en page.json; vanliga synkroniseringar hoppar då över den, och Blockstudio\Pages::force_sync() skapar den en gång.
Det är säkert att ändra inläggstyp. Om en samling flyttas från page till en anpassad inläggstyp migreras redan synkroniserade inlägg på plats när deras lagrade identitet matchar, så inläggs-ID:n består.
Nästa steg
- Referens för sidor: varje
page.json– ochpages.json-egenskap, loaders, layouter och avstämningsrapporten. - Skapa filbaserade sidor: mallåsning, redigeringslägen för block och nyckelbaserad sammanslagning för sidor som klienter redigerar.
- Mallar och delar för webbplatsredigeraren från filer: samma filbaserade arbetssätt för sidhuvuden, sidfötter och temamallar.