Izdelava spletnega mesta z dokumentacijo
Dokumentacija naj bo shranjena ob kodi, ki jo opisuje. Pisci imajo raje Markdown, pregledovalci želijo videti spremembe v zahtevku za združitev, izdaja pa naj vključuje dokumentacijo v isti potrditvi. WordPress pa želi objave v zbirki podatkov: tam so iskanje, stalne povezave, revizije in urejevalnik.
Zbirke strani Blockstudio povezujejo oboje. Mapa z datotekami Markdown postane nabor pravih objav WordPress z lastno vrsto objav, osnovo URL ter hierarhijo nadrejenih in podrejenih strani. Datoteka layout.php vsako stran v zbirki ovije z navigacijo, zgrajeno iz istih podatkov. Datoteke ostanejo glavni vir, izrecni ukaz za sinhronizacijo pa jih zapiše v zbirko podatkov.
Ta vodnik korak za korakom zgradi majhen razdelek z dokumentacijo za temo z imenom acme: manifest, strani Markdown, nalagalnik, ki ustvari dnevnik sprememb, sinhronizacijo ter postavitev s stransko navigacijo in povezavama na prejšnjo in naslednjo stran.
Kaj boste zgradili
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 sinhronizaciji so v zbirki na voljo ti URL-ji:
| Vir | Javni 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/ |
| vnos nalagalnika | /docs/changelog/ |
1. korak: Manifest zbirke
Zbirka je mapa znotraj pages/, ki vsebuje manifest pages.json. Ustvarite pages/docs/pages.json:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection je oznaka zbirke in postane javna osnova URL. postType vsako stran v zbirki dodeli namenski vrsti objav, zato se dokumentacija v skrbništvu ne meša z običajnimi stranmi. Če ta vrsta objav še ne obstaja, jo registrira Blockstudio. Privzete nastavitve registracije so: javna, hierarhična, na voljo v REST API, s podporo za naslov, urejevalnik, atribute strani, predogledno sličico, izvleček in revizije ter z nadomestnim polžem, enakim oznaki zbirke. postTypeArgs se združi s temi privzetimi nastavitvami, zato ta manifest spremeni samo oznako v skrbništvu.
defaults uporabi lastnosti strani za vsako stran v zbirki. Tukaj se vsaka stran ob sinhronizaciji objavi in zaklene za urejanje samo vsebine, zato lahko uredniki v urejevalniku popravijo tipkarsko napako, ne morejo pa spreminjati strukture, ki jo določa Markdown.
2. korak: Pisanje strani v Markdown
V zbirki je vsaka datoteka Markdown stran. Identiteto določa mesto datoteke, zato je uvodno besedilo neobvezno. Uporabite ga za naslov, vrstni red in dodatne podatke, ki jih želite pozneje prebrati.
---
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
```
Razdelek z vodnikom je mapa z lastnim index.md, ki postane nadrejena stranem ob njej:
---
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 iz vsake datoteke določi logično pot in ime strani:
| Datoteka | Pot | Ime strani |
|---|---|---|
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 in guide/install/index.md ustvarita isto pot, zato lahko pozneje preklopite med ravno datoteko in mapo, ne da bi spremenili URL.
order razvrsti sorodne strani in se zapiše kot vrstni red objave v meniju. Strani brez vrstnega reda so za tistimi z določenim vrstnim redom, nato se razvrstijo po naslovu. Ključi uvodnega besedila, ki jih Blockstudio ne prepozna, kot je zgornji description, se ohranijo v polju meta strani.
Med sinhronizacijo se Markdown razčleni kot GitHub Flavored Markdown, pretvori v HTML in nato razčleni v izvorne bloke. Shranjena objava vsebuje bloke, ne besedila Markdown. Naslovi dobijo stabilno sidro, tabele postanejo core/table, navedki postanejo core/quote, ograjena koda pa postane blok core/preformatted, ki ohrani razred jezika. To je shranjena vsebina namestitvene strani (presledki so odstranjeni):
<!-- 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. korak: Ustvarjanje strani z nalagalnikom
Nekatere strani je bolje ustvariti samodejno kot napisati. Dober primer je dnevnik sprememb: podatki o izdajah že obstajajo, ročno kopiranje v Markdown pa hitro povzroči razhajanja. Zbirka lahko vključuje loader.php, ki vrne dodatne opredelitve strani.
Podatke o izdajah hranite v zbirki:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Nato iz njih ustvarite eno stran 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',
),
),
);
Nalagalnik se zažene med izrecnim odkrivanjem in sinhronizacijo, nikoli med običajnim ogledom strani. Naj bo determinističen in lokalen: branje datoteke v temi je v redu, pridobivanje oddaljenega API pa ne, saj bi bila sinhronizacija odvisna od dosegljivosti te storitve.
Strani nalagalnika so označene kot ustvarjene. Če v izhodu nalagalnika manjka vnos, naslednja sinhronizacija njegovo objavo obravnava kot osirotelo in jo obdela prek filtra blockstudio/pages/orphan_action, ki jo privzeto premakne v koš.
Nalagalnik lahko vrne tudi paths za priklop drugih lokalnih map z datotekami Markdown v zbirko, po želji pod predpono. Za mape zunaj korena zbirke je potreben filter blockstudio/pages/allow_external_loader_path. Celotno obliko si oglejte v razdelku Nalagalniki zbirk.
4. korak: Sinhronizacija
V zbirko podatkov se nič ne zapiše, dokler tega ne zahtevate:
wp bs pages sync
Ukaz odkrije vse vire strani, registrira vrsto objav acme_docs, ustvari ali posodobi objave ter izpiše vrstico s povzetkom, ki vsebuje števila za discovered, created, updated, unchanged, removed in failed. Če ga znova zaženete brez sprememb, so vse strani označene kot nespremenjene, objave pa se ne zapišejo. Dodajte --format=json, če skript za uvedbo potrebuje celotno poročilo.
Po sinhronizaciji objave odražajo drevo datotek. guide/install je podrejena stran strani guide, ta pa je podrejena korenu zbirke. Vrstni red objave v meniju je enak vrednosti order v uvodnem besedilu. URL-ji zbirke združijo oznako zbirke z logično potjo posamezne strani:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Stalnih povezav vam ni treba znova shraniti. Pravila za prepis URL-jev zbirke se samodejno osvežijo, ko se spremenijo registrirane vrste objav zbirke.
Sinhronizacijo vključite v uvedbo. Zahteve za frontend in skrbništvo nikoli ne odkrijejo strani, zato bo uvedba, ki kopira nove datoteke Markdown brez zagona wp bs pages sync, še naprej prikazovala prejšnjo vsebino.
5. korak: Postavitev
Objave zdaj obstajajo, vendar se vsaka izriše z običajno predlogo za posamezno objavo v temi in brez navigacije. Datoteka layout.php ob pages.json ovije izris vsake strani zbirke na frontendu:
<?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') vrne zbirko kot ugnezdena vozlišča, razvrščena po order in nato po naslovu, pri čemer so otroci vsakega vozlišča v children. Tukaj ima zbirka en korenski element, uvodno stran, pod njo pa so druge strani. Vsako vozlišče vsebuje key, title, path in permalink. Če drevo sploščite v tem vrstnem redu, dobite zaporedje za branje, ki zadošča za povezave na prejšnjo in naslednjo stran.
blockstudio_page_content() izpiše telo strani, ki bi ga WordPress izrisal prek the_content. Če ga izpustite, je vsebina skrita. Pri /docs/guide/install/ mesta na https://example.com se v postavitvi izriše tole (skrajšano):
<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>
Postavitev se uporabi samo pri zahtevah za posamezne strani na frontendu v glavnem zanki. Ne spremeni shranjenega post_content in ne ovije platna urejevalnika. Njena pot je shranjena v vsaki sinhronizirani objavi in je del prstnega odtisa strani, zato se spremenjena postavitev uporabi ob naslednji sinhronizaciji.
Branje podatkov zbirke v PHP
Pomožne funkcije postavitve so preprosti ovoji okoli razreda Blockstudio\Pages. V predlogah, blokih ali vtičnikih lahko uporabite katero koli obliko:
| Pomožna funkcija | Metoda razreda | Vrne |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Ploski seznam strani zbirke, razvrščen po ključu strani |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Gnezdena vozlišča z children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Neposredne podrejene strani ene strani |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Podatki zbirke iz manifesta |
blockstudio_current_page() |
Pages::current_page() |
Stran, ki se izrisuje, ali null |
Pages::get_page('docs-guide-install') |
Stran po imenu |
Nizi strani vključujejo sinhronizirane post_id, permalink, name, key, title,
path, order, collection, postType in polje meta. Dodatki iz frontmatterja se
shranijo v meta, zato lahko postavitev izpiše povzetek uvoda:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Pri zahtevah iz vmesnika te funkcije berejo že sinhronizirane objave in konfiguracijo, shranjeno ob zadnji sinhronizaciji. Nikoli ne berejo datotek Markdown, zato ne obremenijo datotečnega sistema. V vmesniku so na voljo samo objavljene strani.
Surovi Markdown za orodja
Ker strani izvirajo iz datotek Markdown, lahko Blockstudio ponudi tudi
izvirno kodo. Zahtevajte stran s pripono .md, na primer
/docs/guide/install.md, ali pošljite Accept: text/markdown običajnemu URL. Odgovor izpusti frontmatter in kaže nazaj na stran HTML z glavo Link. To je uporabno za iskalne indeksatorje, pomočnike in druga orodja, ki berejo golo besedilo. Strani, ustvarjene iz vsebine vgrajenega nalagalnika, nimajo izvorne datoteke in zato ne vrnejo .md.
Izklopite ga z enim filtrom:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Nasveti
Naj strukturo določajo poti. Ko premaknete datoteko, se ob naslednji sinhronizaciji posodobijo njena pot, nadrejeni element in URL. Frontmatter path uporabite le, kadar se URL razlikuje od lokacije datoteke.
Kombinirajte page.json z Markdown, kadar stran potrebuje več. Mapa z page.json in index.md uporablja JSON za lastnosti strani, kot sta postId ali templateLock, ter Markdown za vsebino. Frontmatter v index.md ima prednost pred ujemajočimi se vrednostmi page.json.
Pišite v datoteke, ne v urejevalnik. Z templateLock: "contentOnly" lahko uredniki popravijo besedilo na mestu, vendar naslednja sinhronizacija spremenjenega vira prepiše shranjeno vsebino iz datoteke. Za mesto pisanja dokumentacije uporabljajte Markdown. Stran, ki naj pripada urednikom, namesto tega dobi "sync": false v page.json; običajne sinhronizacije jo nato preskočijo, Blockstudio\Pages::force_sync() pa jo ustvari enkrat.
Sprememba vrste objave je varna. Če zbirko spremenite iz page v vrsto objave po meri, se že sinhronizirane objave preselijo na mestu, kadar se njihova shranjena identiteta ujema, zato se ID-ji objav ohranijo.
Naslednji koraki
- Referenca strani: vsaka lastnost
page.jsoninpages.json, nalagalniki, postavitve in poročilo o usklajevanju. - Ustvarjanje strani na podlagi datotek: zaklepanje predlog, načini urejanja blokov in združevanje po ključih za strani, ki jih urejajo stranke.
- Predloge in deli urejevalnika spletnega mesta iz datotek: enak pristop, ki daje prednost datotekam, za glave, noge in predloge tem.