Към съдържанието

Изграждане на сайт с документация

Документацията трябва да е близо до кода, който описва. Авторите предпочитат Markdown, рецензентите искат да виждат промените в заявка за изтегляне, а документацията за дадено издание трябва да е в същия commit. От друга страна, 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:

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 е страница. Местоположението на файла задава идентичността ѝ, затова frontmatter не е задължителен. Използвайте го за заглавието, реда на сортиране и допълнителните данни, които искате да прочетете по-късно.

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

Разделът с ръководството е папка със собствен index.md, който става родител на страниците до нея:

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 извежда логически път и име на страница от всеки файл:

Файл Път Име на страницата
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 подрежда страниците в една група и се записва като ред в менюто на публикацията. Страниците без зададен ред се подреждат след тези със зададен ред, а след това по заглавие. Ключовете във frontmatter, които Blockstudio не разпознава, като description по-горе, се запазват в масива meta на страницата.

При синхронизиране Markdown се анализира като GitHub Flavored Markdown, преобразува се в HTML, след което се анализира като собствени блокове. Съхранената публикация съдържа блокове, а не текст Markdown. Заглавията получават стабилна котва, таблиците се превръщат в core/table, цитатите — в core/quote, а ограденият с разделители код — в блок core/preformatted, който запазва класа на езика. Ето съхраненото съдържание на инсталационната страница (с премахнати крайни интервали):

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

Стъпка 3: Генериране на страници със зареждащ компонент

Някои страници е по-добре да се генерират, вместо да се пишат. Регистърът на промените е добър пример: данните за изданията вече съществуват, а ръчното им копиране в Markdown може да доведе до несъответствия. Колекцията може да включва loader.php, който връща допълнителни определения на страници.

Съхранявайте данните за изданията в колекцията:

JSON
[
  { "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
<?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 от frontmatter. URL адресите на колекцията съчетават краткото име на колекцията с логическия път на всяка страница:

Код
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/

Не е необходимо да записвате постоянните връзки отново. Правилата за пренаписване на адресите на колекцията се обновяват автоматично, когато се променят регистрираните типове публикации на колекцията.

Включете синхронизирането в процеса си на внедряване. Заявките от frontend и администрацията никога не откриват страници, затова при внедряване, което копира нови файлове Markdown без да изпълни wp bs pages sync, ще продължи да се показва предишното съдържание.

Стъпка 5: Оформлението

Публикациите вече съществуват, но всяка се показва с обичайния шаблон за единична страница на темата и без навигация. layout.php до pages.json обгръща визуализацията във frontend на всяка страница от колекцията:

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') връща колекцията като вложени възли, сортирани по order и след това по заглавие, а дъщерните възли на всеки възел се намират в children. Тук има един основен възел — страницата с въведението, под която са останалите страници. Всеки възел съдържа key, title, path и permalink. Изравняването на дървото в този ред дава последователността за четене, която е необходима за връзките към предишната и следващата страница.

blockstudio_page_content() отпечатва тялото на страницата, което WordPress би генерирал чрез the_content. Ако го пропуснете, съдържанието остава скрито. При /docs/guide/install/ на сайт на адрес https://example.com оформлението генерира следния (съкратен) резултат:

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>

Оформлението се изпълнява само при заявки към отделни страници от frontend в основния цикъл. То не променя съхранения 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
<?php $summary = $current['meta']['description'] ?? ''; ?>

При заявки от фронтенда тези функции четат вече синхронизираните публикации и конфигурацията, запазена при последната синхронизация. Те никога не четат файловете Markdown, затова не извършват файлови операции. Във фронтенда са налични само публикуваните страници.

Необработен Markdown за инструменти

Тъй като страниците идват от файлове Markdown, Blockstudio може да предоставя и оригиналния източник. Заявете страница с наставка .md, например /docs/guide/install.md, или изпратете Accept: text/markdown към стандартния URL. Отговорът не включва frontmatter и сочи обратно към страницата HTML с каноничен хедър Link. Това е полезно за търсачки, асистенти и други инструменти, които четат обикновен текст. Страниците, генерирани от съдържание в inline loader, нямат изходен файл и следователно не връщат .md.

Изключете го с един филтър:

PHP
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 на публикациите се запазват.

Следващи стъпки