Membangun Situs Dokumentasi
Dokumentasi sebaiknya berada di dekat kode yang dijelaskannya. Penulis lebih suka Markdown, peninjau ingin melihat perubahan dalam pull request, dan dokumentasi sebaiknya dirilis dalam commit yang sama. WordPress, di sisi lain, memerlukan posting di basis data: di sanalah pencarian, permalink, revisi, dan editor berada.
Blockstudio koleksi halaman menghubungkan keduanya. Folder berisi file Markdown
menjadi sekumpulan posting WordPress sungguhan dengan jenis posting sendiri, basis URL, serta
hierarki induk dan anak. File layout.php membungkus setiap halaman dalam
koleksi dengan navigasi yang dibuat dari data yang sama. File tetap menjadi sumber kebenaran, dan perintah sinkronisasi eksplisit menulisnya ke basis data.
Panduan ini membangun bagian dokumentasi kecil untuk tema bernama acme, langkah
demi langkah: manifest, halaman Markdown, loader yang menghasilkan log perubahan, sinkronisasi, serta tata letak dengan bilah sisi dan tautan sebelumnya dan berikutnya.
Yang Akan Anda Bangun
theme/
└── pages/
└── docs/
├── pages.json
├── layout.php
├── loader.php
├── index.md
├── getting-started.md
├── data/
│ └── releases.json
└── guide/
├── index.md
├── install.md
└── configure.md
Setelah disinkronkan, koleksi ini menyajikan URL berikut:
| Sumber | URL Publik |
|---|---|
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/ |
| entri loader | /docs/changelog/ |
Langkah 1: Manifest Koleksi
Koleksi adalah folder di dalam pages/ yang berisi manifest pages.json.
Buat pages/docs/pages.json:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection adalah slug koleksi dan menjadi basis publik URL. postType
mengirim setiap halaman dalam koleksi ke jenis posting khusus, sehingga dokumentasi tidak bercampur
dengan halaman biasa Anda di admin. Jika jenis posting tersebut belum ada,
Blockstudio mendaftarkannya. Pengaturan pendaftaran bawaan bersifat publik, hierarkis,
tersedia di REST API, mendukung judul, editor, atribut halaman, gambar mini,
kutipan, dan revisi, serta memiliki slug rewrite yang sama dengan slug koleksi. Pengaturan postTypeArgs
digabungkan dengan nilai bawaan tersebut, sehingga manifest ini hanya
mengubah label admin.
defaults menerapkan properti halaman ke setiap halaman dalam koleksi. Di sini, setiap
halaman diterbitkan saat sinkronisasi dan dibatasi pada pengeditan konten saja, sehingga editor dapat memperbaiki
salah ketik di editor, tetapi tidak dapat mengatur ulang struktur yang ditentukan oleh Markdown.
Langkah 2: Tulis Halaman dalam Markdown
Di dalam koleksi, setiap file Markdown adalah sebuah halaman. Lokasi file menentukan identitasnya, jadi frontmatter bersifat opsional. Gunakan frontmatter untuk judul, urutan pengurutan, dan data tambahan apa pun yang ingin Anda baca nanti.
---
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
```
Bagian panduan adalah folder dengan index.md sendiri, yang menjadi induk
halaman-halaman di sebelahnya:
---
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 memperoleh jalur logis dan nama halaman dari setiap file:
| File | Jalur | Nama halaman |
|---|---|---|
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 dan guide/install/index.md menghasilkan jalur yang sama, jadi Anda
dapat beralih antara file datar dan folder nanti tanpa mengubah URL.
order mengurutkan halaman bersaudara dan ditulis ke urutan menu posting. Halaman tanpa
urutan ditempatkan setelah halaman yang memiliki urutan, lalu diurutkan berdasarkan judul. Kunci frontmatter yang tidak dikenali
oleh Blockstudio, seperti description di atas, disimpan dalam larik meta
halaman.
Saat sinkronisasi, Markdown diurai sebagai GitHub Flavored Markdown, dikonversi menjadi HTML,
lalu diurai menjadi blok native. Posting yang disimpan berisi blok, bukan teks Markdown.
Judul mendapat anchor stabil, tabel menjadi core/table, kutipan blok menjadi core/quote, dan kode berpagar menjadi blok core/preformatted
yang mempertahankan kelas bahasa. Berikut konten tersimpan dari halaman instalasi ini (spasi di awal dan akhir telah dihapus):
<!-- 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 -->
Langkah 3: Buat Halaman dengan Loader
Beberapa halaman lebih baik dihasilkan daripada ditulis. Log perubahan adalah contoh yang tepat:
data rilis sudah tersedia, dan menyalinnya ke Markdown secara manual dapat menyebabkan
perbedaan. Koleksi dapat menyertakan loader.php yang mengembalikan definisi
halaman tambahan.
Simpan data rilis dalam koleksi:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Lalu buat satu halaman Markdown darinya:
<?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',
),
),
);
Loader berjalan saat penemuan dan sinkronisasi eksplisit, bukan saat halaman biasa dilihat. Pastikan loader deterministik dan lokal: membaca file dalam tema tidak masalah, mengambil API jarak jauh tidak disarankan, karena sinkronisasi akan bergantung pada layanan tersebut agar tetap dapat diakses.
Halaman loader ditandai sebagai hasil buatan. Jika suatu entri hilang dari keluaran loader,
sinkronisasi berikutnya menganggap postingnya sebagai yatim dan menanganinya melalui filter blockstudio/pages/orphan_action,
yang secara default memindahkannya ke tempat sampah.
Loader juga dapat mengembalikan paths untuk memasang folder lokal lain yang berisi Markdown ke dalam
koleksi, dengan awalan opsional. Folder di luar akar koleksi memerlukan filter blockstudio/pages/allow_external_loader_path. Lihat
Loader Koleksi untuk struktur lengkapnya.
Langkah 4: Sinkronisasi
Tidak ada yang ditulis ke basis data sampai Anda memintanya:
wp bs pages sync
Perintah ini menemukan setiap sumber halaman, mendaftarkan jenis posting acme_docs,
membuat atau memperbarui posting, dan mencetak baris ringkasan dengan jumlah discovered,
created, updated, unchanged, removed, dan failed. Jika dijalankan
lagi tanpa perubahan, semua halaman dilaporkan tidak berubah dan tidak ada posting yang ditulis.
Sertakan --format=json jika skrip deployment memerlukan laporan lengkap.
Setelah sinkronisasi, posting mencerminkan struktur pohon file. guide/install adalah anak dari
guide, yang merupakan anak dari akar koleksi, dan urutan menu setiap posting adalah nilai order dari frontmatter.
URL koleksi menggabungkan slug koleksi dengan jalur logis setiap halaman:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Anda tidak perlu menyimpan ulang permalink. Aturan rewrite koleksi di-flush otomatis saat jenis posting koleksi yang terdaftar berubah.
Jadikan sinkronisasi bagian dari proses deployment Anda. Permintaan frontend dan admin tidak pernah menjalankan
penemuan halaman, jadi deploy yang menyalin file Markdown baru tanpa menjalankan
wp bs pages sync akan tetap menyajikan konten sebelumnya.
Langkah 5: Tata Letak
Posting kini tersedia, tetapi masing-masing dirender dengan templat tunggal biasa dari tema dan tanpa navigasi. layout.php
di samping pages.json membungkus proses render frontend setiap halaman dalam koleksi:
<?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') mengembalikan koleksi sebagai simpul bertingkat, diurutkan
berdasarkan order lalu judul, dengan anak setiap simpul di dalam children. Di sini
koleksi memiliki satu akar, yaitu halaman pengantar, dengan halaman lain di bawahnya. Setiap simpul
memuat key, title, path, dan permalink. Meratakan pohon dalam urutan tersebut menghasilkan urutan baca yang dibutuhkan semua tautan sebelumnya dan berikutnya.
blockstudio_page_content() mencetak isi halaman yang akan dirender WordPress melalui the_content. Jika tidak disertakan, konten disembunyikan. Saat /docs/guide/install/ situs di https://example.com, tata letak merender bagian berikut (dipangkas):
<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>
Tata letak hanya berjalan pada permintaan frontend tunggal di loop utama. Tata letak tidak
mengubah post_content yang tersimpan dan tidak membungkus kanvas editor.
Jalurnya disimpan pada setiap posting yang disinkronkan dan menjadi bagian dari sidik jari halaman, sehingga
tata letak yang diedit akan digunakan pada sinkronisasi berikutnya.
Membaca Data Koleksi di PHP
Helper tata letak adalah pembungkus tipis untuk kelas Blockstudio\Pages. Gunakan
salah satu bentuk di dalam templat, blok, atau plugin:
| Helper | Metode class | Mengembalikan |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Daftar datar halaman koleksi, diindeks berdasarkan kunci halaman dan diurutkan |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
Node bertingkat dengan children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Anak langsung dari satu halaman |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Data koleksi dari manifest |
blockstudio_current_page() |
Pages::current_page() |
Halaman yang sedang dirender, atau null |
Pages::get_page('docs-guide-install') |
Satu halaman berdasarkan nama |
Array halaman mencakup post_id, permalink, name, key, title,
path, order, collection, postType yang disinkronkan, serta array meta. Data tambahan frontmatter masuk ke meta, sehingga layout dapat menampilkan ringkasan pendahuluan:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Pada permintaan frontend, fungsi-fungsi ini membaca postingan yang sudah disinkronkan dan konfigurasi yang disimpan saat sinkronisasi terakhir. Fungsi-fungsi ini tidak pernah membaca file Markdown, sehingga tidak memerlukan pekerjaan sistem file. Hanya halaman yang dipublikasikan yang tersedia di frontend.
Markdown mentah untuk Tools
Karena halaman berasal dari file Markdown, Blockstudio juga dapat menyajikan sumber aslinya. Minta halaman dengan sufiks .md, seperti /docs/guide/install.md, atau kirim Accept: text/markdown ke URL biasa. Respons tidak menyertakan frontmatter dan menunjuk kembali ke halaman HTML dengan header Link kanonis. Ini berguna untuk pengindeks pencarian, asisten, dan alat lain yang membaca teks biasa. Halaman yang dibuat dari konten pemuat inline tidak memiliki file sumber, sehingga tidak memiliki respons .md.
Nonaktifkan dengan satu filter:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Tips
Biarkan jalur menentukan struktur. Pindahkan file, maka jalur, induk, dan URL akan ikut berubah pada sinkronisasi berikutnya. Gunakan frontmatter path hanya jika URL harus berbeda dari lokasi file.
Padukan page.json dengan Markdown jika halaman memerlukan lebih banyak data. Folder dengan page.json dan index.md menggunakan JSON untuk properti halaman seperti postId atau templateLock, dan Markdown untuk konten. Frontmatter di index.md lebih diutamakan daripada nilai page.json yang cocok.
Tulis di file, bukan di editor. Dengan templateLock: "contentOnly", editor dapat memperbaiki teks langsung, tetapi sinkronisasi berikutnya atas sumber yang berubah akan menulis ulang konten tersimpan dari file. Jadikan Markdown tempat penulisan dokumentasi. Halaman yang seharusnya dikelola editor perlu diberi "sync": false di dalam page.json; sinkronisasi biasa akan melewatinya, lalu Blockstudio\Pages::force_sync() membuatnya satu kali.
Mengubah jenis postingan aman. Jika koleksi berpindah dari page ke jenis postingan kustom, postingan yang sudah disinkronkan akan dimigrasikan di tempat jika identitas tersimpannya cocok, sehingga ID postingan tetap dipertahankan.
Langkah Berikutnya
- Referensi halaman: setiap properti
page.jsondanpages.json, pemuat, layout, dan laporan rekonsiliasi. - Membangun Halaman Berbasis File: penguncian templat, mode pengeditan blok, dan penggabungan berbasis kunci untuk halaman yang diedit klien.
- Templat dan Bagian Site Editor dari File: pendekatan yang mengutamakan file untuk header, footer, dan templat tema.