Создание сайта с документацией
Документация должна храниться рядом с описываемым ею кодом. Авторы предпочитают 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 в варианте 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. Дополнительные данные
из frontmatter попадают в meta, поэтому макет может вывести краткое описание введения:
<?php $summary = $current['meta']['description'] ?? ''; ?>
При запросах к фронтенду эти функции читают уже синхронизированные записи и конфигурацию, сохраненную при последней синхронизации. Они никогда не читают файлы Markdown, поэтому не обращаются к файловой системе. На фронтенде доступны только опубликованные страницы.
Необработанный Markdown для инструментов
Поскольку страницы берутся из файлов Markdown, Blockstudio может также отдавать
исходный текст. Запросите страницу с суффиксом .md, например
/docs/guide/install.md, или передайте Accept: text/markdown обычному URL. В ответе не будет frontmatter;
он будет содержать ссылку на страницу HTML в заголовке Link. Это полезно для поисковых
индексаторов, ассистентов и других инструментов, работающих с обычным текстом. У страниц,
созданных из встроенного содержимого загрузчика, нет исходного файла, поэтому ответ .md для них недоступен.
Отключите это одним фильтром:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Советы
Пусть структуру задают пути. Переместите файл — и при следующей синхронизации
обновятся его путь, родительский элемент и URL. Используйте frontmatter path, только если URL
должен отличаться от расположения файла.
Сочетайте page.json с Markdown, если странице нужно больше. Для папки с
page.json и index.md используется JSON для свойств страницы, таких как postId
или templateLock, и Markdown для содержимого. Данные frontmatter в index.md имеют приоритет
над совпадающими значениями page.json.
Редактируйте файлы, а не записи в редакторе. С templateLock: "contentOnly"
редакторы могут исправлять текст на месте, но при следующей синхронизации измененного исходника
сохраненное содержимое перезапишется данными из файла. Используйте Markdown как место,
где редактируется документация. Если страница должна принадлежать редакторам, добавьте
"sync": false в page.json; обычная синхронизация будет пропускать ее, а Blockstudio\Pages::force_sync() создаст ее один раз.
Изменять тип записи безопасно. Если коллекция переходит с page на
пользовательский тип записей, уже синхронизированные записи переносятся на месте, когда их сохраненная
идентичность совпадает; таким образом, ID записей сохраняются.
Следующие шаги
- Справочник по страницам: все свойства
page.jsonиpages.json, загрузчики, макеты и отчет о согласовании. - Создание страниц на основе файлов: блокировка шаблонов, режимы редактирования блоков и объединение по ключам для страниц, которые редактируют клиенты.
- Шаблоны и части редактора сайта из файлов: тот же подход, при котором файлы служат источником, для заголовков, подвалов и шаблонов темы.