Bir Dokümantasyon Sitesi Oluşturma
Dokümantasyon, anlattığı kodun yanında bulunmalıdır. Yazarlar Markdown kullanmayı, inceleyenler değişiklikleri bir çekme isteğinde görmeyi, sürüm süreci ise dokümantasyonun aynı commit içinde yayımlanmasını ister. WordPress ise öte yandan yazıların veritabanında olmasını ister: arama, kalıcı bağlantılar, revizyonlar ve düzenleyici orada bulunur.
Blockstudio sayfa koleksiyonları bu ikisini birbirine bağlar. Bir klasördeki Markdown dosyaları; kendine ait yazı türü, URL tabanı ve üst-alt sayfa hiyerarşisi olan gerçek WordPress yazılarına dönüşür. Bir layout.php dosyası, aynı verilerden oluşturulan gezinme öğeleriyle koleksiyondaki her sayfayı sarmalar. Dosyalar tek doğruluk kaynağı olarak kalır; açık bir eşitleme komutu bunları veritabanına yazar.
Bu kılavuz, adım adım acme adlı bir tema için küçük bir dokümantasyon bölümü oluşturur: bildirim dosyası, Markdown sayfaları, değişiklik günlüğü oluşturan bir yükleyici, eşitleme ve kenar çubuğu ile önceki-sonraki bağlantılarını içeren bir düzen.
Oluşturacaklarınız
theme/
└── pages/
└── docs/
├── pages.json
├── layout.php
├── loader.php
├── index.md
├── getting-started.md
├── data/
│ └── releases.json
└── guide/
├── index.md
├── install.md
└── configure.md
Eşitleme sonrasında koleksiyonda şu URL’ler sunulur:
| Kaynak | Herkese açık 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/ |
| yükleyici girdisi | /docs/changelog/ |
1. Adım: Koleksiyon Bildirimi
Koleksiyon, pages/ içinde bir pages.json bildirimi içeren klasördür.
pages/docs/pages.json oluşturun:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection koleksiyon kısa adıdır ve herkese açık URL tabanı olur. postType, koleksiyondaki her sayfayı özel bir yazı türüne gönderir; böylece dokümantasyon yönetici panelindeki normal sayfalarınızla karışmaz. Bu yazı türü henüz yoksa Blockstudio onu kaydeder. Kayıt varsayılanları; herkese açık, hiyerarşik ve REST API içinde kullanılabilir olacak şekilde ayarlanmıştır; başlık, düzenleyici, sayfa öznitelikleri, küçük resim, özet ve revizyon desteği içerir. Yeniden yazım kısa adı koleksiyon kısa adıyla aynıdır. postTypeArgs bu varsayılanlarla birleştirilir; dolayısıyla bu bildirim yalnızca yönetici etiketi değiştirir.
defaults, koleksiyondaki her sayfaya sayfa özellikleri uygular. Burada eşitleme sırasında her sayfa yayımlanır ve yalnızca içerik düzenlemeye kilitlenir; böylece editörler düzenleyicide bir yazım hatasını düzeltebilir, ancak Markdown tarafından tanımlanan yapıyı yeniden düzenleyemez.
2. Adım: Sayfaları Markdown içinde yazma
Bir koleksiyondaki her Markdown dosyası bir sayfadır. Dosyanın konumu kimliği belirlediğinden önbilgi isteğe bağlıdır. Başlık, sıralama düzeni ve daha sonra okumak istediğiniz ek veriler için kullanın.
---
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
```
Kılavuz bölümü, kendine ait bir index.md bulunan ve yanındaki sayfaların üst öğesi olan bir klasördür:
---
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 her dosyadan mantıksal bir yol ve sayfa adı türetir:
| Dosya | Yol | Sayfa adı |
|---|---|---|
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 ve guide/install/index.md aynı yolu oluşturur; bu nedenle daha sonra URL değiştirmeden düz dosya ile klasör arasında geçiş yapabilirsiniz.
order kardeş sayfaları sıralar ve yazının menü sırasına yazılır. Sırası olmayan sayfalar sıralı sayfalardan sonra, başlığa göre sıralanır. Yukarıdaki description gibi, Blockstudio tarafından tanınmayan önbilgi anahtarları sayfanın meta dizisinde tutulur.
Eşitleme sırasında Markdown, GitHub Flavored Markdown olarak ayrıştırılır, HTML biçimine dönüştürülür
ve ardından yerel bloklara ayrıştırılır. Depolanan yazıda Markdown metni değil bloklar bulunur. Başlıklara sabit bir bağlantı noktası atanır, tablolar core/table olur, alıntı blokları core/quote olur ve kod çitleri dil sınıfını koruyan bir core/preformatted bloğuna dönüşür. Kurulumun sayfa içeriği (boşlukları temizlenmiş hali) şöyledir:
<!-- 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. Adım: Yükleyiciyle Sayfalar Oluşturma
Bazı sayfaları yazmak yerine oluşturmak daha uygundur. Değişiklik günlüğü buna iyi bir örnektir: sürüm verileri zaten vardır ve bunları elle Markdown içine kopyalamak zamanla tutarsızlıklara yol açabilir. Bir koleksiyona ek sayfa tanımları döndüren bir loader.php eklenebilir.
Sürüm verilerini koleksiyonda tutun:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
Ardından bu verilerden bir Markdown sayfası oluşturun:
<?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',
),
),
);
Yükleyici, açık keşif ve eşitleme sırasında çalışır; normal bir sayfa görüntülemesinde çalışmaz. İşlemi belirleyici ve yerel tutun: temadaki bir dosyayı okumak uygundur; uzak bir API öğesini getirmek uygun değildir, çünkü bu durumda eşitleme o hizmete erişilebilmesine bağlı olur.
Yükleyici sayfaları oluşturulmuş olarak işaretlenir. Yükleyici çıktısında bir girdi kaybolursa sonraki eşitleme, ilgili yazıyı sahipsiz kabul eder ve varsayılan olarak çöp kutusuna taşıyan blockstudio/pages/orphan_action filtresi aracılığıyla işler.
Bir yükleyici ayrıca paths döndürerek, isteğe bağlı bir önek altında koleksiyona başka yerel Markdown klasörleri bağlayabilir. Koleksiyon kökünün dışındaki klasörler için blockstudio/pages/allow_external_loader_path filtresi gerekir. Ayrıntılı biçim için Koleksiyon Yükleyicileri sayfasına bakın.
4. Adım: Eşitleme
Siz istemedikçe veritabanına hiçbir şey yazılmaz:
wp bs pages sync
Komut tüm sayfa kaynaklarını bulur, acme_docs yazı türünü kaydeder, yazıları oluşturur veya günceller ve discovered, created, updated, unchanged, removed ve failed sayılarını içeren bir özet satırı yazdırır. Değişiklik olmadan yeniden çalıştırıldığında her sayfanın değişmediğini bildirir ve hiçbir yazıya yazmaz. Dağıtım betiğinin tam rapora ihtiyacı varsa --format=json ekleyin.
Eşitleme sonrasında yazılar dosya ağacını yansıtır. guide/install, koleksiyon kökünün alt öğesi olan guide öğesinin alt öğesidir ve her yazının menü sırası önbilgideki order değeridir. Koleksiyon URL’leri, koleksiyon kısa adıyla her sayfanın mantıksal yolunun birleştirilmesiyle oluşturulur:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Kalıcı bağlantıları yeniden kaydetmeniz gerekmez. Kayıtlı koleksiyon yazı türleri değiştiğinde koleksiyonun yeniden yazım kuralları otomatik olarak yenilenir.
Eşitlemeyi dağıtım sürecinize ekleyin. Ön yüz ve yönetici paneli istekleri sayfa keşfini çalıştırmaz; bu nedenle yeni Markdown dosyalarını wp bs pages sync çalıştırmadan kopyalayan bir dağıtım önceki içeriği sunmaya devam eder.
5. Adım: Düzen
Yazılar artık mevcut, ancak her biri temanın normal tekil şablonuyla ve gezinme olmadan görüntüleniyor. pages.json yanındaki bir layout.php, koleksiyondaki her sayfanın ön yüz görüntülemesini sarar:
<?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'), koleksiyonu order ve ardından başlığa göre sıralanmış iç içe düğümler halinde döndürür; her düğümün alt öğeleri children içinde bulunur. Burada tek bir kök vardır: diğer sayfaların altında yer aldığı giriş sayfası. Her düğüm key, title, path ve permalink içerir. Ağacı bu sırayla düzleştirmek, önceki ve sonraki bağlantılar için gereken okuma sırasını verir.
blockstudio_page_content(), WordPress’in the_content üzerinden oluşturacağı sayfa gövdesini yazdırır. Bunu çıkarırsanız içerik gizlenir. https://example.com adresindeki bir sitenin /docs/guide/install/ sırasında düzen şu kısaltılmış biçimde oluşturulur:
<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>
Düzen yalnızca ana döngüdeki tekil ön yüz isteklerinde çalışır. Depolanan post_content değerini değiştirmez ve düzenleyici tuvalini de sarmalamaz. Düzenin yolu eşitlenen her yazıda saklanır ve sayfa parmak izinin bir parçasıdır; bu nedenle düzenleme sonraki eşitlemede alınır.
PHP İçinde Koleksiyon Verilerini Okuma
Düzen yardımcıları, Blockstudio\Pages sınıfını saran ince katmanlardır. Şablonlarda, bloklarda veya eklentilerde iki biçimden birini kullanın:
| Yardımcı | Sınıf yöntemi | Döndürdüğü |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
Koleksiyonun sayfalarının, sayfa anahtarına göre sıralanmış düz listesi |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
children içeren iç içe düğümler |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
Bir sayfanın doğrudan alt öğeleri |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
Manifest’teki koleksiyon verileri |
blockstudio_current_page() |
Pages::current_page() |
İşlenen sayfa veya null |
Pages::get_page('docs-guide-install') |
Ada göre tek bir sayfa |
Sayfa dizileri, eşitlenmiş post_id, permalink, name, key, title,
path, order, collection, postType ve meta dizisini içerir. Frontmatter
ekleri meta içine eklenir; böylece bir şablon, girişin özetini yazdırabilir:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Ön yüz isteklerinde bu işlevler, önceden eşitlenmiş gönderileri ve son eşitlemede kaydedilen yapılandırmayı okur. Markdown dosyalarını hiçbir zaman okumazlar; bu nedenle dosya sistemi işlemi gerektirmezler. Ön yüzde yalnızca yayımlanmış sayfalara erişilebilir.
Araçlar için Ham Markdown
Sayfalar Markdown dosyalarından geldiği için Blockstudio özgün kaynağı da sunabilir. Bir sayfayı .md uzantısıyla isteyin; örneğin /docs/guide/install.md ya da Accept: text/markdown değerini normal URL isteğine ekleyin. Yanıtta frontmatter bulunmaz ve sayfanın HTML sayfasına işaret eden standart bir Link başlığı yer alır. Bu, arama dizinleyicileri, asistanlar ve düz metin okuyan diğer araçlar için kullanışlıdır. Satır içi yükleyici içeriğinden oluşturulan sayfaların kaynak dosyası olmadığından .md yanıtı da bulunmaz.
Tek bir filtreyle kapatın:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
İpuçları
Yapıyı yollarla ifade edin. Bir dosyayı taşıdığınızda yolu, üst öğesi ve URL bir sonraki eşitlemede güncellenir. Yalnızca URL dosya konumundan farklı olması gerektiğinde frontmatter’da path kullanın.
Bir sayfa daha fazlasına ihtiyaç duyduğunda page.json ile Markdown’ı birlikte kullanın. page.json ve index.md içeren bir klasörde, postId veya templateLock gibi sayfa özellikleri için JSON, içerik içinse Markdown kullanılır. index.md içindeki frontmatter, eşleşen page.json değerlerine üstün gelir.
Düzenleyicide değil, dosyalarda yazın. templateLock: "contentOnly" kullanıldığında düzenleyiciler metni yerinde düzeltebilir; ancak değiştirilen bir kaynağın sonraki eşitlemesi, kayıtlı içeriği dosyadaki içerikle yeniden yazar. Dokümanların yazıldığı yer olarak Markdown kabul edin. Düzenleyicilere ait olması gereken bir sayfaya bunun yerine "sync": false, bir page.json içinde verin; normal eşitlemeler bu sayfayı atlar, Blockstudio\Pages::force_sync() ise sayfayı bir kez oluşturur.
Gönderi türünü değiştirmek güvenlidir. Bir koleksiyon page türünden özel bir gönderi türüne geçtiğinde, kayıtlı kimliği eşleşen önceden eşitlenmiş gönderiler yerinde taşınır; böylece gönderi kimlikleri korunur.
Sonraki Adımlar
- Sayfalar başvurusu: her
page.jsonvepages.jsonözelliği, yükleyiciler, düzenler ve uzlaştırma raporu. - Dosya Tabanlı Sayfalar Oluşturma: şablon kilitleme, blok düzenleme modları ve müşterilerin düzenlediği sayfalar için anahtarlı birleştirme.
- Site Düzenleyicisi Şablonları ve Dosyalardaki Parçalar: üstbilgiler, altbilgiler ve tema şablonları için aynı dosya öncelikli yaklaşım.