إنشاء موقع توثيق
يفضل أن يكون التوثيق بجوار الكود الذي يشرحه. يفضّل الكتّاب Markdown، ويريد المراجعون رؤية التغييرات في طلب سحب، وينبغي أن يصدر التوثيق مع الإصدار نفسه وفي الالتزام نفسه. من ناحية أخرى، يريد WordPress المنشورات في قاعدة البيانات؛ فهناك توجد خاصيات البحث والروابط الدائمة والمراجعات والمحرر.
تصل مجموعات الصفحات في Blockstudio بين الأمرين. يتحول مجلد ملفات Markdown إلى مجموعة من منشورات WordPress حقيقية بنوع منشور خاص وقاعدة URL وتسلسل هرمي من الصفحات الأصلية والفرعية. يغلّف ملف layout.php كل صفحة في المجموعة بتخطيط تنقل مبني على البيانات نفسها. تظل الملفات مصدر الحقيقة، ويكتبها أمر مزامنة صريح إلى قاعدة البيانات.
يبني هذا الدليل خطوةً خطوةً قسم توثيق صغيرًا لقالب اسمه acme: ملف بيان وصفحات Markdown ومحمّل يُنشئ سجل التغييرات، ثم المزامنة وتخطيطًا بقائمة جانبية وروابط السابق والتالي.
ما الذي ستبنيه
theme/
└── pages/
└── docs/
├── pages.json
├── layout.php
├── loader.php
├── index.md
├── getting-started.md
├── data/
│ └── releases.json
└── guide/
├── index.md
├── install.md
└── configure.md
بعد المزامنة، ستعرض المجموعة عناوين URL التالية:
| المصدر | 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/ |
| مدخل المحمّل | /docs/changelog/ |
الخطوة 1: بيان المجموعة
المجموعة مجلد داخل pages/ يحتوي على ملف بيان pages.json. أنشئ pages/docs/pages.json:
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collection هو الاسم المختصر للمجموعة، ويصبح قاعدة URL العامة. يوجّه postType كل صفحة في المجموعة إلى نوع منشور مخصص، كي لا تختلط صفحات التوثيق بصفحاتك العادية في لوحة الإدارة. وإذا لم يكن نوع المنشور موجودًا، يسجله Blockstudio. تكون الإعدادات الافتراضية للتسجيل عامة وهرمية ومتاحة في REST API، مع دعم العنوان والمحرر وسمات الصفحة والصورة المصغرة والمقتطف والمراجعات، ويطابق الاسم المختصر لإعادة الكتابة اسم المجموعة. ويُدمج postTypeArgs مع هذه الإعدادات الافتراضية، لذا لا يغيّر هذا البيان سوى تسمية لوحة الإدارة.
يطبّق defaults خصائص الصفحة على كل صفحة في المجموعة. هنا تُنشر كل صفحة عند المزامنة وتُقفل على تحرير المحتوى فقط، ليتمكن المحررون من تصحيح خطأ مطبعي في المحرر، لكنهم لا يستطيعون تغيير البنية التي يحددها Markdown.
الخطوة 2: كتابة الصفحات في Markdown
داخل المجموعة، يمثل كل ملف 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/).
---
title: Getting Started
order: 10
---
# Getting Started
Install the theme, then activate it under **Appearance > Themes**.
```bash
wp theme activate acme
```
قسم الدليل مجلد له index.md خاص به، ويصبح المجلد الأصل للصفحات الموجودة بجواره:
---
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 مسارًا منطقيًا واسم صفحة من كل ملف:
| الملف | المسار | اسم الصفحة |
|---|---|---|
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 وguide/install/index.md المسار نفسه، لذا يمكنك لاحقًا التبديل بين ملف مسطّح ومجلد من دون تغيير URL.
يرتّب order الصفحات الشقيقة، وتُحفظ قيمته في ترتيب قائمة المنشور. تأتي الصفحات التي بلا ترتيب بعد الصفحات المرتبة، ثم تُرتّب حسب العنوان. وتُحفظ مفاتيح مقدمات الملفات التي لا يتعرف إليها Blockstudio، مثل description أعلاه، في مصفوفة meta الخاصة بالصفحة.
أثناء المزامنة، يُحلل Markdown بصيغة GitHub Flavored Markdown، ثم يُحوّل إلى HTML ويُحلل بعد ذلك إلى كتل أصلية. يحتوي المنشور المخزّن على كتل، لا على نص Markdown. تحصل العناوين على مُرسى ثابت، وتتحول الجداول إلى core/table، والاقتباسات الكتلية إلى core/quote، والأكواد المحاطة بسياج إلى كتلة core/preformatted تحتفظ بفئة اللغة. هذا هو المحتوى المخزن لصفحة التثبيت في هذا الموقع (بعد إزالة المسافات البيضاء من الأطراف):
<!-- 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: إنشاء الصفحات باستخدام محمّل
من الأفضل إنشاء بعض الصفحات تلقائيًا بدلًا من كتابتها. سجل التغييرات مثال جيد: فبيانات الإصدارات موجودة أصلًا، ونسخها يدويًا إلى Markdown يعرّضها للتباعد عن المصدر. ويمكن أن تضم المجموعة loader.php يعيد تعريفات صفحات إضافية.
احتفظ ببيانات الإصدار في المجموعة:
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
ثم أنشئ منها صفحة 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',
),
),
);
يعمل المحمّل أثناء الاكتشاف والمزامنة الصريحين، وليس عند عرض صفحة عادية. اجعله حتميًا ومحليًا: لا بأس بقراءة ملف في القالب، لكن لا تجلب API بعيدًا، لأن المزامنة ستعتمد عندئذٍ على إمكانية الوصول إلى تلك الخدمة.
تُعلَّم صفحات المحمّل على أنها مُنشأة تلقائيًا. إذا اختفى إدخال من مخرجات المحمّل، فستتعامل المزامنة التالية مع منشوره كعنصر يتيم عبر مرشح blockstudio/pages/orphan_action، الذي ينقله إلى سلة المهملات افتراضيًا.
يمكن للمحمّل أيضًا إرجاع paths لإضافة مجلدات محلية أخرى تحتوي على Markdown إلى المجموعة، اختياريًا ضمن بادئة. وتتطلب المجلدات خارج جذر المجموعة مرشح blockstudio/pages/allow_external_loader_path. راجع محمّلات المجموعات للاطلاع على البنية كاملةً.
الخطوة 4: المزامنة
لن يُكتب شيء في قاعدة البيانات قبل أن تطلب ذلك:
wp bs pages sync
يكتشف الأمر كل مصادر الصفحات، ويسجّل نوع المنشور acme_docs، وينشئ المنشورات أو يحدّثها، ثم يطبع صفًا موجزًا يتضمن أعداد discovered وcreated وupdated وunchanged وremoved وfailed. وإذا شُغّل مجددًا بلا تغييرات، فسيعرض كل صفحة على أنها لم تتغير، ولن يجري أي كتابة للمنشورات. أضف --format=json عندما يحتاج برنامج النشر النصي إلى التقرير الكامل.
بعد المزامنة، تعكس المنشورات شجرة الملفات. تكون guide/install صفحة فرعية من guide، وهذه بدورها صفحة فرعية من جذر المجموعة، ويكون ترتيب قائمة كل منشور هو قيمة order في البيانات الوصفية للمقدمة. تجمع عناوين URL للمجموعة اسمها المختصر مع المسار المنطقي لكل صفحة:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
لا تحتاج إلى حفظ الروابط الدائمة مجددًا. تُحدّث قواعد إعادة الكتابة للمجموعة تلقائيًا عند تغيير أنواع منشورات المجموعة المسجلة.
اجعل المزامنة جزءًا من عملية النشر. فلا تنفذ طلبات الواجهة الأمامية ولوحة الإدارة اكتشاف الصفحات، لذا فإن نشرًا ينسخ ملفات Markdown جديدة من دون تشغيل wp bs pages sync سيواصل عرض المحتوى السابق.
الخطوة 5: التخطيط
أصبحت المنشورات موجودة الآن، لكن كلًا منها يُعرض باستخدام القالب الفردي المعتاد للنسق ومن دون تنقل. يغلّف layout.php الموجود بجوار pages.json العرض الأمامي لكل صفحة في المجموعة:
<?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') المجموعة على هيئة عقد متداخلة، مرتبة حسب order ثم العنوان، وتحتوي كل عقدة على صفحاتها الفرعية ضمن children. هنا توجد عقدة جذر واحدة، هي صفحة المقدمة، وتتبعها الصفحات الأخرى. وتضم كل عقدة key وtitle وpath وpermalink. ويؤدي تسطيح الشجرة بهذا الترتيب إلى تسلسل القراءة، وهو كل ما تحتاج إليه روابط السابق والتالي.
يطبع blockstudio_page_content() متن الصفحة الذي سيعرضه WordPress عبر the_content. اتركه خارجًا وسيظل المحتوى مخفيًا. عند /docs/guide/install/ موقع على https://example.com، يعرض التخطيط ما يلي (بعد التشذيب):
<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>
لا يعمل التخطيط إلا مع طلبات الواجهة الأمامية للصفحات المفردة ضمن الحلقة الرئيسية. ولا يغيّر post_content المخزّن، كما لا يغلّف لوحة المحرر. يُحفظ مساره في كل منشور تمت مزامنته، ويُعد جزءًا من بصمة الصفحة، لذا يُلتقط أي تعديل على التخطيط في المزامنة التالية.
قراءة بيانات المجموعة في PHP
ما مساعدات التخطيط إلا أغلفة رقيقة حول الصنف Blockstudio\Pages. استخدم أيًا من الصيغتين في القوالب أو الكتل أو الإضافات:
| المساعد | أسلوب الصنف | القيمة المُعادة |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
قائمة مسطحة بصفحات المجموعة، مفهرسة بمفتاح الصفحة ومرتبة |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
عقد متداخلة مع children |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
الصفحات الفرعية المباشرة لصفحة واحدة |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
بيانات المجموعة من ملف البيان |
blockstudio_current_page() |
Pages::current_page() |
الصفحة المعروضة، أو null |
Pages::get_page('docs-guide-install') |
صفحة واحدة حسب الاسم |
تتضمن مصفوفات الصفحات post_id وpermalink وname وkey وtitle وpath وorder وcollection وpostType، بالإضافة إلى مصفوفة meta. وتوضع الإضافات الواردة في مقدمة الملف ضمن meta، لذا يستطيع التخطيط عرض ملخص المقدمة:
<?php $summary = $current['meta']['description'] ?? ''; ?>
تقرأ هذه الدوال في طلبات الواجهة الأمامية المنشورات التي تمت مزامنتها بالفعل والإعدادات المخزنة في آخر مزامنة. وهي لا تقرأ ملفات Markdown، لذا لا تتطلب أي عمل على نظام الملفات. لا تتاح في الواجهة الأمامية إلا الصفحات المنشورة.
Markdown الخام للأدوات
نظرًا إلى أن الصفحات مستمدة من ملفات Markdown، يمكن لـBlockstudio تقديم المصدر الأصلي أيضًا. اطلب صفحة مع اللاحقة .md، مثل /docs/guide/install.md، أو أرسل Accept: text/markdown إلى URL العادي. لا تتضمن الاستجابة البيانات الوصفية للمقدمة، وتشير إلى صفحة HTML باستخدام ترويسة Link أساسية. يفيد ذلك مفهرسات البحث والمساعدين والأدوات الأخرى التي تقرأ النص العادي. أما الصفحات المُنشأة من محتوى محمّل مضمّن، فلا تملك ملف مصدر، وبالتالي لا تتوفر لها استجابة .md.
أوقف ذلك باستخدام مرشح واحد:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
نصائح
دع المسارات تحدد البنية. عند نقل ملف، يتغير مساره وصفحته الأصل وقيمة URL في المزامنة التالية. استخدم البيانات الوصفية في مقدمة الملف ضمن path فقط عندما تريد أن يختلف URL عن موقع الملف.
اجمع بين page.json وMarkdown عندما تحتاج الصفحة إلى المزيد. يستخدم المجلد الذي يضم page.json وindex.md ملف JSON لخصائص الصفحة مثل postId أو templateLock، وملف Markdown للمحتوى. وتكون الأولوية للبيانات الوصفية في index.md على قيم page.json المطابقة.
اكتب في الملفات، لا في المحرر. باستخدام templateLock: "contentOnly"،
يمكن للمحررين تصحيح النص في مكانه، لكن المزامنة التالية لمصدر متغير
تعيد كتابة المحتوى المخزن من الملف. اعتبر Markdown المكان الذي
تُكتب فيه المستندات. أما الصفحة التي يُفترض أن يحررها المحررون، فتُنشأ
"sync": false داخل page.json؛ وعندها تتجاهلها
عمليات المزامنة العادية، وينشئها Blockstudio\Pages::force_sync() مرة واحدة.
تغيير نوع المنشور آمن. إذا انتقلت مجموعة من page إلى
نوع منشور مخصص، فستُنقل المنشورات التي تمت مزامنتها بالفعل إلى موضعها عند تطابق هويتها المخزنة، وبذلك تظل معرّفات المنشورات كما هي.
الخطوات التالية
- مرجع الصفحات: كل خاصية من
page.jsonوpages.json، والمحملات والتخطيطات وتقرير التسوية. - إنشاء صفحات قائمة على الملفات: تثبيت القوالب، وأوضاع تحرير الكتل والدمج باستخدام المفاتيح للصفحات التي يعدلها العملاء.
- قوالب أجزاء محرر الموقع من الملفات: النهج المعتمد على الملفات نفسه للرؤوس والتذييلات وقوالب السمات.