Dokumentatsioonisaidi loomine
Dokumentatsioon peaks asuma kirjeldatava koodi kõrval. Kirjutajad eelistavad Markdown, ülevaatajad tahavad näha muudatusi tõmbetaotluses ja väljalase peaks sisaldama dokumentatsiooni samas sissekandes. WordPress seevastu vajab postitusi andmebaasis: seal asuvad otsing, püsilingid, versioonid ja redaktor.
Blockstudio lehekogumid ühendavad need kaks poolt. Markdown failide kaustast saab päris WordPress postituste kogum, millel on oma postituse tüüp, URL baas ning vanem- ja alamelementide hierarhia. Fail layout.php lisab igale kogumi lehele paigutuse, mille navigeerimine põhineb samadel andmetel. Failid jäävad tõeallikaks ja selgesõnaline sünkroonimiskäsk kirjutab need andmebaasi.
Selles juhendis ehitatakse sammhaaval väike dokumentatsiooniosa teemale acme: manifest, Markdown lehed, muudatuste logi genereeriv laadija, sünkroonimine ning külgriba ja eelmise-järgmise linkidega paigutus.
Mida ehitate
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ärast sünkroonimist on kogumi lehed saadaval järgmistel URL-idel:
| Allikas | Avalik 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/ |
| laadija kirje | /docs/changelog/ |
1. samm: kogumi manifest
Kogum on kaust asukohas pages/, mis sisaldab manifesti pages.json. Looge pages/docs/pages.json:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection on kogumi lühinimi ja sellest saab avalik URL baas. postType suunab kõik kogumi lehed spetsiaalsesse postituse tüüpi, nii et dokumentatsioon ei segune administraatoris tavaliste lehtedega. Kui seda postituse tüüpi pole veel olemas, registreerib selle Blockstudio. Registreerimise vaikeväärtused on avalik ja hierarhiline, saadaval REST API loendis, toetab pealkirja, redaktorit, leheatribuute, pisipilti, väljavõtet ja versioone ning selle ümberkirjutuslühinimi võrdub kogumi lühinimega. Nende vaikeväärtuste peale ühendatakse postTypeArgs, nii et see manifest muudab ainult administraatoris kuvatavat silti.
defaults rakendab lehe omadused kogumi igale lehele. Siin avaldatakse kõik lehed sünkroonimisel ja nende sisu muutmine lukustatakse, nii et toimetajad saavad redaktoris kirjavea parandada, kuid ei saa muuta struktuuri, mille määrab Markdown.
2. samm: kirjutage lehed kausta Markdown
Kogumis on iga Markdown fail üks leht. Faili asukoht määrab selle identiteedi, seega pole esiosa metaandmed kohustuslikud. Kasutage neid pealkirja, sortimisjärjestuse ja lisaandmete jaoks, mida soovite hiljem lugeda.
---
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
```
Juhendiosa on oma index.md-ga kaust, millest saab selle kõrval asuvate lehtede vanem:
---
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 tuletab igast failist loogilise tee ja lehe nime:
| Fail | Tee | Lehe nimi |
|---|---|---|
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 ja guide/install/index.md annavad sama tee, nii et hiljem saate lameda faili kaustaga asendada, muutmata seejuures URL.
order järjestab sama taseme lehed ja salvestatakse postituse menüükorrana. Järjestuseta lehed paigutatakse järjestusega lehtede järele ning seejärel sorteeritakse pealkirja järgi. Esiosa metaandmete võtmed, mida Blockstudio ära ei tunne, näiteks ülaltoodud description, säilitatakse lehe meta massiivis.
Sünkroonimise käigus parsitakse Markdown kujule GitHub Flavored Markdown, teisendatakse kujule HTML ja seejärel parsitakse natiivseteks plokkideks. Salvestatud postitus sisaldab plokke, mitte Markdown teksti. Pealkirjadele lisatakse püsiv ankur, tabelitest saavad core/table, plokktsitaatidest core/quote ning piiritletud koodist core/preformatted plokk, mis säilitab keele klassi. Selline on paigalduse lehe salvestatud sisu (äärtest tühikud eemaldatud):
<!-- 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. samm: genereerige lehti laadijaga
Mõnda lehte on parem genereerida kui käsitsi kirjutada. Hea näide on muudatuste logi: väljalaskeandmed on juba olemas ja nende käsitsi kopeerimine faili Markdown tekitab lahknevusi. Kogum võib sisaldada faili loader.php, mis tagastab täiendavad lehemääratlused.
Hoidke väljalaskeandmeid kogumis:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Seejärel koostage neist üks Markdown leht:
<?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',
),
),
);
Laadija käivitub selgesõnalise avastamise ja sünkroonimise ajal, mitte tavalisel lehevaatamisel. Hoidke see deterministlik ja kohalik: teemas oleva faili lugemine sobib, kaugasukoha API toomine aga mitte, sest siis sõltuks sünkroonimine selle teenuse kättesaadavusest.
Laadija lehed märgitakse genereerituks. Kui mõni kirje laadija väljundist kaob, käsitleb järgmine sünkroonimine selle postitust orvuna ja töötleb seda filtri blockstudio/pages/orphan_action kaudu, mis teisaldab selle vaikimisi prügikasti.
Laadija võib tagastada ka väärtuse paths, et ühendada kogumiga teisi kohalikke kaustu, kus asuvad Markdown, soovi korral eesliite alla. Väljaspool kogumi juurkausta asuvate kaustade jaoks on vaja filtrit blockstudio/pages/allow_external_loader_path. Täielikku ülesehitust vaadake jaotisest Kogumi laadijad.
4. samm: sünkroonimine
Andmebaasi ei kirjutata midagi enne, kui selleks käsu annate:
wp bs pages sync
Käsk tuvastab iga leheallika, registreerib postituse tüübi acme_docs, loob või uuendab postitused ning väljastab kokkuvõtterea arvudega discovered, created, updated, unchanged, removed ja failed. Kui käivitate selle muudatusteta uuesti, märgitakse kõik lehed muutumatuks ja postitusi ei kirjutata. Lisage --format=json, kui juurutusskript vajab täielikku aruannet.
Pärast sünkroonimist vastavad postitused failipuule. guide/install on elemendi guide alam, mis on kogumi juure alamelement, ning iga postituse menüüjärjestus pärineb esiosa metaandmete väärtusest order. Kogumi URL-id ühendavad kogumi lühinime iga lehe loogilise teega:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Püsilinke pole vaja uuesti salvestada. Kogumi ümberkirjutusreeglid värskendatakse automaatselt, kui registreeritud kogumi postituse tüübid muutuvad.
Lisage sünkroonimine juurutusprotsessi. Frontendi ja administraatori päringud ei käivita lehtede avastamist, seega jätkab juurutus, mis kopeerib uued Markdown failid ilma käsuta wp bs pages sync, eelmise sisu näitamist.
5. samm: paigutus
Postitused on nüüd olemas, kuid igaüks neist kuvatakse teema tavalise üksikpostituse malliga ja ilma navigeerimiseta. Fail layout.php faili pages.json kõrval määrab kogu kogumi lehtede frontend-kuvamise:
<?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') tagastab kogumi pesastatud sõlmedena, mis on järjestatud order ja seejärel pealkirja järgi; iga sõlme alamüksused asuvad children sees. Siin on üks juur, sissejuhatuse leht, millest ülejäänud lehed hargnevad. Iga sõlm sisaldab väärtusi key, title, path ja permalink. Puu tasandamine selles järjekorras annab lugemisjärjestuse, mida eelmise ja järgmise lingid vajavad.
blockstudio_page_content() prindib lehe sisuosa, mille WordPress renderdaks
the_content kaudu. Jätke see välja ja sisu peidetakse. Saidi aadressil https://example.com asuva lehe /docs/guide/install/ renderdab paigutus järgmiselt (lühendatult):
<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>
Paigutus töötab ainult üksikute kirjete frontendi päringute korral põhipäringutsüklis. See ei muuda salvestatud väärtust post_content ega ümbritse redaktori tööala. Selle tee salvestatakse igasse sünkroonitud postitusse ja see kuulub lehe sõrmejälje hulka, nii et muudetud paigutus rakendub järgmisel sünkroonimisel.
Kogumiandmete lugemine PHP-is
Paigutuse abifunktsioonid on klassi Blockstudio\Pages õhukesed ümbrised. Kasutage mallides, plokkides või pluginates kumbagi kuju:
| Abifunktsioon | Klassi meetod | Tagastab |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Kogu lehekülgede sorteeritud tasane loend, võtmetena lehekülgede võtmed |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Pesastatud sõlmed koos children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Ühe lehekülje otsesed alamlehed |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Kogu andmed manifestist |
blockstudio_current_page() |
Pages::current_page() |
Renderdatav lehekülg või null |
Pages::get_page('docs-guide-install') |
Lehekülg nime järgi |
Lehekülgede massiivid sisaldavad sünkroonitud välju post_id, permalink, name, key, title,
path, order, collection, postType ja massiivi meta. Esiosa lisaväljad
salvestatakse asukohta meta, nii et paigutus saab kuvada sissejuhatuse kokkuvõtte:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Esiosa päringute korral loevad need funktsioonid juba sünkroonitud postitusi ja viimase sünkroonimise käigus salvestatud konfiguratsiooni. Need ei loe kunagi Markdown faile, seega ei koorma failisüsteemi. Esiosas on saadaval ainult avaldatud leheküljed.
Tööriistade lähte-Markdown
Kuna leheküljed pärinevad Markdown failidest, saab Blockstudio edastada ka algse lähtefaili. Pärige lehekülge lõpuga .md, näiteks /docs/guide/install.md, või saatke Accept: text/markdown tavalisele URL-ile. Vastus jätab esiosa metaandmed välja ja viitab kanoonilise Link päisega tagasi leheküljele HTML. See on kasulik otsinguindekseerijatele, assistentidele ja muudele tööriistadele, mis loevad lihtteksti. Reasisese laaduri sisust loodud lehekülgedel lähtefail puudub ja seetõttu ei saa neile .md-i vastust.
Lülita see ühe filtriga välja:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Nõuanded
Lase struktuuril kajastuda teekondades. Faili teisaldamisel muutuvad järgmisel sünkroonimisel ka selle tee, vanem ja URL. Kasuta esiosa metaandmete path-i ainult siis, kui URL peaks failiasukohast erinema.
Kasuta page.json-i koos Markdown-ga, kui lehekülg vajab enamat. Kaustas, kus on page.json ja index.md, kasutatakse lehekülje omaduste jaoks, näiteks postId või templateLock, elementi JSON ning sisu jaoks elementi Markdown. index.md esiosa metaandmed on vastavate page.json väärtuste suhtes ülimuslikud.
Kirjuta failidesse, mitte redaktorisse. templateLock: "contentOnly" korral saavad toimetajad küll teksti otse parandada, kuid muudetud lähtefaili järgmine sünkroonimine kirjutab salvestatud sisu failist uuesti üle. Käsitle dokumentide kirjutamise kohana elementi Markdown. Toimetajatele mõeldud leheküljele lisa selle asemel "sync": false elemendis page.json; tavaline sünkroonimine jätab selle siis vahele ja Blockstudio\Pages::force_sync() loob selle ühe korra.
Postituse tüübi muutmine on ohutu. Kui kogu viiakse tüübilt page üle kohandatud postituse tüübile, viiakse juba sünkroonitud postitused üle olemasoleval kujul, kui nende salvestatud identiteet kattub; postituste ID-d säilivad.
Järgmised sammud
- Lehekülgede viide: iga
page.jsonjapages.jsonomadus, laadurid, paigutused ja kooskõlastusraport. - Failipõhiste lehekülgede loomine: mallide lukustamine, plokkide redigeerimisrežiimid ja võtmete alusel ühendamine lehekülgede jaoks, mida kliendid muudavad.
- Saidi redaktori mallid ja osad failidest: sama failikeskne lähenemine päiste, jaluste ja teemamallide jaoks.