用代码定义完整页面
模板和Markdown只需一条命令即可同步到WordPress。
从文件创建集合
定义pages.json,让Blockstudio发现其下的所有源文件。嵌套路径会变成嵌套页面,默认值应用于整个集合,还可以自动生成缺失的父级页面。
可将集合用于文档、知识库或着陆页,也可使用loader.php将外部文件夹挂载到路径前缀下。
将 layout.php 或 layout.tsx 之类的渲染器布局放在 pages.json 旁边,即可用一个外壳包裹集合中的每个页面,并使用 blockstudio_page_tree() 显示侧边栏。
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}---
title: Installation
order: 10
---
# Installation
Install Blockstudio from this Markdown page.<?php $current = blockstudio_current_page(); ?>
<main class="docs-layout">
<aside>
<?php foreach (blockstudio_page_tree('docs') as $item) : ?>
<?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
<a
href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
<?php echo $is_current ? 'aria-current="page"' : ''; ?>
>
<?php echo esc_html($item['title']); ?>
</a>
<?php endforeach; ?>
</aside>
<article>
<?php echo blockstudio_page_content(); ?>
</article>
</main>显式同步
wp bs pages sync 会应用更改;未更改的页面不会产生任何写入。
Markdown源
使用带 frontmatter 的index.md,或将page.json与Markdown内容配对使用。
原始Markdown
Markdown 文件页面可通过其 URL 加 .md 访问;对于 Accept: text/markdown,也可通过常规的 URL 访问,并附带指向 HTML 的规范链接。
集合加载器
将外部文档文件夹挂载到集合中,并置于路径前缀下。
站点集合
作用域为 site 的 pages.json 会为整个页面树应用共享默认设置并列出该页面树,同时不会更改 URL 或文章行。
导航辅助工具
blockstudio_page_tree()、blockstudio_page_children()、blockstudio_current_page() 和 blockstudio_page_content() 用于构建侧边栏、分页器和正文。
集合和文章类型
集合可以注册专用的层级文章类型。
模板锁定
使用 contentOnly、all 或 insert 锁定页面或单个区块。
编写 HTML,生成区块
<h1>、<p>和<ul>等标准元素会映射到核心区块。其他所有区块名称和嵌套层级都使用<block>。
Blockstudio会将完整的页面布局解析为真正可编辑的WordPress区块。
<div>
<h1 blockEditingMode="contentOnly">About Us</h1>
<p>We build tools for WordPress developers.</p>
<img src="/team.jpg" alt="Our team" />
</div>
<block name="core/columns">
<block name="core/column"><h2>Our Mission</h2></block>
<block name="core/column"><h2>Our Stack</h2></block>
</block>由组件渲染的页面
在 page.json 中将 render 设置为 page.tsx 之类的条目,并提供一个 data.php 加载器,你的主题或插件注册的页面渲染器就会绘制整个页面。Sync 会存储一个 blockstudio/page 区块,而简码等 WordPress 内容会保留在其插槽中。
渲染器返回的资源会像区块资源一样经过处理,并且只打印一次,因此预渲染的页面会包含这些资源。blockstudio.dev 本身由组件页面构建而成。
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}add_action(
'blockstudio/pages/renderers',
static function (): void {
Blockstudio\Page_Renderers::register(
'react',
array(
'extensions' => array( 'tsx' ),
'layouts' => array( 'layout.tsx' ),
'render' => 'my_theme_render_page',
)
);
}
);没有文章的路由
Blockstudio\Virtual_Routes::register() 为没有文章作为基础的文档提供服务,例如组件参考或目录。使用 prefix 和 match 后,一次注册即可响应一系列 URL;返回 null 后,URL 会交由 WordPress 处理。
路由会在 Blockstudio 的输出缓冲区中渲染,因此其中的区块会获得各自的资源和 Tailwind 输出。urls 中的路径会加入静态预渲染构建,而 Virtual_Routes::urls() 会返回这些路径以供生成站点地图。
add_action( 'init', function () {
Blockstudio\Virtual_Routes::register(
'components',
function ( $component, string $rest ) {
get_header();
echo my_component_page( $component );
get_footer();
},
[
'prefix' => true,
'match' => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
'title' => fn ( $component ) => my_component_title( $component ),
'urls' => fn () => my_component_paths(),
]
);
} );由你决定何时同步
只有在你提出要求时,页面文件才会更改WordPress。wp bs pages sync会应用所有已更改的源文件,保留带键的编辑器内容,并清理文件已不存在的页面。
指纹涵盖清单、加载器、布局和源文件,因此未更改的页面不会产生任何写入。部署时调用Pages::reconcile()并获取机器可读报告。
# Apply changed sources, keep keyed edits
wp bs pages sync
# Replace managed content from the files
wp bs pages sync --authoritative
# Compare every page and report as JSON
wp bs pages sync --full --format=json$report = Blockstudio\Pages::reconcile();
if (0 === $report['failed']) {
// Once the release is live and verified:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
}带键的区块会保留内容
为任意区块添加key。下次同步时,带键的区块会将模板属性与现有用户内容合并,而不带键的区块则会被替换。
在部署过程中调整结构,同时保留客户内容。
<h1 key="title">About Us</h1>
<block name="core/cover" key="hero" url="/hero.jpg">
<h2>Welcome to our company</h2>
<p>Edit this content freely.</p>
</block>
<block name="core/columns" key="team">
<block name="core/column"><h3>Our Team</h3></block>
</block>{
"name": "about",
"title": "About Us",
"slug": "about",
"templateLock": "contentOnly"
}模板锁定和编辑模式
"all"禁止更改;"contentOnly"锁定结构,但允许编辑文本;"insert"允许编辑和重新排序,但不允许添加或删除。
使用blockEditingMode覆盖任何元素,即可让已锁定的页面选择性地允许编辑,或禁用单个区块。
<h1>Welcome to Our Product</h1>
<p>The best solution for your needs.</p>
<block name="core/cover" blockEditingMode="disabled" url="/static-banner.jpg">
<p>Promotional banner</p>
</block>
<block name="core/group" blockEditingMode="default">
<h2>Customizable Section</h2>
</block>{
"name": "landing",
"title": "Landing Page",
"slug": "landing",
"templateLock": "contentOnly",
"blockEditingMode": "contentOnly"
}从文件提供站点编辑器模板
将template.json和模板添加到templates/,或将part.json添加到parts/,即可让你的区块主题获得基于文件的wp_template和wp_template_part源。
它们使用与页面相同的语法。只要不重置,站点编辑器中的自定义内容仍会优先生效;重置后,文件源就会恢复。
<block name="core/template-part" slug="header" />
<div>
<h1>Welcome</h1>
<block name="core/post-content" />
</div>
<block name="core/template-part" slug="footer" />{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}{
"slug": "header",
"title": "Header",
"area": "header"
}git 中选定的数据库内容
wp bs content pull 会将允许列表中的文章、术语、关系和已声明元数据导出为可移植文件,push 则会将其应用到另一个环境。已声明的引用、父级和术语关系会以稳定的 UID 随文件迁移。
由页面同步管理的文章可以与 includePageSyncManaged 一起使用。它们的文件带有 "bodyOwner": "page-sync",因此 Content Sync 会迁移元数据,而页面同步会保留正文。
{
"content": {
"enabled": true,
"id": "default",
"path": "content",
"postTypes": ["team_member"],
"taxonomies": ["category"],
"meta": {
"include": ["_my_*"],
"references": {
"_thumbnail_id": { "kind": "attachment" },
"_related_posts": { "kind": "post", "path": "*" }
}
},
"media": "manifest"
}
}wp bs content pull --dry-run
wp bs content pull
wp bs content status
wp bs content push --dry-run
wp bs content push --prune --yes带键区块
模板不断演进,用户内容依然保留。
编辑模式
设置页面默认值,并覆盖单个元素的设置。
区块绑定
将区块连接到文章元数据,让内容在同步后得以保留。
文章类型模板
templateFor 会将一个页面设为某种类型每篇新文章的起始区块结构。
固定文章 ID
删除页面并重新同步时,postId 会恢复使用相同的 ID,因此菜单和链接仍能正常工作。
脚手架与锁定
sync: false 与 Pages::force_sync() 一起使用时,会创建一次页面,供编辑者自行管理。Pages::lock() 和 unlock() 可阻止某个页面参与同步。
自定义解析器渲染器
构建器和渲染器筛选器可将区块标签转换为第三方区块的区块数组,也可更改核心区块的写入方式。
元素映射
将一个 HTML 元素映射到另一个区块,根据元素属性选择区块,并将段落 HTML 路由到内容字段。
自定义发现路径
筛选器可为页面、版式和站点编辑器模板添加根目录,例如来自某个插件的根目录。
逻辑发现源
预览、叠加层和生成的主题可以向 Blockstudio 提供组合后的文件清单,而不是单个主题文件夹。
稳定引用
声明的文章、术语和附件引用会在拉取时转换为可移植的 UID,在推送时解析为本地 ID。
推送前检查状态
wp bs content status 会将每个实体报告为未更改、将要更新、数据库中缺失、冲突、已锁定或孤立,并警告看起来像机密信息的元键。
经过验证且范围明确的推送
推送会在写入前验证整个计划,并跳过已锁定的实体。–dry-run 会显示计划,而 –prune –yes 只会移除此内容集中的实体。
纳入版本控制
在Git中跟踪页面文件,并将它们部署到不同环境。
PHP API
以编程方式访问树、子项、元数据、同步、锁定和 ID。
官方扩展套件
高级站点模板、AI 系统指令和私人 Discord 社区。一次购买,终身更新。
- 500+ 个网站模板
- AI 系统指令
- 终身更新
- 私有 Discord 社区