Siirry sisältöön

Dokumentaatiosivuston rakentaminen

Dokumentaation on hyvä sijaita sitä kuvaavan koodin vieressä. Kirjoittajat suosivat muotoa Markdown, arvioijat haluavat nähdä muutokset vetopyynnössä ja julkaisun dokumentaation tulisi sisältyä samaan toimitukseen. WordPress puolestaan tarvitsee julkaisut tietokantaan: siellä ovat haku, kestolinkit, versiot ja editori.

Blockstudio-sivukokoelmat yhdistävät nämä kaksi. Markdown-tiedostojen kansiosta syntyy joukko oikeita WordPress-julkaisuja, joilla on oma julkaisulaji, URL-peruspolku sekä emo- ja lapsihierarkia. layout.php-tiedosto ympäröi kokoelman jokaisen sivun samoista tiedoista muodostetulla navigoinnilla. Tiedostot säilyvät totuuden lähteenä, ja erillinen synkronointikomento kirjoittaa ne tietokantaan.

Tässä oppaassa rakennetaan vaihe vaiheelta pieni dokumentaatio-osio teemalle nimeltä acme: luettelotiedosto, Markdown-sivut, muutoslokin luova lataaja, synkronointi sekä sivupalkin ja edellinen- ja seuraava-linkkien asettelu.

Mitä rakennat

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

Synkronoinnin jälkeen kokoelmassa on käytössä seuraavat URL-osoitteet:

Lähde Julkinen 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/
lataajan kohde /docs/changelog/

Vaihe 1: Kokoelman luettelotiedosto

Kokoelma on hakemistossa pages/ sijaitseva kansio, joka sisältää pages.json-luettelotiedoston. Luo tiedosto pages/docs/pages.json:

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

collection on kokoelman tunniste, josta tulee julkinen URL-peruspolku. postType ohjaa kokoelman jokaisen sivun omaan julkaisulajiin, jotta dokumentaatio ei sekoitu hallintapaneelin tavallisiin sivuihin. Jos julkaisulajia ei vielä ole, Blockstudio rekisteröi sen. Oletusarvoisesti rekisteröinti määrittää julkaisun julkiseksi ja hierarkkiseksi, saataville kohteessa REST API, ja ottaa käyttöön otsikon, editorin, sivun ominaisuudet, pienoiskuvan, otteen ja versiotuen sekä kirjoittaa uudelleenpoluksi kokoelman tunnisteen. postTypeArgs yhdistetään näihin oletusarvoihin, joten tässä luettelotiedostossa muutetaan vain hallintapaneelin nimeä.

defaults määrittää sivun ominaisuudet kokoelman jokaiselle sivulle. Tässä kaikki sivut julkaistaan synkronoinnin yhteydessä ja lukitaan vain sisältöä koskevaan muokkaustilaan, joten toimittajat voivat korjata kirjoitusvirheen editorissa mutta eivät voi järjestellä uudelleen rakennetta, jonka Markdown määrittää.

Vaihe 2: Kirjoita sivut kohteeseen Markdown

Kokoelmassa jokainen Markdown-tiedosto on sivu. Tiedoston sijainti määrittää sen tunnisteen, joten etusivun metadataa ei tarvita. Käytä sitä otsikkoon, lajittelujärjestykseen ja muihin myöhemmin tarvittaviin tietoihin.

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

Opasosio on kansio, jolla on oma index.md ja josta tulee sen vieressä olevien sivujen yläsivu:

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 johtaa kunkin tiedoston loogisen polun ja sivun nimen:

Tiedosto Polku Sivun 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 tuottavat saman polun, joten voit myöhemmin vaihtaa yksittäisen tiedoston kansioon muuttamatta kohdetta URL.

order lajittelee sisarussivut ja tallentuu julkaisun valikkojärjestykseksi. Järjestystä vailla olevat sivut sijoitetaan järjestettyjen jälkeen ja lajitellaan sitten otsikon mukaan. Etusivun metadatan avaimet, joita Blockstudio ei tunnista, kuten yllä oleva description, säilytetään sivun meta-taulukossa.

Synkronoinnin aikana Markdown jäsennetään muotoon GitHub Flavored Markdown, muunnetaan muotoon HTML ja jäsennetään sitten natiivimuotoisiksi lohkoiksi. Tallennettu julkaisu sisältää lohkot, ei Markdown-tekstiä. Otsikoille luodaan pysyvä ankkuri, taulukoista tulee core/table, lainauksista tulee core/quote ja koodiaitaus lohkosta tulee core/preformatted-lohko, jossa kieliluokka säilyy. Tältä asennussivun tallennettu sisältö näyttää (ympäriltä poistetut tyhjät merkit):

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

Vaihe 3: Luo sivuja lataajalla

Jotkin sivut kannattaa luoda kirjoittamisen sijaan. Muutosloki on hyvä esimerkki: julkaisutiedot ovat jo olemassa, ja niiden kopioiminen käsin kohteeseen Markdown aiheuttaa ristiriitoja. Kokoelmaan voi sisällyttää loader.php-tiedoston, joka palauttaa lisää sivumääritelmiä.

Säilytä julkaisutiedot kokoelmassa:

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

Luo sitten siitä yksi Markdown-sivu:

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

Lataaja suoritetaan nimenomaisen lähteiden etsinnän ja synkronoinnin aikana, ei tavallisen sivun katselun yhteydessä. Pidä se deterministisenä ja paikallisena: tiedoston lukeminen teemasta sopii, mutta etäpalvelun API-tiedon noutaminen ei, sillä silloin synkronointi riippuisi palvelun saavutettavuudesta.

Lataajan sivut merkitään luoduiksi. Jos merkintä katoaa lataajan tulosteesta, seuraavassa synkronoinnissa sen julkaisua käsitellään orpona ja se käsitellään suodattimella blockstudio/pages/orphan_action, joka siirtää sen oletusarvoisesti roskakoriin.

Lataaja voi myös palauttaa arvon paths liittääkseen muita paikallisia Markdown-kansioita kokoelmaan, halutessasi etuliitteen alle. Kokoelman juuren ulkopuoliset kansiot edellyttävät suodatinta blockstudio/pages/allow_external_loader_path. Katso täydellinen rakenne oppaasta Kokoelman lataajat.

Vaihe 4: Synkronointi

Tietokantaan ei kirjoiteta mitään ennen kuin pyydät sitä:

Shell
wp bs pages sync

Komento etsii kaikki sivulähteet, rekisteröi julkaisulajin acme_docs, luo tai päivittää julkaisut ja tulostaa yhteenvetorivin, jossa näkyvät määrät: discovered, created, updated, unchanged, removed ja failed. Jos ajat sen uudelleen ilman muutoksia, kaikki sivut ilmoitetaan muuttumattomiksi eikä julkaisuja kirjoiteta. Lisää --format=json, jos käyttöönottoskripti tarvitsee täydellisen raportin.

Synkronoinnin jälkeen julkaisut vastaavat tiedostopuuta. guide/install on kohteen guide lapsi, joka puolestaan on kokoelman juuren lapsi, ja kunkin julkaisun valikkojärjestys on etusivun metadatan order. Kokoelman URL-osoitteissa yhdistyvät kokoelman tunniste ja kunkin sivun looginen polku:

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

Kestolinkkejä ei tarvitse tallentaa uudelleen. Kokoelmien uudelleenkirjoitussäännöt päivitetään automaattisesti, kun rekisteröityjen kokoelmien julkaisulajit muuttuvat.

Ota synkronointi osaksi käyttöönottoa. Käyttöliittymän tai hallintapaneelin pyynnöt eivät koskaan etsi sivuja, joten uusien Markdown-tiedostojen kopioiminen ilman komentoa wp bs pages sync jättää edellisen sisällön käyttöön.

Vaihe 5: Asettelu

Julkaisut ovat nyt olemassa, mutta kukin niistä käyttää teeman tavallista yksittäisen julkaisun mallia eikä navigointia ole. Kohteen pages.json viereinen layout.php ympäröi kokoelman jokaisen sivun renderöinnin käyttöliittymässä:

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') palauttaa kokoelman sisäkkäisinä solmuina, jotka on lajiteltu kohteen order ja sitten otsikon mukaan; kunkin solmun lapset ovat kohteessa children. Tässä juuria on yksi, esittelysivu, jonka alla ovat muut sivut. Solmu sisältää arvot key, title, path ja permalink. Kun puu litistetään tässä järjestyksessä, saadaan lukemisjärjestys, jota edellinen- ja seuraava-linkit tarvitsevat.

blockstudio_page_content() tulostaa sivun rungon, jonka WordPress muodostaisi the_content-palvelun kautta. Jos jätät sen pois, sisältö piilotetaan. Kun sivusto https://example.com on tilassa /docs/guide/install/, asettelu muodostaa tämän (lyhennettynä):

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>

Asettelu suoritetaan vain yksittäisen julkaisun käyttöliittymäpyynnöissä pääsilmukan aikana. Se ei muuta tallennettua post_content-sisältöä eikä ympäröi editorin piirtoaluetta. Sen polku tallennetaan kuhunkin synkronoituun julkaisuun ja sisältyy sivun sormenjälkeen, joten muokattu asettelu otetaan käyttöön seuraavan synkronoinnin yhteydessä.

Kokoelman tietojen lukeminen kohteessa PHP

Asettelun apufunktiot ovat ohuita kääreitä Blockstudio\Pages-luokan ympärillä. Käytä kumpaa tahansa muotoa malleissa, lohkoissa tai lisäosissa:

Apu Luokan metodi Palauttaa
blockstudio_pages('docs') Pages::pages('docs') Kokoelman sivujen litteä luettelo sivuavaimen mukaan järjestettynä
blockstudio_page_tree('docs') Pages::tree('docs') Sisäkkäiset solmut, joissa on children
blockstudio_page_children('docs-guide', 'docs') Pages::children('docs-guide', 'docs') Yhden sivun suorat alasivut
blockstudio_page_collection('docs') Pages::collection('docs') Kokoelman tiedot manifestista
blockstudio_current_page() Pages::current_page() Renderöitävä sivu tai null
Pages::get_page('docs-guide-install') Yksi sivu nimen perusteella

Sivutaulukot sisältävät synkronoidut post_id, permalink, name, key, title, path, order, collection, postType ja meta-taulukon. Frontmatterin lisätiedot päätyvät kohtaan meta, joten asettelu voi tulostaa johdannon yhteenvedon:

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

Frontend-pyynnöissä nämä funktiot lukevat jo synkronoituja artikkeleita ja viimeisimmän synkronoinnin tallentamia määrityksiä. Ne eivät koskaan lue Markdown-tiedostoja, joten tiedostojärjestelmää ei tarvitse käsitellä. Frontendissä ovat käytettävissä vain julkaistut sivut.

Työkalujen raaka Markdown

Koska sivut tulevat Markdown-tiedostoista, Blockstudio voi tarjota myös alkuperäisen lähteen. Pyydä sivua .md-päätteellä, esimerkiksi /docs/guide/install.md, tai lähetä Accept: text/markdown tavalliseen URL-osoitteeseen. Vastauksesta puuttuu frontmatter, ja se osoittaa takaisin HTML-sivulle kanonisella Link-otsakkeella. Tämä on hyödyllistä hakemistoille, avustajille ja muille pelkkää tekstiä lukeville työkaluille. Sisäisen lataajan sisällöstä luoduilla sivuilla ei ole lähdetiedostoa, joten niille ei ole myöskään .md-vastausta.

Poista se käytöstä yhdellä suodattimella:

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

Vinkkejä

Anna polkujen määrittää rakenne. Kun siirrät tiedoston, sen polku, yläelementti ja URL siirtyvät mukana seuraavassa synkronoinnissa. Käytä frontmatterin path-määritystä vain, kun URL poikkeaa tiedoston sijainnista.

Yhdistä page.json ja Markdown, kun sivu tarvitsee lisää. Kansiossa, jossa on page.json ja index.md, käytetään JSON-määritystä sivun ominaisuuksiin, kuten postId tai templateLock, ja Markdown-määritystä sisältöön. Kohdassa index.md oleva frontmatter ohittaa vastaavat page.json-arvot.

Kirjoita tiedostoihin, älä muokkaimeen. Kun käytössä on templateLock: "contentOnly", muokkaajat voivat korjata tekstiä suoraan, mutta seuraava muuttuneen lähteen synkronointi kirjoittaa tallennetun sisällön uudelleen tiedostosta. Pidä Markdown-hakemistoa dokumentaation kirjoituspaikkana. Sivulle, jonka pitäisi kuulua muokkaajille, asetetaan sen sijaan "sync": false tiedostossa page.json; tavalliset synkronoinnit ohittavat sen, ja Blockstudio\Pages::force_sync() luo sen kerran.

Artikkelityypin vaihtaminen on turvallista. Jos kokoelma siirtyy tyypistä page mukautettuun artikkelityyppiin, jo synkronoidut artikkelit siirretään paikallaan, kun niiden tallennettu identiteetti täsmää, joten artikkelien tunnukset säilyvät.

Seuraavat vaiheet