cloudcannon-bookshop

CloudCannon Bookshop

Bookshop 是 CloudCannon 早期的组件系统：包括组件库、用于生成编辑器结构的构建步骤，以及在可视化编辑器中重新渲染组件的实时编辑引擎。可编辑区域 已取代它。本技能介绍如何读取 Bookshop 站点、维持站点运行，以及迁移并移除 Bookshop。

适用场景

• 站点有 § 检测 Bookshop 中的任一信号
• 在 Bookshop 站点上添加或修改组件
• 将 Bookshop 站点迁移到可编辑区域
• Bookshop 实时编辑、结构或构建出现问题

不适用场景

• 站点没有 Bookshop 信号——请使用 cloudcannon-visual-editing。不得向没有 Bookshop 的站点添加 Bookshop；新组件编辑一律使用可编辑区域。
• Bookshop 已移除，只剩下区域——请使用 cloudcannon-visual-editing，包括其中的故障排除内容。
• 与组件无关的配置——请使用 cloudcannon-configuration。

检测 Bookshop

满足任一信号，即表示站点使用了 Bookshop。

信号	位置
bookshop/bookshop.config.{js,cjs}	src/（Astro）或 component-library/（Hugo、Eleventy、Jekyll、Next.js）
每个组件旁的 *.bookshop.{yml,yaml,toml,json,js,cjs}	component-library/components/ 或 src/components/
@bookshop/* 包	package.json 中的 dependencies 或 devDependencies
npx @bookshop/generate	.cloudcannon/postbuild
_bookshop_name 键	Front matter 中，通常位于 content_blocks 下；有时也在组件代码中
SSG 的 Bookshop 插件、模块或集成，以及其模板调用	站点配置和布局——请参阅该 SSG 的 bookshop.md

SSG 支持

只有在可编辑区域能够重新渲染 SSG 的组件时，才进行迁移。否则，网站应继续使用 Bookshop。

SSG	Bookshop 引擎	路径	文档
Astro	@bookshop/astro-engine	迁移 — migrating-to-editable-regions.md	astro/overview.md
Hugo	@bookshop/hugo-engine	迁移 — migrating-to-editable-regions.md	hugo/overview.md
Eleventy	@bookshop/eleventy-engine	迁移 — migrating-to-editable-regions.md	eleventy/overview.md
Next.js	无 — @bookshop/generate 只会写入结构	迁移 — migrating-to-editable-regions.md	nextjs/overview.md
Jekyll	@bookshop/jekyll-engine	继续使用 Bookshop — maintaining.md。可编辑区域目前尚不支持 Jekyll 组件	—

维护还是迁移？

用户想要……	执行操作
只添加或更改组件，不做其他更改	maintaining.md — 未经询问，不要开始迁移
停用 Bookshop，改用标记为“迁移”的 SSG	migrating-to-editable-regions.md
停用 Bookshop，改用标记为“继续使用”的 SSG	说明目前尚不可行；提供 maintaining.md
网站迁移到 CloudCannon（migrate-to-cloudcannon）	在该迁移流程的各阶段中完成迁移 — 迁移文件列出了各步骤
不明确	询问。迁移会重写每个组件和页面布局

目录

文件	涵盖内容
SKILL.md（本文档）	检测、SSG 支持、路由
bookshop.md	Bookshop 的工作方式 — 库布局、*.bookshop.yml、@bookshop/generate、实时编辑、绑定
maintaining.md	修改继续使用 Bookshop 的站点
migrating-to-editable-regions.md	步骤顺序、*.bookshop.yml 中的结构、_bookshop_name 重命名、移除 Bookshop
troubleshooting.md	症状 → 原因 → 修复，适用于 Bookshop 站点及迁移进行到一半的情况

按 SSG 分类：

从 SSG 的 overview.md 开始阅读；其中会说明该 SSG 各文件的阅读顺序。

SSG	文档	用途
Astro	astro/overview.md	从这里开始了解 Astro
Hugo	hugo/overview.md	从这里开始了解 Hugo
Eleventy	eleventy/overview.md	从这里开始了解 Eleventy
Next.js	nextjs/overview.md	从这里开始了解 Next.js

其他技能：

技能	何时阅读
cloudcannon-visual-editing	迁移期间 — 区域、普查和完整性检查清单
cloudcannon-configuration	编写并验证用于替代生成结构的 _structures
cloudcannon-dev-server	让用户在本地编辑器中试用迁移后的站点

常见错误

借口	事实
“这是 Bookshop 站点，所以我要迁移它”	只有用户提出要求且该 SSG 标记为 Migrate 时才迁移。在 Bookshop 站点上更改组件属于 Bookshop 修改。
“这个新组件可以使用 editable-regions”	对于继续使用 Bookshop 的站点，新组件应当是 Bookshop 组件 — maintaining.md § 添加组件。