Tworzenie witryny z dokumentacją
Dokumentacja powinna znajdować się obok opisywanego kodu. Autorzy wolą Markdown, recenzenci chcą widzieć zmiany w pull requeście, a dokumentacja powinna być wydawana w tym samym commicie co dana wersja. WordPress z kolei przechowuje wpisy w bazie danych: tam znajdują się wyszukiwanie, bezpośrednie odnośniki, rewizje i edytor.
Blockstudio kolekcje stron łączą oba podejścia. Folder z plikami Markdown staje się zbiorem rzeczywistych wpisów WordPress z własnym typem wpisu, bazą URL oraz hierarchią stron nadrzędnych i podrzędnych. Plik layout.php opakowuje każdą stronę kolekcji w układ z nawigacją utworzoną na podstawie tych samych danych. Pliki pozostają źródłem prawdy, a jawne polecenie synchronizacji zapisuje je w bazie danych.
Ten przewodnik krok po kroku tworzy niewielką sekcję dokumentacji dla motywu o nazwie acme: manifest, strony Markdown, moduł ładujący generujący dziennik zmian, synchronizację oraz układ z paskiem bocznym i odnośnikami do poprzedniej i następnej strony.
Co utworzysz
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 synchronizacji kolekcja udostępnia te adresy URL:
| Źródło | Publiczny 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/ |
| wpis modułu ładującego | /docs/changelog/ |
Krok 1: Manifest kolekcji
Kolekcja to folder wewnątrz pages/ zawierający manifest pages.json. Utwórz pages/docs/pages.json:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection to uproszczona nazwa kolekcji, która staje się publiczną bazą URL. postType przypisuje każdą stronę kolekcji do osobnego typu wpisu, dzięki czemu dokumentacja nie miesza się ze zwykłymi stronami w panelu administracyjnym. Jeśli ten typ wpisu jeszcze nie istnieje, rejestruje go Blockstudio. Domyślne ustawienia rejestracji to: publiczny, hierarchiczny, dostępny w REST API, z obsługą tytułu, edytora, atrybutów strony, miniatury, zajawki i rewizji oraz z uproszczoną nazwą adresu równą nazwie kolekcji. postTypeArgs łączy się z tymi ustawieniami, zmieniając w tym manifeście jedynie etykietę w panelu administracyjnym.
defaults ustawia właściwości stron dla wszystkich stron kolekcji. Tutaj każda strona jest publikowana podczas synchronizacji i ma zablokowaną edycję do samej treści, więc redaktorzy mogą poprawić literówkę w edytorze, ale nie mogą zmienić struktury zdefiniowanej przez Markdown.
Krok 2: Tworzenie stron w Markdown
W kolekcji każdy plik Markdown jest stroną. Tożsamość strony wynika z lokalizacji pliku, więc sekcja frontmatter jest opcjonalna. Można w niej podać tytuł, kolejność sortowania i dodatkowe dane do późniejszego odczytu.
---
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
```
Sekcja przewodnika to folder z własnym plikiem index.md, który staje się stroną nadrzędną stron znajdujących się obok:
---
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 wyznacza ścieżkę logiczną i nazwę strony na podstawie każdego pliku:
| Plik | Ścieżka | Nazwa strony |
|---|---|---|
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 i guide/install/index.md dają tę samą ścieżkę, więc później można przejść z płaskiego pliku do folderu bez zmiany URL.
order sortuje strony podrzędne i jest zapisywane jako kolejność strony w menu. Strony bez określonej kolejności są sortowane po stronach z określoną kolejnością, a następnie według tytułu. Klucze frontmatter, których Blockstudio nie rozpoznaje, takie jak powyższe description, są zachowywane w tablicy meta strony.
Podczas synchronizacji Markdown jest przetwarzany jako GitHub z rozszerzeniami Markdown, konwertowany do HTML, a następnie przetwarzany na natywne bloki. Zapisany wpis zawiera bloki, a nie tekst Markdown. Nagłówki otrzymują stabilny kotwicznik, tabele są zamieniane na core/table, cytaty blokowe na core/quote, a bloki kodu na blok core/preformatted zachowujący klasę języka. Oto zapisana treść strony instalacyjnej (z przyciętymi białymi znakami):
<!-- 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: Generowanie stron za pomocą modułu ładującego
Niektóre strony lepiej generować niż pisać ręcznie. Dobrym przykładem jest dziennik zmian: dane o wydaniach już istnieją, a ręczne kopiowanie ich do Markdown grozi rozbieżnościami. Kolekcja może zawierać plik loader.php, który zwraca dodatkowe definicje stron.
Przechowuj dane o wydaniach w kolekcji:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Następnie utwórz na ich podstawie jedną stronę Markdown:
<?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',
),
),
);
Moduł ładujący działa podczas jawnego wykrywania i synchronizacji, nigdy przy zwykłym wyświetlaniu strony. Zadbaj, by jego działanie było deterministyczne i lokalne: odczyt pliku z motywu jest w porządku, ale pobieranie zdalnego API nie, ponieważ synchronizacja zależałaby wtedy od dostępności tej usługi.
Strony modułu ładującego są oznaczane jako wygenerowane. Jeśli wpis zniknie z jego wyników, podczas następnej synchronizacji wpis zostanie uznany za osierocony i obsłużony przez filtr blockstudio/pages/orphan_action, który domyślnie przenosi go do kosza.
Moduł ładujący może również zwrócić paths, aby dołączyć do kolekcji inne lokalne foldery zawierające Markdown, opcjonalnie z prefiksem. Foldery spoza katalogu głównego kolekcji wymagają filtra blockstudio/pages/allow_external_loader_path. Pełny opis struktury znajduje się w dokumentacji Loadery kolekcji.
Krok 4: Synchronizacja
Dopóki nie wydasz odpowiedniego polecenia, nic nie jest zapisywane w bazie danych:
wp bs pages sync
Polecenie wykrywa wszystkie źródła stron, rejestruje typ wpisu acme_docs, tworzy lub aktualizuje wpisy i drukuje wiersz podsumowania z liczbami discovered, created, updated, unchanged, removed i failed. Ponowne uruchomienie bez zmian oznacza każdą stronę jako niezmienioną i nie zapisuje żadnych wpisów. Dodaj --format=json, gdy skrypt wdrożeniowy potrzebuje pełnego raportu.
Po synchronizacji wpisy odzwierciedlają strukturę plików. guide/install jest stroną podrzędną guide, która jest stroną podrzędną katalogu głównego kolekcji, a kolejność wpisu w menu odpowiada wartości frontmatter order. Adresy URL kolekcji łączą uproszczoną nazwę kolekcji ze ścieżką logiczną każdej strony:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Nie trzeba ponownie zapisywać bezpośrednich odnośników. Reguły przepisywania adresów URL kolekcji są automatycznie odświeżane po zmianie zarejestrowanych typów wpisów kolekcji.
Uwzględnij synchronizację w procesie wdrożenia. Żądania z frontendu i panelu administracyjnego nigdy nie uruchamiają wykrywania stron, więc wdrożenie, które kopiuje nowe pliki Markdown bez uruchomienia wp bs pages sync, nadal będzie wyświetlać poprzednią treść.
Krok 5: Układ
Wpisy już istnieją, ale każdy z nich jest renderowany przy użyciu zwykłego szablonu pojedynczej strony motywu, bez nawigacji. Plik layout.php obok pages.json opakowuje renderowanie każdej strony kolekcji we frontendzie:
<?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') zwraca kolekcję jako zagnieżdżone węzły posortowane według order, a następnie tytułu; elementy podrzędne każdego węzła znajdują się w children. Tutaj istnieje jeden węzeł główny — strona wprowadzająca — a pozostałe strony znajdują się pod nim. Każdy węzeł zawiera key, title, path i permalink. Spłaszczenie drzewa w tej kolejności daje kolejność czytania potrzebną do utworzenia odnośników do poprzedniej i następnej strony.
blockstudio_page_content() wyświetla treść strony, którą WordPress wyrenderowałoby za pośrednictwem the_content. Jeśli go pominiesz, treść będzie ukryta. Podczas /docs/guide/install/ witryny pod adresem https://example.com układ renderuje następujący fragment (po przycięciu):
<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>
Układ działa tylko przy żądaniach frontendowych dotyczących pojedynczych wpisów w głównej pętli. Nie zmienia zapisanej wartości post_content ani nie opakowuje obszaru edytora. Jego ścieżka jest zapisywana w każdym zsynchronizowanym wpisie i stanowi część odcisku strony, więc zmodyfikowany układ zostanie uwzględniony podczas następnej synchronizacji.
Odczyt danych kolekcji w PHP
Funkcje pomocnicze układu to proste opakowania klasy Blockstudio\Pages. W szablonach, blokach i wtyczkach można użyć jednej z tych form:
| Pomocnik | Metoda klasy | Zwraca |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Płaska lista stron kolekcji, uporządkowana według klucza strony |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Zagnieżdżone węzły z children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Bezpośrednie strony podrzędne jednej strony |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Dane kolekcji z manifestu |
blockstudio_current_page() |
Pages::current_page() |
Renderowana strona lub null |
Pages::get_page('docs-guide-install') |
Jedna strona według nazwy |
Tablice stron zawierają zsynchronizowane post_id, permalink, name, key, title,
path, order, collection, postType oraz tablicę meta. Dodatkowe dane z frontmatter trafiają do meta, dzięki czemu układ może wyświetlić podsumowanie wprowadzenia:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Podczas żądań z frontendu te funkcje odczytują już zsynchronizowane wpisy i konfigurację zapisaną przy ostatniej synchronizacji. Nigdy nie odczytują plików Markdown, więc nie wykonują operacji na systemie plików. Na frontendzie dostępne są tylko opublikowane strony.
Surowy Markdown dla narzędzi
Ponieważ strony pochodzą z plików Markdown, Blockstudio może też udostępniać oryginalne źródło. Żądaj strony z przyrostkiem .md, na przykład /docs/guide/install.md, albo wyślij Accept: text/markdown do zwykłego URL. Odpowiedź pomija frontmatter i wskazuje z powrotem stronę HTML za pomocą nagłówka canonical Link. Przydaje się to indeksatorom wyszukiwarek, asystentom i innym narzędziom odczytującym zwykły tekst. Strony wygenerowane z zawartości wbudowanej w loader nie mają pliku źródłowego, a zatem nie otrzymują odpowiedzi .md.
Wyłącz to za pomocą jednego filtra:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Wskazówki
Pozwól ścieżkom określać strukturę. Przenieś plik, a jego ścieżka, element nadrzędny i URL zostaną zaktualizowane przy następnej synchronizacji. Używaj frontmatter path tylko wtedy, gdy URL ma się różnić od lokalizacji pliku.
Połącz page.json z Markdown, gdy strona potrzebuje więcej. Folder zawierający page.json i index.md używa JSON dla właściwości strony, takich jak postId lub templateLock, a Markdown dla treści. Wartości frontmatter w index.md mają pierwszeństwo przed pasującymi wartościami page.json.
Pisz w plikach, nie w edytorze. W przypadku templateLock: "contentOnly" edytorzy mogą poprawiać tekst bezpośrednio, ale następna synchronizacja zmienionego źródła zastępuje zapisaną treść zawartością pliku. Za miejsce tworzenia dokumentacji uznaj Markdown. Strona, która ma należeć do edytorów, otrzymuje zamiast tego "sync": false w page.json; zwykłe synchronizacje ją pomijają, a Blockstudio\Pages::force_sync() tworzy ją raz.
Zmiana typu wpisu jest bezpieczna. Jeśli kolekcja przechodzi z page na niestandardowy typ wpisu, już zsynchronizowane wpisy są migrowane w miejscu, gdy pasuje ich zapisana tożsamość, dzięki czemu identyfikatory wpisów pozostają bez zmian.
Następne kroki
- Dokumentacja stron: wszystkie właściwości
page.jsonipages.json, loadery, układy oraz raport uzgadniania. - Tworzenie stron na podstawie plików: blokowanie szablonów, tryby edycji bloków i scalanie według kluczy dla stron edytowanych przez klientów.
- Szablony i części edytora witryny z plików: to samo podejście oparte na plikach dla nagłówków, stopek i szablonów motywów.