Pāriet uz saturu

Dokumentācijas vietnes izveide

Dokumentācijai jāatrodas blakus kodam, ko tā apraksta. Autori dod priekšroku Markdown, recenzenti vēlas redzēt izmaiņas izmaiņu pieprasījumā, un dokumentācijai jābūt iekļautai tajā pašā laidiena iesniegumā. Savukārt WordPress ierakstiem jābūt datubāzē: tur atrodas meklēšana, pastāvīgās saites, versijas un redaktors.

Blockstudio lapu kolekcijas savieno abus. Mape ar Markdown failiem kļūst par īstu WordPress ierakstu kopu ar atsevišķu ierakstu tipu, URL pamatceļu un vecāku un bērnu hierarhiju. layout.php fails katru kolekcijas lapu ietver izkārtojumā ar navigāciju, kas veidota no tiem pašiem datiem. Faili paliek patiesības avots, un skaidri palaista sinhronizācijas komanda ieraksta tos datubāzē.

Šajā rokasgrāmatā soli pa solim tiks izveidota neliela dokumentācijas sadaļa tēmai ar nosaukumu acme: manifests, Markdown lapas, ielādētājs, kas ģenerē izmaiņu žurnālu, sinhronizācija un izkārtojums ar sānjoslu un saitēm uz iepriekšējo un nākamo lapu.

Ko izveidosiet

Kods
theme/
└── pages/
    └── docs/
        ├── pages.json
        ├── layout.php
        ├── loader.php
        ├── index.md
        ├── getting-started.md
        ├── data/
        │   └── releases.json
        └── guide/
            ├── index.md
            ├── install.md
            └── configure.md

Pēc sinhronizācijas kolekcijā būs pieejami šie URL:

Avots Publiskais 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/
ielādētāja ieraksts /docs/changelog/

1. darbība: kolekcijas manifests

Kolekcija ir mape pages/, kurā atrodas pages.json manifests. Izveidojiet pages/docs/pages.json:

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

collection ir kolekcijas saīsinātais nosaukums un kļūst par publisko URL pamatceļu. postType katru kolekcijas lapu piesaista atsevišķam ierakstu tipam, tāpēc dokumentācija administrācijas vidē nesajaucas ar parastajām lapām. Ja šis ierakstu tips vēl nepastāv, Blockstudio to reģistrē. Reģistrācijas noklusētās vērtības paredz publisku, hierarhisku ierakstu tipu, kas pieejams REST API un atbalsta virsrakstu, redaktoru, lapas atribūtus, sīktēlu, fragmentu un versijas; pārrakstīšanas saīsinātais nosaukums atbilst kolekcijas saīsinātajam nosaukumam. postTypeArgs tiek apvienots ar šīm noklusētajām vērtībām, tāpēc šis manifests maina tikai administrācijas etiķeti.

defaults piemēro lapas rekvizītus visām kolekcijas lapām. Šeit katra lapa sinhronizācijas laikā tiek publicēta un bloķēta tā, lai rediģēt varētu tikai saturu. Tādējādi redaktori var izlabot drukas kļūdu redaktorā, bet nevar pārkārtot struktūru, ko nosaka Markdown.

2. darbība: rakstiet lapas Markdown

Kolekcijā katrs Markdown fails ir lapa. Identitāti nosaka faila atrašanās vieta, tāpēc priekšdaļa nav obligāta. Izmantojiet to virsrakstam, kārtošanas secībai un jebkādiem papildu datiem, ko vēlaties nolasīt vēlāk.

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

Rokasgrāmatas sadaļa ir mape ar savu index.md, kas kļūst par blakus esošo lapu vecāku:

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 katram failam nosaka loģisko ceļu un lapas nosaukumu:

Fails Ceļš Lapas nosaukums
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 un guide/install/index.md veido vienādu ceļu, tāpēc vēlāk varat pāriet no atsevišķa faila uz mapi, nemainot URL.

order kārto blakuslapas un tiek ierakstīts ieraksta izvēlnes secībā. Lapas bez secības vērtības tiek kārtotas pēc lapām, kurām tā ir norādīta, un pēc tam pēc virsraksta. Priekšdaļas atslēgas, ko Blockstudio neatpazīst, piemēram, iepriekš minēto description, tiek saglabātas lapas meta masīvā.

Sinhronizācijas laikā Markdown tiek parsēts kā GitHub ar Markdown paplašinājumiem, pārveidots par HTML un pēc tam parsēts vietējos blokos. Saglabātajā ierakstā ir bloki, nevis Markdown teksts. Virsrakstiem tiek pievienots stabils enkurs, tabulas kļūst par core/table, citāti — par core/quote, bet koda bloki — par core/preformatted bloku, kurā tiek saglabāta valodas klase. Šādi izskatās saglabātais instalācijas lapas saturs (atstarpes apgrieztas):

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. darbība: ģenerējiet lapas ar ielādētāju

Dažas lapas ir labāk ģenerēt, nevis rakstīt. Labs piemērs ir izmaiņu žurnāls: laidiena dati jau ir pieejami, un manuāla to kopēšana uz Markdown var radīt neatbilstības. Kolekcijā var iekļaut loader.php, kas atgriež papildu lapu definīcijas.

Glabājiet laidiena datus kolekcijā:

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

Pēc tam no tiem izveidojiet vienu Markdown lapu:

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',
		),
	),
);

Ielādētājs darbojas skaidri pieprasītas atklāšanas un sinhronizācijas laikā, nekad parastas lapas skatīšanas laikā. Tam jābūt deterministiskam un lokālam: faila nolasīšana no tēmas ir piemērota, bet attāla API izgūšana nav, jo tad sinhronizācija būtu atkarīga no šī pakalpojuma pieejamības.

Ielādētāja lapas tiek atzīmētas kā ģenerētas. Ja kāds ieraksts pazūd no ielādētāja izvades, nākamajā sinhronizācijā tā ieraksts tiek uzskatīts par bezsaimnieka ierakstu un apstrādāts, izmantojot blockstudio/pages/orphan_action filtru, kas pēc noklusējuma to pārvieto uz atkritni.

Ielādētājs var arī atgriezt paths, lai kolekcijā pievienotu citas lokālās Markdown mapes, vajadzības gadījumā izmantojot prefiksu. Mapēm ārpus kolekcijas saknes nepieciešams filtrs blockstudio/pages/allow_external_loader_path. Pilnu struktūru skatiet sadaļā Kolekciju ielādētāji.

4. darbība: sinhronizējiet

Datubāzē nekas netiek ierakstīts, kamēr to nepieprasāt:

Apvalks
wp bs pages sync

Komanda atrod visus lapu avotus, reģistrē ierakstu tipu acme_docs, izveido vai atjaunina ierakstus un izdrukā kopsavilkuma rindu ar discovered, created, updated, unchanged, removed un failed skaitu. Palaižot komandu vēlreiz bez izmaiņām, visas lapas tiek norādītas kā nemainītas un ieraksti netiek rakstīti. Pievienojiet --format=json, ja izvietošanas skriptam vajadzīgs pilns pārskats.

Pēc sinhronizācijas ieraksti atspoguļo failu koku. guide/install ir guide bērns, kas ir kolekcijas saknes bērns, un katra ieraksta izvēlnes secība atbilst priekšdaļas vērtībai order. Kolekcijas URL apvieno kolekcijas saīsināto nosaukumu ar katras lapas loģisko ceļu:

Kods
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/

Pastāvīgās saites nav jāsaglabā no jauna. Kolekcijas pārrakstīšanas noteikumi tiek automātiski atjaunināti, kad mainās reģistrētie kolekcijas ierakstu tipi.

Iekļaujiet sinhronizāciju izvietošanas procesā. Frontend un administrācijas pieprasījumi nekad nemeklē lapas, tāpēc izvietošana, kas kopē jaunus Markdown failus, bet nepalaid wp bs pages sync, turpinās rādīt iepriekšējo saturu.

5. darbība: izkārtojums

Ieraksti tagad ir izveidoti, taču katrs no tiem tiek attēlots ar parasto vienas lapas veidni un bez navigācijas. layout.php, kas atrodas blakus pages.json, ietver visas kolekcijas lapas frontend attēlošanu:

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') atgriež kolekciju kā ligzdotus mezglus, kas sakārtoti pēc order un pēc tam virsraksta, un katra mezgla bērni atrodas children. Šeit ir viena saknes lapa — ievads — un pārējās lapas atrodas zem tās. Katrā mezglā ir key, title, path un permalink. Secīgi izkārtojot koku šajā kārtībā, iegūst lasīšanas secību, kas nepieciešama saitēm uz iepriekšējo un nākamo lapu.

blockstudio_page_content() izvada lapas pamatdaļu, ko WordPress renderētu, izmantojot the_content. Ja to izlaiž, saturs ir paslēpts. Vietnes /docs/guide/install/ laikā https://example.com izkārtojums renderē šo (saīsināto):

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>

Izkārtojums darbojas tikai atsevišķu ierakstu frontend pieprasījumiem galvenajā ciklā. Tas nemaina saglabāto post_content un neietver redaktora audeklu. Tā ceļš tiek saglabāts katrā sinhronizētajā ierakstā un ir daļa no lapas pirkstu nospieduma, tāpēc rediģēts izkārtojums tiek ņemts vērā nākamajā sinhronizācijā.

Kolekcijas datu lasīšana, izmantojot PHP

Izkārtojuma palīgfunkcijas ir plānas Blockstudio\Pages klases aptveres. Veidnēs, blokos vai spraudņos izmantojiet jebkuru no abām formām:

Palīgfunkcija Klases metode Atgriež
blockstudio_pages('docs') Pages::pages('docs') Plakanu kolekcijas lapu sarakstu, sakārtotu pēc lapas atslēgas
blockstudio_page_tree('docs') Pages::tree('docs') Ligzdotus mezglus ar children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Vienas lapas tiešos bērnelementus
blockstudio_page_collection('docs') Pages::collection('docs') Kolekcijas datus no manifesta
blockstudio_current_page() Pages::current_page() Renderējamo lapu vai null
Pages::get_page('docs-guide-install') Lapu pēc nosaukuma

Lapu masīvos ir sinhronizētie post_id, permalink, name, key, title, path, order, collection, postType un masīvs meta. Frontmatter papildu lauki nonāk meta, tāpēc izkārtojums var attēlot ievada kopsavilkumu:

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

Frontend pieprasījumos šīs funkcijas nolasa jau sinhronizētās ziņas un pēdējās sinhronizācijas laikā saglabāto konfigurāciju. Tās nekad nelasa Markdown failus, tāpēc failu sistēma netiek skarta. Frontendā ir pieejamas tikai publicētas lapas.

Neapstrādāts Markdown rīkiem

Tā kā lapas tiek veidotas no Markdown failiem, Blockstudio var nodrošināt arī sākotnējo avotu. Pieprasiet lapu ar sufiksu .md, piemēram, /docs/guide/install.md, vai nosūtiet Accept: text/markdown parastajam URL. Atbildē nav frontmatter, un tā norāda atpakaļ uz HTML lapu ar kanonisko Link galveni. Tas noder meklēšanas indeksētājiem, asistentiem un citiem rīkiem, kas lasa vienkāršu tekstu. Lapām, kas ģenerētas no inline ielādētāja satura, nav avota faila, tāpēc tām nav arī .md atbildes.

Izslēdziet to ar vienu filtru:

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

Padomi

Ļaujiet ceļiem noteikt struktūru. Pārvietojot failu, tā ceļš, vecākmezgls un URL mainās nākamajā sinhronizācijā. Izmantojiet frontmatter path tikai tad, ja URL jāatšķiras no faila atrašanās vietas.

Apvienojiet page.json ar Markdown, ja lapai vajag ko vairāk. Mapē ar page.json un index.md lapas rekvizītiem, piemēram, postId vai templateLock, izmanto JSON, bet saturam — Markdown. Frontmatter vērtības failā index.md ir svarīgākas par atbilstošajām page.json vērtībām.

Rakstiet failos, nevis redaktorā. Izmantojot templateLock: "contentOnly", redaktori var uzreiz labot tekstu, taču nākamajā izmainīta avota sinhronizācijā saglabātais saturs tiek pārrakstīts no faila. Uzskatiet Markdown par vietu, kur tiek rakstīta dokumentācija. Lapa, kas jānodod redaktoriem, tiek izveidota ar "sync": false failā page.json; parastās sinhronizācijas to izlaiž, un Blockstudio\Pages::force_sync() to izveido vienreiz.

Ziņas veida maiņa ir droša. Ja kolekciju pārveido no page par pielāgotu ziņu veidu, jau sinhronizētās ziņas tiek migrētas, ja to saglabātā identitāte atbilst, tāpēc ziņu ID paliek nemainīgi.

Nākamie soļi