Δημιουργία ιστότοπου τεκμηρίωσης
Η τεκμηρίωση πρέπει να βρίσκεται δίπλα στον κώδικα που περιγράφει. Οι συντάκτες προτιμούν το Markdown, οι κριτές θέλουν να βλέπουν τις αλλαγές σε ένα αίτημα συγχώνευσης και κάθε έκδοση πρέπει να περιλαμβάνει την τεκμηρίωσή της στο ίδιο commit. Το 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 είναι το slug της συλλογής και γίνεται η δημόσια βάση URL. Το postType στέλνει κάθε σελίδα της συλλογής σε έναν αποκλειστικό τύπο ανάρτησης, ώστε η τεκμηρίωση να μην αναμειγνύεται με τις κανονικές σελίδες στον πίνακα διαχείρισης. Αν ο τύπος ανάρτησης δεν υπάρχει ακόμη, το Blockstudio τον καταχωρίζει. Οι προεπιλεγμένες ρυθμίσεις της καταχώρισης είναι: δημόσιος, ιεραρχικός και διαθέσιμος στα REST API, με υποστήριξη για τίτλο, επεξεργαστή, χαρακτηριστικά σελίδας, μικρογραφία, απόσπασμα και αναθεωρήσεις, καθώς και slug επανεγγραφής ίδιο με το slug της συλλογής. Το postTypeArgs συγχωνεύεται με αυτές τις προεπιλεγμένες ρυθμίσεις, επομένως αυτό το αρχείο δήλωσης αλλάζει μόνο την ετικέτα στον πίνακα διαχείρισης.
Το defaults εφαρμόζει ιδιότητες σελίδας σε κάθε σελίδα της συλλογής. Εδώ, κάθε σελίδα δημοσιεύεται κατά τον συγχρονισμό και κλειδώνεται σε επεξεργασία μόνο του περιεχομένου, ώστε οι συντάκτες να μπορούν να διορθώσουν ένα τυπογραφικό λάθος στον επεξεργαστή, αλλά να μην αλλάζουν τη δομή που ορίζει το Markdown.
Βήμα 2: Γράψτε τις σελίδες σε Markdown
Μέσα σε μια συλλογή, κάθε αρχείο Markdown είναι μια σελίδα. Η θέση του αρχείου καθορίζει την ταυτότητα, επομένως τα frontmatter είναι προαιρετικά. Χρησιμοποιήστε τα για τον τίτλο, τη σειρά ταξινόμησης και τυχόν πρόσθετα δεδομένα που θέλετε να διαβάσετε αργότερα.
---
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 ταξινομεί τις αδελφές σελίδες και γράφεται στη σειρά μενού της ανάρτησης. Οι σελίδες χωρίς σειρά εμφανίζονται μετά τις ταξινομημένες και έπειτα ταξινομούνται κατά τίτλο. Τα κλειδιά frontmatter που δεν αναγνωρίζει το Blockstudio, όπως το description παραπάνω, διατηρούνται στον πίνακα meta της σελίδας.
Κατά τον συγχρονισμό, το Markdown αναλύεται ως GitHub Flavored Markdown, μετατρέπεται σε HTML και έπειτα αναλύεται σε εγγενή μπλοκ. Η αποθηκευμένη ανάρτηση περιέχει μπλοκ, όχι κείμενο Markdown. Οι επικεφαλίδες λαμβάνουν σταθερή αγκύρωση, οι πίνακες γίνονται core/table, τα παραθέματα γίνονται core/quote και τα μπλοκ κώδικα με delimiters γίνονται μπλοκ 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 των frontmatter. Οι διευθύνσεις URL της συλλογής συνδυάζουν το slug της συλλογής με τη λογική διαδρομή κάθε σελίδας:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
Δεν χρειάζεται να αποθηκεύσετε ξανά τους μόνιμους συνδέσμους. Οι κανόνες επανεγγραφής της συλλογής ανανεώνονται αυτόματα όταν αλλάζουν οι καταχωρισμένοι τύποι αναρτήσεων της συλλογής.
Συμπεριλάβετε τον συγχρονισμό στη διαδικασία ανάπτυξής σας. Τα αιτήματα frontend και διαχειριστή δεν εκτελούν ποτέ αναζήτηση σελίδων, επομένως μια ανάπτυξη που αντιγράφει νέα αρχεία Markdown χωρίς να εκτελέσει το wp bs pages sync εξακολουθεί να εξυπηρετεί το προηγούμενο περιεχόμενο.
Βήμα 5: Η διάταξη
Οι αναρτήσεις υπάρχουν πλέον, αλλά καθεμία αποδίδεται με το κανονικό πρότυπο μεμονωμένης ανάρτησης του θέματος, χωρίς πλοήγηση. Ένα layout.php δίπλα στο pages.json περιβάλλει την απόδοση frontend κάθε σελίδας της συλλογής:
<?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>
Η διάταξη εκτελείται μόνο σε αιτήματα μεμονωμένων σελίδων frontend στον κύριο βρόχο. Δεν αλλάζει το αποθηκευμένο 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') |
Δεδομένα συλλογής από το manifest |
blockstudio_current_page() |
Pages::current_page() |
Η σελίδα που αποδίδεται ή null |
Pages::get_page('docs-guide-install') |
Μία σελίδα με βάση το όνομα |
Οι πίνακες σελίδων περιλαμβάνουν τα συγχρονισμένα post_id, permalink, name, key, title,
path, order, collection, postType και τον πίνακα meta. Τα πρόσθετα στοιχεία του frontmatter καταλήγουν στο meta, ώστε μια διάταξη να μπορεί να εμφανίσει την περίληψη της εισαγωγής:
<?php $summary = $current['meta']['description'] ?? ''; ?>
Στα αιτήματα frontend, αυτές οι συναρτήσεις διαβάζουν ήδη συγχρονισμένες αναρτήσεις και τη διαμόρφωση που αποθηκεύτηκε κατά τον τελευταίο συγχρονισμό. Δεν διαβάζουν ποτέ τα αρχεία Markdown, επομένως δεν εκτελούν εργασίες στο σύστημα αρχείων. Στο frontend είναι διαθέσιμες μόνο δημοσιευμένες σελίδες.
Ακατέργαστο Markdown για εργαλεία
Επειδή οι σελίδες προέρχονται από αρχεία Markdown, το Blockstudio μπορεί επίσης να παρέχει την αρχική πηγή.
Ζητήστε μια σελίδα με κατάληξη .md, όπως
/docs/guide/install.md, ή στείλτε Accept: text/markdown στο κανονικό URL. Η
απόκριση παραλείπει το frontmatter και παραπέμπει πίσω στην αντίστοιχη σελίδα HTML με μια κανονική κεφαλίδα Link. Αυτό είναι χρήσιμο για ευρετηριαστές αναζήτησης, βοηθούς και άλλα εργαλεία που διαβάζουν απλό κείμενο. Οι σελίδες που δημιουργούνται από περιεχόμενο inline loader δεν έχουν αρχείο πηγής και επομένως δεν έχουν απόκριση .md.
Απενεργοποιήστε το με ένα φίλτρο:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Συμβουλές
Αφήστε τις διαδρομές να καθορίζουν τη δομή. Μετακινήστε ένα αρχείο και η διαδρομή του, ο γονέας του και το URL θα ακολουθήσουν στον επόμενο συγχρονισμό. Χρησιμοποιήστε το frontmatter path μόνο όταν το URL πρέπει να διαφέρει από τη θέση του αρχείου.
Συνδυάστε το page.json με το Markdown όταν μια σελίδα χρειάζεται περισσότερα. Ένας φάκελος με page.json και index.md χρησιμοποιεί το JSON για ιδιότητες σελίδας, όπως postId ή templateLock, και το Markdown για περιεχόμενο. Το frontmatter στο index.md υπερισχύει των αντίστοιχων τιμών page.json.
Γράφετε στα αρχεία, όχι στον επεξεργαστή. Με το templateLock: "contentOnly", οι συντάκτες μπορούν να διορθώνουν κείμενο επιτόπου, αλλά ο επόμενος συγχρονισμός μιας αλλαγμένης πηγής ξαναγράφει το αποθηκευμένο περιεχόμενο από το αρχείο. Χρησιμοποιείτε το Markdown ως το μέρος όπου γράφεται η τεκμηρίωση. Σελίδες που πρέπει να ανήκουν στους συντάκτες λαμβάνουν αντί αυτού "sync": false σε ένα page.json· έτσι παραλείπονται από τους κανονικούς συγχρονισμούς και το Blockstudio\Pages::force_sync() τις δημιουργεί μία φορά.
Η αλλαγή του τύπου ανάρτησης είναι ασφαλής. Αν μια συλλογή μεταβεί από το page σε έναν προσαρμοσμένο τύπο ανάρτησης, οι ήδη συγχρονισμένες αναρτήσεις μεταφέρονται επιτόπου όταν ταιριάζει η αποθηκευμένη ταυτότητά τους, οπότε τα αναγνωριστικά αναρτήσεων διατηρούνται.
Επόμενα βήματα
- Αναφορά σελίδων: κάθε ιδιότητα
page.jsonκαιpages.json, loaders, διατάξεις και αναφορά συμφιλίωσης. - Δημιουργία σελίδων βάσει αρχείων: κλείδωμα προτύπων, λειτουργίες επεξεργασίας μπλοκ και συγχώνευση με βάση κλειδιά για σελίδες που επεξεργάζονται οι πελάτες.
- Πρότυπα και τμήματα του Επεξεργαστή Ιστότοπου από αρχεία: η ίδια προσέγγιση με προτεραιότητα στα αρχεία για κεφαλίδες, υποσέλιδα και πρότυπα θέματος.