Dokumentációs webhely létrehozása
A dokumentációnak az általa leírt kód mellett a helye. Az írók a Markdown megoldást részesítik előnyben, a lektorok a pull requestben szeretnék látni a változásokat, a kiadással pedig azonos commitban kell megjelennie a dokumentációnak. A WordPress ezzel szemben adatbázisbeli bejegyzéseket igényel: a keresés, a közvetlen hivatkozások, a változatok és a szerkesztő ott található.
A Blockstudio oldalkollekciók összekötik a kettőt. Az Markdown fájlok mappájából valódi WordPress bejegyzések lesznek, saját bejegyzéstípussal, URL alappal és szülő-gyermek hierarchiával. Egy layout.php fájl a kollekció minden oldalát az ugyanabból az adatból összeállított navigációval jeleníti meg. A forrás továbbra is a fájl, az adatbázisba pedig egy kifejezett szinkronizálási paranccsal írhatók be az oldalak.
Ez az útmutató lépésről lépésre épít fel egy kis dokumentációs részt a acme nevű témához: létrehoz egy jegyzéket, Markdown oldalakat és egy változásnaplót generáló betöltőt, elvégzi a szinkronizálást, majd oldalsávval és előző, illetve következő hivatkozásokkal ellátott elrendezést állít be.
Mit fog létrehozni
theme/
└── pages/
└── docs/
├── pages.json
├── layout.php
├── loader.php
├── index.md
├── getting-started.md
├── data/
│ └── releases.json
└── guide/
├── index.md
├── install.md
└── configure.md
A szinkronizálás után a kollekció ezeken az URL-eken érhető el:
| Forrás | Nyilvános 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/ |
| betöltő bejegyzése | /docs/changelog/ |
1. lépés: A kollekció jegyzéke
A kollekció egy mappa a pages/ könyvtáron belül, amely egy pages.json jegyzékfájlt tartalmaz. Hozza létre ezt: pages/docs/pages.json
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
A collection a kollekció slugja, ebből lesz a nyilvános URL alap. A postType a kollekció minden oldalát külön bejegyzéstípusba helyezi, így a dokumentációs oldalak nem keverednek az adminisztrációban a szokásos oldalakkal. Ha ez a bejegyzéstípus még nem létezik, a Blockstudio regisztrálja. Az alapértelmezett beállítások nyilvános, hierarchikus típust hoznak létre, amely elérhető a REST API között, és támogatja a címet, a szerkesztőt, az oldalattribútumokat, az indexképet, a kivonatot és a változatokat; az átírás slugja megegyezik a kollekció slugjával. A postTypeArgs ezeket az alapértékeket egészíti ki, ezért ez a jegyzék csak az adminisztrációs címkét módosítja.
A defaults minden oldalra alkalmazza az oldal tulajdonságait. Itt minden oldal közzététele szinkronizáláskor történik, és csak tartalmi szerkesztés engedélyezett, így a szerkesztők kijavíthatnak egy elírást a szerkesztőben, de nem rendezhetik át a Markdown által meghatározott szerkezetet.
2. lépés: Oldalak írása Markdown formátumban
Egy kollekción belül minden Markdown fájl egy oldal. A fájl helye határozza meg az azonosítóját, ezért az előtétadatok megadása nem kötelező. Használja a címet, a rendezési sorrendet és a később beolvasandó egyéb adatokat tartalmazó részt.
---
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
```
Az útmutató saját index.md fájllal rendelkező mappa; ez lesz a mellette található oldalak szülője:
---
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.
A Blockstudio minden fájlhoz logikai útvonalat és oldalnevet rendel:
| Fájl | Útvonal | Oldal neve |
|---|---|---|
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 |
A guide/install.md és a guide/install/index.md ugyanazt az útvonalat eredményezi, ezért később módosíthatja a lapos fájlt mappára anélkül, hogy megváltozna a URL.
A order rendezi a testvérelemeket, és a bejegyzés menüsorrendjébe kerül. A sorrend nélküli oldalak a rendezettek után, majd cím szerint következnek. Az olyan frontmatter-kulcsok, amelyeket a Blockstudio nem ismer fel, például a fenti description, megmaradnak az oldal meta tömbjében.
A szinkronizálás során a Markdown feldolgozása GitHub ízű Markdown formátumban történik, majd a rendszer HTML formátumra alakítja, végül natív blokkokká elemzi. A tárolt bejegyzés blokkokat tartalmaz, nem Markdown szöveget. A címsorok stabil horgonnyal rendelkeznek, a táblázatok core/table elemmé, az idézetblokkok core/quote elemmé alakulnak, a kódblokkok pedig core/preformatted blokká, amely megőrzi a nyelvosztályt. A telepítés oldalának tárolt tartalma (a szóközök levágása után):
<!-- 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 -->
3. lépés: Oldalak létrehozása betöltővel
Egyes oldalakat jobb generálni, mint megírni. Jó példa erre a változásnapló: a kiadási adatok már léteznek, kézi másolásuk a Markdown fájlba pedig eltérésekhez vezethet. A kollekció tartalmazhat egy loader.php elemet, amely további oldalak leírását adja vissza.
Tárolja a kiadási adatokat a kollekcióban:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Ezután készítsen belőlük egyetlen Markdown oldalt:
<?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',
),
),
);
A betöltő kifejezett felderítéskor és szinkronizáláskor fut, normál oldalmegtekintéskor soha. Gondoskodjon róla, hogy a működése determinisztikus és helyi legyen: a témafájl beolvasása rendben van, távoli API lekérése viszont nem, mert így a szinkronizálás egy külső szolgáltatás elérhetőségétől függne.
A betöltőoldalak generáltként vannak megjelölve. Ha egy bejegyzés eltűnik a betöltő kimenetéből, a következő szinkronizálás árva bejegyzésnek tekinti, és a blockstudio/pages/orphan_action szűrőn keresztül kezeli, amely alapértelmezés szerint a kukába helyezi.
A betöltő paths értéket is visszaadhat, amellyel más, helyi Markdown mappák csatlakoztathatók a kollekcióhoz, igény szerint előtaggal. A kollekció gyökérmappáján kívüli mappákhoz szükség van a blockstudio/pages/allow_external_loader_path szűrőre. A teljes szerkezetet a Kollekcióbetöltők részben találja.
4. lépés: Szinkronizálás
Az adatbázisba semmi nem kerül be, amíg nem kéri:
wp bs pages sync
A parancs felderíti az összes oldalforrást, regisztrálja a acme_docs bejegyzéstípust, létrehozza vagy frissíti a bejegyzéseket, és egy összesítő sort ír ki a következő értékekkel: discovered, created, updated, unchanged, removed és failed. Ha változás nélkül ismét futtatja, minden oldal változatlanként jelenik meg, és egyetlen bejegyzés sem íródik újra. Adja hozzá a --format=json elemet, ha egy telepítési szkriptnek a teljes jelentésre van szüksége.
A szinkronizálás után a bejegyzések tükrözik a fájlszerkezetet. A guide/install a guide gyermeke, amely a kollekció gyökerének gyermeke; az egyes bejegyzések menüsorrendjét pedig az előtétadatok order értéke adja. A kollekció URL-jei a kollekció slugjából és az oldalak logikai útvonalából állnak össze:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Nem kell újra mentenie a közvetlen hivatkozásokat. A kollekció átírási szabályai automatikusan frissülnek, amikor megváltoznak a regisztrált kollekciók bejegyzéstípusai.
Tegye a szinkronizálást a telepítés részévé. A frontend- és adminisztrációs kérések nem futtatnak oldalfelderítést, ezért ha egy telepítés új Markdown fájlokat másol fel, de nem futtatja a wp bs pages sync parancsot, továbbra is a korábbi tartalmat szolgálja ki.
5. lépés: Az elrendezés
A bejegyzések már léteznek, de mindegyik a téma szokásos egyedi sablonjával, navigáció nélkül jelenik meg. A pages.json melletti layout.php a kollekció minden oldalának frontend-megjelenítését körülöleli:
<?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>
A blockstudio_page_tree('docs') egymásba ágyazott csomópontokként adja vissza a kollekciót. A rendezés alapja a order, majd a cím; az egyes csomópontok gyermekei a children mezőben találhatók. Itt egyetlen gyökér van, a bevezető oldal, alatta pedig a többi oldal. Minden csomópont a következőket tartalmazza: key, title, path és permalink. A fa ilyen sorrendben történő kilapítása adja az olvasási sorrendet, amelyből az előző és következő hivatkozások összeállíthatók.
A blockstudio_page_content() kiírja az oldal törzsét, amelyet a WordPress a the_content segítségével renderelne. Hagyja ki, és a tartalom rejtve marad. Egy webhely https://example.com alatti /docs/guide/install/ nézetében az elrendezés ezt jeleníti meg (rövidítve):
<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>
Az elrendezés csak a fő ciklusban futó egyedi frontend-kéréseknél érvényes. Nem módosítja a tárolt post_content értéket, és nem vonja körül a szerkesztő vásznát. Az útvonala minden szinkronizált bejegyzésen tárolódik, és része az oldal ujjlenyomatának, így a módosított elrendezés a következő szinkronizáláskor lép életbe.
Kollekcióadatok beolvasása a PHP használatával
Az elrendezési segédfüggvények a Blockstudio\Pages osztályt használó egyszerű burkolók. Bármelyik alakot használhatja a sablonokban, blokkokban vagy bővítményekben:
| Segédfüggvény | Osztálymetódus | Visszatérési érték |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
A gyűjtemény oldalainak rendezett, lapkulcs szerint indexelt, lapos listája |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Beágyazott csomópontok children-val |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Egy oldal közvetlen gyermekei |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
A gyűjtemény adatai a jegyzékből |
blockstudio_current_page() |
Pages::current_page() |
A megjelenített oldal, vagy null |
Pages::get_page('docs-guide-install') |
Egy oldal név alapján |
Az oldaltömbök tartalmazzák a szinkronizált post_id, permalink, name, key, title,
path, order, collection, postType és a meta tömböt. A frontmatter további
adatai a meta helyre kerülnek, így az elrendezés megjelenítheti a bevezető összefoglalóját:
<?php $summary = $current['meta']['description'] ?? ''; ?>
A frontendkérések során ezek a függvények a már szinkronizált bejegyzéseket és az utolsó szinkronizáláskor eltárolt konfigurációt olvassák be. A Markdown fájlokat soha nem olvassák, így nem végeznek fájlrendszer-műveletet. A frontend csak közzétett oldalakat tesz elérhetővé.
Nyers Markdown az eszközök számára
Mivel az oldalak Markdown fájlokból származnak, a Blockstudio az eredeti forrást is kiszolgálhatja. Kérjen le egy oldalt .md végződéssel, például /docs/guide/install.md, vagy küldje el a Accept: text/markdown értéket a szokásos URL végpontra. A válaszból kimarad a frontmatter, és egy kanonikus Link fejléc mutat vissza az HTML oldalra. Ez hasznos a keresőindexelők, asszisztensek és más, egyszerű szöveget feldolgozó eszközök számára. Az inline betöltő tartalmából generált oldalaknak nincs forrásfájlja, ezért .md válaszuk sincs.
Kapcsolja ki egyetlen szűrővel:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Tippek
A struktúrát az útvonalak határozzák meg. Ha áthelyez egy fájlt, az útvonala, szülője és URL értéke a következő szinkronizáláskor követi. Csak akkor használja a frontmatter path mezőjét, ha a URL eltérjen a fájl helyétől.
Társítsa a page.json elemet a Markdown elemmel, ha egy oldalhoz többre van szükség. Az page.json és index.md fájlt tartalmazó mappa a JSON elemet használja az oldal tulajdonságaihoz, például a postId vagy a templateLock megadásához, a tartalomhoz pedig a Markdown elemet. A index.md frontmatter-adatai felülírják a velük egyező page.json értékeket.
A fájlokban írjon, ne a szerkesztőben. A templateLock: "contentOnly" használatakor a szerkesztők közvetlenül javíthatják a szöveget, de a módosított forrás következő szinkronizálása felülírja a tárolt tartalmat a fájl tartalmával. A dokumentációt a Markdown helyen írja. Ha egy oldalnak a szerkesztőkhöz kell tartoznia, adja hozzá a "sync": false elemet egy page.json fájlhoz; a szokásos szinkronizálások ezután kihagyják, a Blockstudio\Pages::force_sync() pedig egyszer létrehozza.
A bejegyzéstípus módosítása biztonságos. Ha egy gyűjtemény a page típusról egyéni bejegyzéstípusra vált, a már szinkronizált bejegyzések a helyükön migrálódnak, ha az eltárolt azonosítójuk megegyezik, így a bejegyzésazonosítók megmaradnak.
Következő lépések
- Oldalak referenciája: minden
page.jsonéspages.jsontulajdonság, betöltő, elrendezés és egyeztetési jelentés. - Fájlalapú oldalak készítése: sablonrögzítés, blokkszerkesztési módok és kulcsalapú összevonás az ügyfelek által szerkesztett oldalakhoz.
- Webhelyszerkesztő-sablonok és -részek fájlokból: ugyanez a fájlközpontú megközelítés fejlécekhez, láblécekhez és témasablonokhoz.