Створення сайту документації
Документації місце поруч із кодом, який вона описує. Автори віддають перевагу Markdown, рецензенти хочуть бачити зміни в запиті на злиття, а документація має входити до релізу в тому самому коміті. WordPress, зі свого боку, зберігає записи в базі даних: саме там працюють пошук, постійні посилання, редакції та редактор.
Колекції сторінок Blockstudio поєднують ці два підходи. Папка з файлами Markdown перетворюється на набір повноцінних записів WordPress із власним типом записів, базовим шляхом URL та ієрархією батьківських і дочірніх сторінок. Файл layout.php огортає кожну сторінку колекції навігацією, побудованою на тих самих даних. Файли залишаються єдиним джерелом істини, а окрема команда синхронізації записує їх у базу даних.
У цьому посібнику крок за кроком створюється невеликий розділ документації для теми acme: маніфест, сторінки Markdown, завантажувач для створення журналу змін, синхронізація та макет із бічною панеллю й посиланнями на попередню та наступну сторінки.
Що ви створите
theme/
└── pages/
└── docs/
├── pages.json
├── layout.php
├── loader.php
├── index.md
├── getting-started.md
├── data/
│ └── releases.json
└── guide/
├── index.md
├── install.md
└── configure.md
Після синхронізації колекція відповідатиме за ці URL:
| Джерело | Публічний 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/ |
| запис завантажувача | /docs/changelog/ |
Крок 1: Маніфест колекції
Колекція — це папка в pages/, що містить маніфест pages.json.
Створіть pages/docs/pages.json:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection — це ідентифікатор колекції, який стає базовим шляхом публічного URL. postType спрямовує кожну сторінку колекції до окремого типу записів, тож документація не змішується зі звичайними сторінками в адмінпанелі. Якщо такого типу записів ще немає, його реєструє Blockstudio. Тип записів за замовчуванням є публічним та ієрархічним і доступний у REST API; він підтримує заголовок, редактор, атрибути сторінки, мініатюру, уривок і редакції, а його ідентифікатором шляху є ідентифікатор колекції. Значення postTypeArgs об’єднуються з цими параметрами за замовчуванням, тож цей маніфест змінює лише мітку в адмінпанелі.
defaults задає властивості сторінок для кожної сторінки колекції. Тут усі сторінки публікуються під час синхронізації та дозволяють редагувати лише вміст: редактори можуть виправити друкарську помилку в редакторі, але не можуть змінити структуру, визначену Markdown.
Крок 2: Напишіть сторінки в Markdown
У колекції кожен файл 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/).
---
title: Getting Started
order: 10
---
# Getting Started
Install the theme, then activate it under **Appearance > Themes**.
```bash
wp theme activate acme
```
Розділ посібника — це папка з власним index.md, який стає батьківською сторінкою для сторінок поруч із ним:
---
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 визначає логічний шлях і назву сторінки для кожного файла:
| Файл | Шлях | Назва сторінки |
|---|---|---|
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 і guide/install/index.md мають однаковий шлях, тож пізніше можна
перейти від окремого файла до папки, не змінюючи URL.
order упорядковує сусідні сторінки, а його значення записується в порядок меню запису. Сторінки без заданого порядку відображаються після сторінок із порядком, а далі сортуються за заголовком. Ключі метаданих на початку файла, які Blockstudio не розпізнає, як-от наведений вище description, зберігаються в масиві meta сторінки.
Під час синхронізації Markdown обробляється як GitHub Flavored Markdown, перетворюється на HTML, а потім розбирається на нативні блоки. Збережений запис містить блоки, а не текст Markdown. Заголовки отримують стабільний якір, таблиці стають core/table, цитати — core/quote, а блоки коду з роздільниками перетворюються на блок core/preformatted зі збереженим класом мови. Нижче наведено збережений вміст сторінки встановлення (пробільні символи обрізано):
<!-- 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: Створення сторінок за допомогою завантажувача
Деякі сторінки краще генерувати, а не писати вручну. Журнал змін — гарний приклад: дані про релізи вже є, а ручне копіювання їх у Markdown може призвести до розбіжностей. До колекції можна додати loader.php, який повертає додаткові визначення сторінок.
Зберігайте дані про релізи в колекції:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Потім створіть на їх основі одну сторінку 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',
),
),
);
Завантажувач запускається під час явного пошуку та синхронізації, але не під час звичайного перегляду сторінки. Забезпечте передбачувану роботу й локальне виконання: читати файл у темі можна, а завантажувати віддалений API — ні, адже тоді синхронізація залежатиме від доступності цієї служби.
Сторінки завантажувача позначаються як згенеровані. Якщо запис зникає з результатів завантажувача, під час наступної синхронізації його запис стає осиротілим і обробляється фільтром blockstudio/pages/orphan_action, який за замовчуванням переміщує його до кошика.
Завантажувач також може повертати paths, щоб додати до колекції інші локальні папки з Markdown, за бажанням із префіксом. Для папок за межами кореня колекції потрібен фільтр blockstudio/pages/allow_external_loader_path. Повний опис наведено в розділі Завантажувачі колекцій.
Крок 4: Синхронізація
До бази даних нічого не записується, доки ви не запустите команду:
wp bs pages sync
Команда знаходить усі джерела сторінок, реєструє тип записів acme_docs, створює або оновлює записи й виводить підсумковий рядок із кількістю discovered, created, updated, unchanged, removed і failed. Якщо запустити її повторно без змін, усі сторінки буде позначено як незмінені, і жодні записи не буде змінено. Додайте --format=json, якщо сценарію розгортання потрібен повний звіт.
Після синхронізації записи відображають дерево файлів. guide/install — дочірня сторінка guide, яка є дочірньою сторінкою кореня колекції. Порядок меню кожного запису відповідає значенню order на початку файла. URL колекції поєднують ідентифікатор колекції з логічним шляхом кожної сторінки:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Зберігати постійні посилання повторно не потрібно. Правила перезапису URL колекції скидаються автоматично, коли змінюється зареєстрований тип записів колекції.
Додайте синхронізацію до процесу розгортання. Запити з фронтенду й адмінпанелі ніколи не шукають сторінки, тому після копіювання нових файлів Markdown без запуску wp bs pages sync сайт і далі показуватиме попередній вміст.
Крок 5: Макет
Записи вже створено, але кожен із них відображається за звичайним шаблоном окремого запису теми без навігації. Файл layout.php поруч із pages.json обгортає виведення кожної сторінки колекції на фронтенді:
<?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') повертає колекцію як вкладені вузли, відсортовані за order, а потім за заголовком; дочірні вузли кожного вузла містяться в children. Тут є один кореневий вузол — вступна сторінка, під якою розташовано решту сторінок. Кожен вузол містить key, title, path і permalink. Якщо розгорнути дерево в цьому порядку, вийде послідовність читання, потрібна для посилань на попередню й наступну сторінки.
blockstudio_page_content() виводить тіло сторінки, яке WordPress згенерував би
через the_content. Якщо прибрати його, вміст буде приховано. Під час /docs/guide/install/ сайту на https://example.com макет виводить
ось це (скорочено):
<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>
Макет запускається лише для запитів до окремих записів на фронтенді в основному циклі. Він не змінює збережений post_content і не обгортає полотно редактора. Шлях до макета зберігається для кожного синхронізованого запису й входить до відбитка сторінки, тож відредагований макет буде використано під час наступної синхронізації.
Читання даних колекції в PHP
Допоміжні функції макета — це тонкі обгортки навколо класу Blockstudio\Pages. Використовуйте будь-який варіант у шаблонах, блоках або плагінах:
| Допоміжна функція | Метод класу | Повертає |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Плоский список сторінок колекції, відсортований за ключем сторінки |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Вкладені вузли з children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Безпосередні дочірні сторінки однієї сторінки |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Дані колекції з маніфесту |
blockstudio_current_page() |
Pages::current_page() |
Сторінка, що відображається, або null |
Pages::get_page('docs-guide-install') |
Сторінка за назвою |
Масиви сторінок містять синхронізовані post_id, permalink, name, key, title,
path, order, collection, postType і масив meta. Додаткові поля front matter потрапляють у meta, тож макет може вивести анотацію вступу:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Під час запитів до фронтенду ці функції читають уже синхронізовані записи та конфігурацію, збережену під час останньої синхронізації. Вони ніколи не читають файли Markdown, тож не виконують жодних файлових операцій. На фронтенді доступні лише опубліковані сторінки.
Необроблений Markdown для інструментів
Оскільки сторінки надходять із файлів Markdown, Blockstudio може також надавати вихідний код. Запитайте сторінку із суфіксом .md, наприклад /docs/guide/install.md, або надішліть Accept: text/markdown до звичайного URL. У відповіді немає front matter, а в заголовку canonical Link міститься посилання на сторінку HTML. Це корисно для пошукових індексаторів, помічників та інших інструментів, які читають звичайний текст. Сторінки, створені з вбудованого вмісту завантажувача, не мають вихідного файла, а отже, і відповіді .md.
Вимкніть це одним фільтром:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Поради
Нехай структура визначається шляхами. Перемістіть файл — і під час наступної синхронізації оновляться його шлях, батьківська сторінка та URL. Використовуйте front matter path лише тоді, коли URL має відрізнятися від розташування файла.
Поєднуйте page.json з Markdown, коли сторінці потрібно більше. У папці з page.json і index.md використовується JSON для властивостей сторінки, як-от postId чи templateLock, а Markdown — для вмісту. Значення front matter у index.md мають пріоритет над відповідними значеннями page.json.
Пишіть у файлах, а не в редакторі. З templateLock: "contentOnly" редактори можуть виправляти текст безпосередньо, але наступна синхронізація зміненого джерела перезаписує збережений вміст даними з файла. Вважайте Markdown місцем, де пишуть документацію. Сторінці, якою мають керувати редактори, натомість задайте "sync": false у page.json; звичайні синхронізації пропускатимуть її, а Blockstudio\Pages::force_sync() створить її один раз.
Змінювати тип запису безпечно. Якщо колекцію перевести з page на власний тип запису, уже синхронізовані записи буде перенесено на місці, якщо їхня збережена ідентичність збігається, тож ID записів збережуться.
Наступні кроки
- Довідник сторінок: кожна властивість
page.jsonіpages.json, завантажувачі, макети та звіт про узгодження. - Створення сторінок на основі файлів: блокування шаблонів, режими редагування блоків і об’єднання за ключами для сторінок, які редагують клієнти.
- Шаблони та частини редактора сайту з файлів: такий самий підхід із пріоритетом файлів для верхніх і нижніх колонтитулів та шаблонів теми.