Dokumentacijos svetainės kūrimas
Dokumentacija turėtų būti greta kodo, kurį ji aprašo. Autoriai renkasi Markdown, peržiūrėtojai nori matyti pakeitimus sujungimo užklausoje, o dokumentacija turėtų būti pristatoma tame pačiame pakeitime kaip ir leidimas. Kita vertus, WordPress turinį saugo duomenų bazėje: čia veikia paieška, nuolatinės nuorodos, versijos ir redaktorius.
Blockstudio puslapių rinkiniai sujungia abu būdus. Iš aplanko su Markdown failais sukuriamas tikrų WordPress įrašų rinkinys su atskiru įrašų tipu, URL pagrindu ir hierarchija su tėviniais bei vaikų puslapiais. layout.php failas apgaubia kiekvieną rinkinio puslapį išdėstymu, kurio navigacija sudaroma iš tų pačių duomenų. Failai išlieka pagrindiniu informacijos šaltiniu, o aiškiai paleista sinchronizavimo komanda įrašo jų turinį į duomenų bazę.
Šiame nuosekliame vadove sukursime nedidelę temos acme dokumentacijos skiltį: aprašą, Markdown puslapius, pakeitimų žurnalą generuojantį įkėliklį, sinchronizavimą ir išdėstymą su šonine navigacija bei nuorodomis į ankstesnį ir kitą puslapį.
Ką sukursite
theme/
└── pages/
└── docs/
├── pages.json
├── layout.php
├── loader.php
├── index.md
├── getting-started.md
├── data/
│ └── releases.json
└── guide/
├── index.md
├── install.md
└── configure.md
Po sinchronizavimo rinkinį pasieksite šiais URL:
| Šaltinis | Viešasis 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/ |
| įkėliklio įrašas | /docs/changelog/ |
1 veiksmas: rinkinio aprašas
Rinkinys yra aplankas pages/ kataloge, kuriame yra pages.json aprašas.
Sukurkite pages/docs/pages.json:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection yra rinkinio trumpasis pavadinimas, kuris tampa viešu URL pagrindu. postType visus rinkinio puslapius priskiria atskiram įrašų tipui, todėl administravimo srityje dokumentacija nepainiojama su įprastais puslapiais. Jei tokio įrašų tipo dar nėra, Blockstudio jį užregistruoja. Pagal numatytuosius nustatymus jis yra viešas, hierarchinis, pasiekiamas REST API, palaiko pavadinimą, redaktorių, puslapio atributus, miniatiūrą, ištrauką ir versijas, o jo perrašymo trumpasis pavadinimas sutampa su rinkinio trumpuoju pavadinimu. postTypeArgs sujungiama su šiais numatytaisiais nustatymais, todėl šiame apraše keičiamas tik administravimo srities pavadinimas.
defaults visiems rinkinio puslapiams pritaiko puslapio ypatybes. Čia visi puslapiai sinchronizuojant paskelbiami ir užrakinami, kad būtų galima redaguoti tik turinį. Taip redaktoriai gali pataisyti rašybos klaidą redaktoriuje, bet negali pakeisti struktūros, kurią apibrėžia Markdown.
2 veiksmas: rašykite puslapius aplanke Markdown
Rinkinyje kiekvienas Markdown failas yra puslapis. Failo vieta nusako jo tapatybę, todėl pradinė metainformacija nebūtina. Naudokite ją pavadinimui, rikiavimo tvarkai ir papildomiems duomenims, kuriuos norėsite skaityti vėliau, nurodyti.
---
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
```
Vadovo skiltis yra aplankas su atskiru index.md, kuris tampa greta esančių puslapių tėviniu puslapiu:
---
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 iš kiekvieno failo išveda loginį kelią ir puslapio pavadinimą:
| Failas | Kelias | Puslapio pavadinimas |
|---|---|---|
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 ir guide/install/index.md nurodo tą patį kelią, todėl vėliau galite pakeisti paprastą failą aplanku nepakeisdami URL.
order surikiuoja gretimus puslapius, o jo reikšmė įrašoma į įrašo meniu tvarką. Puslapiai be nurodytos tvarkos rikiuojami po kitų, tada pagal pavadinimą. Pradinės metainformacijos raktai, kurių Blockstudio neatpažįsta, pavyzdžiui, aukščiau pateiktas description, išsaugomi puslapio meta masyve.
Sinchronizuojant Markdown išanalizuojamas kaip GitHub Flavored Markdown, konvertuojamas į HTML, tada išanalizuojamas į savuosius blokus. Įraše saugomi blokai, o ne Markdown tekstas. Antraštėms priskiriamos pastovios žymos, lentelės tampa core/table, citatos – core/quote, o kodas tarp aptvėrimo žymų – core/preformatted bloku, išsaugančiu kalbos klasę. Štai kaip atrodo įraše išsaugotas diegimo puslapio turinys (pašalinus pradžios ir pabaigos tarpus):
<!-- 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 veiksmas: generuokite puslapius naudodami įkėliklį
Kai kuriuos puslapius geriau generuoti, o ne rašyti. Pakeitimų žurnalas yra puikus pavyzdys: leidimo duomenys jau yra, o kopijuojant juos rankiniu būdu į Markdown galima padaryti neatitikimų. Į rinkinį galima įtraukti loader.php, kuris pateikia papildomų puslapių aprašų.
Leidimo duomenis laikykite rinkinyje:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Tada pagal juos sukurkite vieną Markdown puslapį:
<?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',
),
),
);
Įkėliklis vykdomas tik aiškiai paleidus aptikimą ir sinchronizavimą, niekada – įprastai peržiūrint puslapį. Užtikrinkite, kad jis veiktų nuspėjamai ir vietoje: skaityti temos failą galima, tačiau nuotolinio API gauti negalima, nes tokiu atveju sinchronizavimo sėkmė priklausytų nuo šios paslaugos pasiekiamumo.
Įkėliklio puslapiai pažymimi kaip sugeneruoti. Jei įrašo nebėra įkėliklio pateiktuose duomenyse, kito sinchronizavimo metu jo įrašas laikomas našlaičiu ir apdorojamas naudojant filtrą blockstudio/pages/orphan_action, kuris pagal numatytuosius nustatymus perkelia jį į šiukšlinę.
Įkėliklis taip pat gali grąžinti paths, kad į rinkinį įtrauktų kitus vietinius aplankus su Markdown, prireikus pridėdamas priešdėlį. Norint įtraukti aplankus, esančius už rinkinio šakninio katalogo ribų, reikia filtro blockstudio/pages/allow_external_loader_path. Išsamų aprašą rasite Rinkinių įkėlikliai.
4 veiksmas: sinchronizuokite
Duomenų bazė nieko negauna, kol to aiškiai nepaprašote:
wp bs pages sync
Komanda aptinka visus puslapių šaltinius, užregistruoja įrašų tipą acme_docs, sukuria arba atnaujina įrašus ir išspausdina suvestinės eilutę su discovered, created, updated, unchanged, removed ir failed skaičiais. Paleidus ją dar kartą be pakeitimų, pranešama, kad visi puslapiai nepasikeitė, ir įrašai neatnaujinami. Jei diegimo scenarijui reikia visos ataskaitos, pridėkite --format=json.
Po sinchronizavimo įrašai atitinka failų medį. guide/install yra guide vaikinis puslapis, o šis – rinkinio šakninio puslapio vaikinis puslapis; kiekvieno įrašo meniu tvarka nustatoma pagal pradinės metainformacijos order reikšmę. Rinkinio URL sudaromi iš rinkinio trumpojo pavadinimo ir kiekvieno puslapio loginio kelio:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Iš naujo išsaugoti nuolatinių nuorodų nereikia. Užregistravus arba pašalinus rinkinio įrašų tipus, perrašymo taisyklės automatiškai išvalomos.
Įtraukite sinchronizavimą į diegimo procesą. Frontend ir administravimo užklausos niekada neatlieka puslapių aptikimo, todėl įdiegus naujus Markdown failus be wp bs pages sync, svetainėje ir toliau bus rodomas ankstesnis turinys.
5 veiksmas: išdėstymas
Įrašai jau sukurti, tačiau kiekvienas jų pateikiamas naudojant įprastą temos vieno įrašo šabloną ir be navigacijos. Šalia pages.json esantis layout.php apgaubia kiekvieno rinkinio puslapio atvaizdavimą svetainės dalyje:
<?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') grąžina rinkinį kaip įdėtus mazgus, surikiuotus pagal order, tada pagal pavadinimą; kiekvieno mazgo vaikiniai elementai pateikiami children. Čia yra viena šaknis – įvadinis puslapis, o po juo išdėstyti kiti puslapiai. Kiekviename mazge yra key, title, path ir permalink. Tokia tvarka išlyginus medį gaunama skaitymo seka, kurios pakanka nuorodoms į ankstesnį ir kitą puslapį sukurti.
blockstudio_page_content() išveda puslapio turinį, kurį WordPress pateiktų per the_content. Jei jo neįtrauksite, turinys bus paslėptas. Svetainės https://example.com puslapio /docs/guide/install/ metu maketas pateikia šį (sutrumpintą) turinį:
<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>
Išdėstymas taikomas tik atskirų įrašų svetainės dalies užklausoms pagrindiniame cikle. Jis nekeičia išsaugoto post_content ir neapgaubia redaktoriaus drobės. Jo kelias išsaugomas kiekviename sinchronizuotame įraše ir įtraukiamas į puslapio kontrolinę sumą, todėl pakeistas išdėstymas pritaikomas kito sinchronizavimo metu.
Rinkinio duomenų skaitymas naudojant PHP
Išdėstymo pagalbinės funkcijos yra paprastos Blockstudio\Pages klasės apvalkalai. Šablonuose, blokuose arba įskiepiuose naudokite bet kurį būdą:
| Pagalbinė funkcija | Klasės metodas | Grąžina |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Surikiuotas plokščias rinkinio puslapių sąrašas, susietas pagal puslapio raktą |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Įdėtiniai mazgai su children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Tiesioginiai vieno puslapio vaikiniai puslapiai |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Rinkinio duomenys iš manifesto |
blockstudio_current_page() |
Pages::current_page() |
Atvaizduojamas puslapis arba null |
Pages::get_page('docs-guide-install') |
Vienas puslapis pagal pavadinimą |
Puslapių masyvuose yra sinchronizuoti post_id, permalink, name, key, title,
path, order, collection, postType ir meta masyvas. Papildomi
frontmatter duomenys patenka į meta, todėl išdėstymo šablone galima parodyti įžangos santrauką:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Frontend užklausų metu šios funkcijos skaito jau sinchronizuotus įrašus ir per paskutinį sinchronizavimą išsaugotą konfigūraciją. Jos niekada neskaito Markdown failų, todėl failų sistemos neapkrauna. Frontend pusėje pasiekiami tik paskelbti puslapiai.
Neapdorotas Markdown įrankiams
Kadangi puslapiai gaunami iš Markdown failų, Blockstudio taip pat gali pateikti
pirminį šaltinį. Paprašykite puslapio su priesaga .md, pavyzdžiui,
/docs/guide/install.md, arba siųskite Accept: text/markdown įprastam URL. Atsakyme nėra frontmatter,
o į HTML puslapį nurodoma kanonine Link antrašte. Tai naudinga paieškos
indeksavimo įrankiams, asistentams ir kitiems įrankiams, kurie skaito paprastą tekstą. Puslapiai,
sukurti iš inline įkėlimo funkcijos turinio, neturi šaltinio failo, todėl .md atsakymo nėra.
Išjunkite naudodami vieną filtrą:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Patarimai
Leiskite struktūrą nurodyti keliams. Perkelkite failą, o jo kelias, tėvinis
puslapis ir URL pasikeis per kitą sinchronizavimą. Frontmatter savybę path naudokite
tik tada, kai URL turi skirtis nuo failo vietos.
Kai puslapiui reikia daugiau, derinkite page.json su Markdown. Aplanke su
page.json ir index.md naudojamas JSON puslapio savybėms, pavyzdžiui, postId
arba templateLock, o Markdown – turiniui. index.md esantys frontmatter duomenys turi
pirmenybę prieš atitinkamas page.json reikšmes.
Rašykite į failus, ne į redaktorių. Naudojant templateLock: "contentOnly",
redaktoriai gali taisyti tekstą vietoje, tačiau kito pakeisto šaltinio sinchronizavimo metu
failo turinys vėl įrašomas į saugyklą. Laikykite Markdown vieta, kurioje rašoma dokumentacija.
Puslapis, kuris turėtų priklausyti redaktoriams, vietoj to gauna "sync": false faile page.json;
įprasti sinchronizavimai jį praleidžia, o Blockstudio\Pages::force_sync() sukuria vieną kartą.
Įrašo tipo keitimas yra saugus. Jei rinkinys perkeliamas iš page į
pasirinktinį įrašo tipą, jau sinchronizuoti įrašai perkeliami vietoje, kai sutampa jų išsaugota
identifikacija, todėl įrašų ID išlieka.
Tolesni žingsniai
- Puslapių žinynas: kiekviena
page.jsonirpages.jsonsavybė, įkėlimo funkcijos, išdėstymo šablonai ir suderinimo ataskaita. - Failais pagrįstų puslapių kūrimas: šablonų užrakinimas, blokų redagavimo režimai ir raktų pagrindu vykdomas puslapių, kuriuos redaguoja klientai, sujungimas.
- Svetainės redaktoriaus šablonai ir dalys iš failų: toks pat failais pagrįstas požiūris į antraštes, poraštes ir temų šablonus.