Přejít k obsahu

Tvorba dokumentačního webu

Dokumentace by měla být uložena vedle kódu, který popisuje. Autoři dávají přednost Markdown, recenzenti chtějí změny vidět v pull requestu a vydání by mělo obsahovat dokumentaci ve stejném commitu. WordPress naopak potřebuje příspěvky v databázi: tam se nachází vyhledávání, trvalé odkazy, revize i editor.

Blockstudio kolekce stránek tyto dva požadavky propojují. Složka souborů Markdown se změní na sadu skutečných příspěvků WordPress s vlastním typem příspěvku, základem URL a hierarchií nadřazených a podřízených stránek. Soubor layout.php obaluje každou stránku v kolekci navigací vytvořenou ze stejných dat. Soubory zůstávají hlavním zdrojem pravdy a výslovný synchronizační příkaz je zapisuje do databáze.

Tento průvodce krok za krokem vytvoří malou sekci dokumentace pro motiv s názvem acme: manifest, stránky Markdown, načítač generující changelog, synchronizaci a rozvržení s postranním panelem a odkazy na předchozí a následující stránku.

Co vytvoří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 synchronizaci budou stránky kolekce dostupné na těchto adresách URL:

Zdroj Veřejná 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čítače /docs/changelog/

Krok 1: Manifest kolekce

Kolekce je složka v pages/ obsahující manifest pages.json. Vytvořte pages/docs/pages.json:

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

collection je název kolekce používaný v adrese URL a stává se veřejným základem URL. postType předává každou stránku kolekce vyhrazenému typu příspěvku, aby se dokumentace v administraci nemíchala s běžnými stránkami. Pokud tento typ příspěvku ještě neexistuje, zaregistruje jej Blockstudio. Výchozí nastavení registrace jsou veřejná, hierarchická a dostupná v REST API s podporou názvu, editoru, atributů stránky, náhledového obrázku, stručného popisu a revizí; název pro přepis adresy URL odpovídá názvu kolekce. postTypeArgs se sloučí s těmito výchozími hodnotami, takže tento manifest mění pouze štítek v administraci.

defaults nastavuje vlastnosti stránek pro každou stránku v kolekci. Zde se při synchronizaci publikuje každá stránka a povoluje se pouze úprava obsahu. Redaktoři tak mohou v editoru opravit překlep, ale nemohou přeuspořádat strukturu definovanou v Markdown.

Krok 2: Pište stránky v Markdown

Každý soubor Markdown v kolekci představuje stránku. Její identitu určuje umístění souboru, takže frontmatter je volitelný. Použijte ho pro název, pořadí řazení a další údaje, které budete chtít později číst.

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

Sekce průvodce je složka s vlastním index.md, který se stává nadřazenou stránkou stránek ve stejné složce:

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í z každého souboru logickou cestu a název stránky:

Soubor Cesta Název 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ářejí stejnou cestu, takže později můžete přejít mezi samostatným souborem a složkou, aniž by se změnila URL.

order řadí sourozenecké stránky a ukládá se do pořadí nabídky příspěvku. Stránky bez pořadí se řadí za stránky s nastaveným pořadím a poté podle názvu. Klíče frontmatteru, které Blockstudio nezná, například výše uvedené description, se zachovávají v poli meta stránky.

Při synchronizaci se Markdown parsuje jako GitHub Flavored Markdown, převádí na HTML a následně parsuje do nativních bloků. Uložený příspěvek obsahuje bloky, nikoli text Markdown. Nadpisy dostávají stabilní kotvu, tabulky se mění na core/table, citace na core/quote a oplocené bloky kódu na blok core/preformatted, který zachovává třídu jazyka. Takto vypadá uložený obsah instalační stránky (oříznuté bílé znaky):

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: Generování stránek pomocí načítače

Některé stránky je lepší generovat než psát ručně. Dobrým příkladem je changelog: údaje o vydání už existují a jejich ruční kopírování do Markdown vede k nesrovnalostem. Kolekce může obsahovat loader.php, který vrací další definice stránek.

Údaje o vydání ponechte v kolekci:

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

Pak z nich vytvořte 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čítač se spouští při výslovném vyhledání a synchronizaci, nikdy při běžném zobrazení stránky. Zajistěte deterministické a lokální zpracování: čtení souboru v motivu je v pořádku, načítání vzdáleného API nikoli, protože synchronizace by pak závisela na dostupnosti této služby.

Stránky načítače jsou označeny jako generované. Pokud některá položka zmizí z výstupu načítače, další synchronizace bude její příspěvek považovat za osiřelý a zpracuje jej pomocí filtru blockstudio/pages/orphan_action, který jej ve výchozím nastavení přesune do koše.

Načítač může také vrátit paths a připojit tak do kolekce další místní složky obsahující Markdown, případně pod zadanou předponou. Složky mimo kořen kolekce vyžadují filtr blockstudio/pages/allow_external_loader_path. Úplný popis najdete v části Načítače kolekcí.

Krok 4: Synchronizace

Do databáze se nic nezapíše, dokud o to nepožádáte:

Shell
wp bs pages sync

Příkaz vyhledá všechny zdroje stránek, zaregistruje typ příspěvku acme_docs, vytvoří nebo aktualizuje příspěvky a vypíše souhrnný řádek s počty discovered, created, updated, unchanged, removed a failed. Při opětovném spuštění bez změn budou všechny stránky označeny jako nezměněné a žádné příspěvky se nezapíší. Pokud skript nasazení potřebuje úplnou zprávu, přidejte --format=json.

Po synchronizaci příspěvky zrcadlí strom souborů. guide/install je podřízenou stránkou guide, která je podřízenou stránkou kořene kolekce; pořadí nabídky každého příspěvku odpovídá hodnotě frontmatteru order. Adresy URL kolekce tvoří název kolekce a logická cesta každé stránky:

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

Trvalé odkazy není třeba znovu ukládat. Pravidla pro přepis adres kolekcí se automaticky obnoví při změně registrovaných typů příspěvků kolekce.

Zařaďte synchronizaci do nasazení. Požadavky frontendu a administrace vyhledávání stránek nikdy nespouštějí, takže nasazení, které zkopíruje nové soubory Markdown bez spuštění wp bs pages sync, bude dál zobrazovat předchozí obsah.

Krok 5: Rozvržení

Příspěvky už existují, ale každý se vykresluje pomocí běžné šablony jednotlivého příspěvku motivu a bez navigace. Soubor layout.php vedle pages.json obaluje vykreslení všech stránek kolekce na frontendu:

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') vrací kolekci jako vnořené uzly seřazené podle order a poté podle názvu; děti každého uzlu jsou v children. Zde má jeden kořen, úvodní stránku, pod níž se nacházejí ostatní stránky. Každý uzel obsahuje key, title, path a permalink. Zploštěním stromu v tomto pořadí vznikne posloupnost stránek, kterou potřebují odkazy na předchozí a následující stránku.

blockstudio_page_content() vypíše tělo stránky, které by WordPress vykreslil prostřednictvím the_content. Pokud jej vynecháte, obsah zůstane skrytý. Při /docs/guide/install/ webu na https://example.com vykreslí rozvržení toto (zkráceno):

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>

Rozvržení se spouští pouze při požadavcích na jednotlivé stránky frontendu v hlavní smyčce. Nemění uložené post_content a neobaluje plátno editoru. Jeho cesta se ukládá do každého synchronizovaného příspěvku a je součástí otisku stránky, takže upravené rozvržení se použije při další synchronizaci.

Čtení dat kolekce v PHP

Pomocné funkce rozvržení jsou tenké obaly kolem třídy Blockstudio\Pages. V šablonách, blocích nebo pluginech použijte kteroukoli z těchto podob:

Pomocná funkce Metoda třídy Vrací
blockstudio_pages('docs') Pages::pages('docs') Plochý seznam stránek kolekce seřazený podle klíče stránky
blockstudio_page_tree('docs') Pages::tree('docs') Vnořené uzly s children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Přímé podřízené stránky
blockstudio_page_collection('docs') Pages::collection('docs') Data kolekce z manifestu
blockstudio_current_page() Pages::current_page() Právě vykreslovaná stránka nebo null
Pages::get_page('docs-guide-install') Stránka podle názvu

Pole stránek obsahují synchronizované post_id, permalink, name, key, title, path, order, collection, postType a pole meta. Další údaje z frontmatter se ukládají do meta, takže rozvržení může zobrazit shrnutí úvodu:

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

Při požadavcích z frontendu tyto funkce čtou již synchronizované příspěvky a konfiguraci uloženou při poslední synchronizaci. Soubory Markdown nikdy nečtou, takže nezatěžují souborový systém. Na frontendu jsou dostupné pouze publikované stránky.

Původní Markdown pro nástroje

Protože stránky pocházejí ze souborů Markdown, může Blockstudio poskytovat i původní zdroj. Vyžádejte si stránku s příponou .md, například /docs/guide/install.md, nebo pošlete Accept: text/markdown na běžnou adresu URL. Odpověď neobsahuje frontmatter a odkazuje zpět na stránku HTML pomocí hlavičky canonical Link. To se hodí pro vyhledávací indexery, asistenty a další nástroje, které čtou prostý text. Stránky generované z obsahu vloženého pomocí inline loaderu nemají zdrojový soubor, a proto nevracejí odpověď .md.

Vypněte to pomocí jediného filtru:

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

Tipy

Strukturu určují cesty. Přesuňte soubor a při příští synchronizaci se přesune i jeho cesta, nadřazená stránka a URL. Frontmatter path použijte jen tehdy, když se má URL lišit od umístění souboru.

Když stránka potřebuje víc, kombinujte page.json s Markdown. Složka s page.json a index.md používá JSON pro vlastnosti stránky, jako jsou postId nebo templateLock, a Markdown pro obsah. Hodnoty frontmatter v index.md mají přednost před shodnými hodnotami page.json.

Upravujte soubory, ne editor. S templateLock: "contentOnly" mohou editoři opravovat text přímo na místě, ale při další synchronizaci změněného zdroje se uložený obsah přepíše podle souboru. Považujte Markdown za místo, kde se dokumentace píše. Stránka, kterou mají spravovat editoři, místo toho dostane "sync": false v page.json; běžné synchronizace ji pak přeskočí a Blockstudio\Pages::force_sync() ji vytvoří jednou.

Změna typu příspěvku je bezpečná. Pokud se kolekce přesune z page na vlastní typ příspěvku, již synchronizované příspěvky se na místě převedou, pokud odpovídá jejich uložená identita, takže ID příspěvků zůstanou zachována.

Další kroky