Preskoči na vsebino

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

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

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.

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

Razdelek z vodnikom je mapa z lastnim index.md, ki postane nadrejena stranem ob njej:

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

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

JSON
[
  { "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
<?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:

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

Koda
/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
<?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):

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>

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

PHP
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