Ugrás a tartalomhoz

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

Kód
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

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.

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

Az útmutató saját index.md fájllal rendelkező mappa; ez lesz a mellette található oldalak szülője:

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.

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

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

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:

JSON
[
  { "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
<?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:

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

Kód
/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
<?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):

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>

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

PHP
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