Preskočiť na obsah

Tvorba dokumentačného webu

Dokumentácia by mala byť uložená vedľa kódu, ktorý opisuje. Autori uprednostňujú Markdown, kontrolóri chcú vidieť zmeny v požiadavke na začlenenie a vydanie by malo obsahovať dokumentáciu v tom istom potvrdení. WordPress naopak potrebuje príspevky v databáze: tam sa nachádza vyhľadávanie, trvalé odkazy, revízie aj editor.

Kolekcie stránok Blockstudio spájajú oba prístupy. Priečinok so súbormi Markdown sa zmení na skupinu skutočných príspevkov WordPress s vlastným typom príspevkov, základnou cestou URL a hierarchiou nadradených a podradených stránok. Súbor layout.php obalí každú stránku kolekcie navigáciou vytvorenou z tých istých údajov. Súbory zostávajú jediným zdrojom pravdy a výslovný synchronizačný príkaz ich zapíše do databázy.

Táto príručka vás krok za krokom prevedie vytvorením malej dokumentačnej sekcie pre tému s názvom acme: od manifestu a stránok Markdown cez načítavač, ktorý vytvorí zoznam zmien, až po synchronizáciu a rozloženie s bočným panelom a odkazmi na predchádzajúcu a nasledujúcu stránku.

Čo vytvoríte

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

Po synchronizácii bude kolekcia dostupná na týchto adresách URL:

Zdroj Verejná 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/
položka načítavača /docs/changelog/

Krok 1: Manifest kolekcie

Kolekcia je priečinok v rámci pages/, ktorý obsahuje manifest pages.json. Vytvorte pages/docs/pages.json:

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

collection je identifikátor kolekcie a stane sa základnou verejnou cestou URL. postType priradí každej stránke kolekcie samostatný typ príspevku, aby sa dokumentácia v administrácii nemiešala s bežnými stránkami. Ak tento typ príspevkov ešte neexistuje, Blockstudio ho zaregistruje. Predvolené nastavenia registrácie sú: verejný a hierarchický typ, dostupný v REST API, s podporou názvu, editora, atribútov stránky, miniatúry, úryvku a revízií. Identifikátor pravidla prepisovania URL sa zhoduje s identifikátorom kolekcie. postTypeArgs sa zlúči s týmito predvolenými nastaveniami, takže tento manifest mení iba označenie v administrácii.

defaults nastavuje vlastnosti každej stránky v kolekcii. V tomto prípade sa každá stránka pri synchronizácii publikuje a povolí sa pri nej iba úprava obsahu. Redaktori tak môžu opraviť preklep v editore, ale nemôžu meniť štruktúru určenú v Markdown.

Krok 2: Písanie stránok v Markdown

V kolekcii predstavuje každý súbor Markdown jednu stránku. Jej identitu určuje umiestnenie súboru, takže predná časť nie je povinná. Použite ju na zadanie názvu, poradia a ďalších údajov, ktoré budete chcieť neskôr čítať.

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

Sekcia príručky je priečinok s vlastným index.md, ktorý sa stane nadradenou stránkou stránok vedľa neho:

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 odvodí logickú cestu a názov stránky z každého súboru:

Súbor Cesta Názov stránky
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 a guide/install/index.md vytvárajú rovnakú cestu, takže neskôr môžete prejsť z plochého súboru na priečinok bez zmeny URL.

order zoraďuje stránky na rovnakej úrovni a zapisuje sa do poradia ponuky príspevku. Stránky bez poradia sa zoradia po stránkach s poradím a následne podľa názvu. Kľúče prednej časti, ktoré Blockstudio nerozpozná, napríklad uvedený description, sa uložia do poľa meta stránky.

Počas synchronizácie sa Markdown analyzuje ako GitHub s rozšíreniami Markdown, prevedie sa na HTML a potom sa spracuje na natívne bloky. Uložený príspevok obsahuje bloky, nie text Markdown. Nadpisy dostanú stabilný kotviaci odkaz, tabuľky sa zmenia na core/table, citácie na core/quote a bloky ohraničené kódom na blok core/preformatted, ktorý zachová triedu jazyka. Takto vyzerá uložený obsah inštalačnej stránky (orezané medzery):

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

Krok 3: Generovanie stránok pomocou načítavača

Niektoré stránky je vhodnejšie generovať než písať. Dobrým príkladom je zoznam zmien: údaje o vydaniach už existujú a ich ručné kopírovanie do Markdown vedie k postupným nezhodám. Kolekcia môže obsahovať loader.php, ktorý vracia ďalšie definície stránok.

Údaje o vydaniach uchovávajte v kolekcii:

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

Potom z nich vytvorte jednu stránku Markdown:

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

Načítavač sa spúšťa počas výslovného vyhľadávania zdrojov a synchronizácie, nikdy pri bežnom zobrazení stránky. Zabezpečte, aby mal deterministické správanie a bežal lokálne: čítanie súboru v téme je v poriadku, načítavanie vzdialeného API nie, pretože synchronizácia by závisela od dostupnosti tejto služby.

Stránky načítavača sú označené ako generované. Ak výstup načítavača už neobsahuje nejakú položku, pri ďalšej synchronizácii sa jej príspevok považuje za osirelý a spracuje sa podľa filtra blockstudio/pages/orphan_action, ktorý ho predvolene presunie do koša.

Načítavač môže vrátiť aj paths a pripojiť tak do kolekcie ďalšie lokálne priečinky so súbormi Markdown, prípadne pod zvolenú predponu. Priečinky mimo koreňového priečinka kolekcie vyžadujú filter blockstudio/pages/allow_external_loader_path. Úplný prehľad možností nájdete v časti Načítavače kolekcií.

Krok 4: Synchronizácia

Do databázy sa nič nezapíše, kým o to nepožiadate:

Shell
wp bs pages sync

Príkaz vyhľadá všetky zdroje stránok, zaregistruje typ príspevku acme_docs, vytvorí alebo aktualizuje príspevky a vypíše súhrnný riadok s počtami discovered, created, updated, unchanged, removed a failed. Pri ďalšom spustení bez zmien sa všetky stránky označia ako nezmenené a žiadne príspevky sa nezapíšu. Ak nasadzovací skript potrebuje úplnú správu, pridajte --format=json.

Po synchronizácii príspevky kopírujú štruktúru stromu súborov. guide/install je podstránkou guide, ktorá je podstránkou koreňovej stránky kolekcie; poradie každého príspevku v ponuke určuje hodnota order z prednej časti. Adresy URL kolekcie kombinujú jej identifikátor s logickou cestou každej stránky:

Kód
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/

Trvalé odkazy nemusíte znova ukladať. Pravidlá prepisovania URL kolekcií sa automaticky obnovia pri zmene zaregistrovaných typov príspevkov kolekcie.

Zahrňte synchronizáciu do nasadenia. Požiadavky z frontendu ani administrácie nikdy nespúšťajú vyhľadávanie stránok, takže ak nasadíte nové súbory Markdown bez spustenia wp bs pages sync, naďalej sa bude zobrazovať predchádzajúci obsah.

Krok 5: Rozloženie

Príspevky už existujú, ale každý sa zobrazuje pomocou bežnej šablóny témy bez navigácie. Súbor layout.php vedľa pages.json obalí vykreslenie každej stránky kolekcie na frontende:

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') vráti kolekciu ako vnorené uzly zoradené podľa order a potom podľa názvu; deti každého uzla sú v children. V tomto prípade má jeden koreň, úvodnú stránku, pod ktorou sú ostatné stránky. Každý uzol obsahuje key, title, path a permalink. Zoradením stromu v tomto poradí vznikne postupnosť čítania, ktorú potrebujú odkazy na predchádzajúcu a nasledujúcu stránku.

blockstudio_page_content() vypíše telo stránky, ktoré by WordPress vykreslil cez the_content. Ak ho vynecháte, obsah zostane skrytý. Pri /docs/guide/install/ webu na adrese https://example.com sa rozloženie vykreslí takto (skrátené):

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>

Rozloženie sa spúšťa iba pri požiadavkách na jednotlivé stránky z frontendu v hlavnej slučke. Nemení uložený post_content ani neobalí plátno editora. Jeho cesta sa ukladá v každom synchronizovanom príspevku a je súčasťou odtlačku stránky, takže upravené rozloženie sa prejaví pri ďalšej synchronizácii.

Čítanie údajov kolekcie v PHP

Pomocné funkcie rozloženia sú tenké obaly okolo triedy Blockstudio\Pages. V šablónach, blokoch alebo pluginoch môžete použiť ktorúkoľvek z týchto foriem:

Pomocník Metóda triedy Návratová hodnota
blockstudio_pages('docs') Pages::pages('docs') Plochý zoznam stránok kolekcie zoradený podľa kľúča stránky
blockstudio_page_tree('docs') Pages::tree('docs') Vnorené uzly s children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Priame podstránky jednej stránky
blockstudio_page_collection('docs') Pages::collection('docs') Údaje kolekcie z manifestu
blockstudio_current_page() Pages::current_page() Práve vykresľovaná stránka alebo null
Pages::get_page('docs-guide-install') Jedna stránka podľa názvu

Polia stránok obsahujú synchronizované post_id, permalink, name, key, title, path, order, collection, postType a pole meta. Ďalšie údaje z frontmatter sa ukladajú do meta, takže rozloženie môže zobraziť súhrn úvodu:

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

Pri požiadavkách z frontendu tieto funkcie čítajú už synchronizované príspevky a konfiguráciu uloženú pri poslednej synchronizácii. Nikdy nečítajú súbory Markdown, takže nezaťažujú súborový systém. Na frontende sú dostupné iba publikované stránky.

Nespracované Markdown pre nástroje

Keďže stránky pochádzajú zo súborov Markdown, Blockstudio môže poskytovať aj pôvodný zdrojový obsah. Požiadajte o stránku s príponou .md, napríklad /docs/guide/install.md, alebo pošlite Accept: text/markdown na bežnú adresu URL. Odpoveď vynechá frontmatter a odkáže späť na stránku HTML pomocou hlavičky Link. Je to užitočné pre indexovače vyhľadávania, asistentov a ďalšie nástroje, ktoré pracujú s obyčajným textom. Stránky vytvorené z obsahu vloženého pomocou inline loadera nemajú zdrojový súbor, a preto pre ne nie je dostupná odpoveď .md.

Vypnite ho pomocou jedného filtra:

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

Tipy

Nechajte štruktúru určiť cestami. Po presunutí súboru sa pri ďalšej synchronizácii zmení jeho cesta, nadradený prvok aj URL. Frontmatter path použite iba vtedy, keď sa URL má líšiť od umiestnenia súboru.

Ak stránka potrebuje viac údajov, skombinujte page.json s Markdown. Priečinok s page.json a index.md používa JSON pre vlastnosti stránky, ako sú postId alebo templateLock, a Markdown pre obsah. Frontmatter v index.md má prednosť pred zodpovedajúcimi hodnotami page.json.

Píšte do súborov, nie v editore. Pri použití templateLock: "contentOnly" môžu editori opravovať text priamo, no pri ďalšej synchronizácii zmeneného zdroja sa uložený obsah prepíše podľa súboru. Za miesto na písanie dokumentácie považujte Markdown. Stránka určená editorom namiesto toho dostane "sync": false v page.json; bežné synchronizácie ju potom preskočia a Blockstudio\Pages::force_sync() ju vytvorí raz.

Zmena typu príspevku je bezpečná. Keď sa kolekcia zmení z page na vlastný typ príspevku, už synchronizované príspevky sa migrujú na svojom mieste, ak sa zhoduje ich uložená identita, takže ich ID zostanú zachované.

Ďalšie kroky