migrate-to-cloudcannon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrating to CloudCannon

迁移到 CloudCannon

This skill orchestrates a full migration of an existing SSG site to CloudCannon. It coordinates five phases, delegating domain-specific work to standalone skills that can also be used independently.

Model recommendation: Migrations involve multi-file architectural decisions across five phases. Use a high-reasoning model (not a fast/lightweight one) for best results.

MUST: run the migration as its orchestrator. Read orchestration.md before Phase 1, then dispatch each phase to a subagent and keep the user conversation yourself. On a host without subagents, run the phases yourself in order.

此 skill 编排将现有 SSG 站点完整迁移到 CloudCannon 的全过程。它协调五个阶段，并将各个领域的工作委派给也可独立使用的独立 skill。

**模型建议：**迁移涉及跨五个阶段的、多文件架构决策。为获得最佳结果，请使用高推理能力模型（而非快速/轻量模型）。

**必须：**以 orchestrator（编排器）的身份运行迁移。在进入阶段 1 前阅读 orchestration.md，然后将每个阶段分派给一个 subagent，同时由你亲自维护与用户的对话。在不支持 subagent 的宿主环境中，请按顺序自行执行这些阶段。

When to use

使用场景

An existing SSG site needs to work with CloudCannon end to end
A site template needs to be made CloudCannon-compatible
A site is being generated as part of the task (e.g. from WordPress) and should land CloudCannon-ready

现有的 SSG 站点需要端到端适配 CloudCannon
站点模板需要变为兼容 CloudCannon
站点作为当前任务的一部分生成（例如从 WordPress 转换而来），且应达到可直接用于 CloudCannon 的状态

When not to use

不适用场景

The site is already on CloudCannon and needs one piece added — go straight to the capability skill:
```
cloudcannon-configuration
```
,
```
cloudcannon-snippets
```
, or
```
cloudcannon-visual-editing
```
Only multilingual or translation work is wanted —
```
make-site-multilingual
```
, then
```
translate-site
```
. Neither is part of the five phases.
One CloudCannon feature is misbehaving on a working site — the capability skill that owns it, not a full migration

站点已在 CloudCannon 上，只需要新增一项功能——直接使用相应的功能 skill：
```
cloudcannon-configuration
```
、
```
cloudcannon-snippets
```
或
```
cloudcannon-visual-editing
```
只需要多语言或翻译工作——使用
```
make-site-multilingual
```
，然后使用
```
translate-site
```
。这两项均不属于五个阶段。
正常运行中的站点有某个 CloudCannon 功能出现问题——使用负责该功能的能力 skill，而不是进行完整迁移

File	Covers
SKILL.md (this file)	The five phases, handoff readiness, naming conventions, common mistakes
astro/overview.md	Start here for Astro — the per-phase guides
hugo/overview.md	Start here for Hugo — the per-phase guides
eleventy/overview.md	Start here for Eleventy — the per-phase guides
audit.md	Shared audit rules — classifying static pages
page-building.md	Read when the census sends pages to a `pages` collection or page builder
cc-friendly-conventions.md	Shared-UI treatment table
orchestration.md	Running phases in subagents, questions, verification, sizing
handoff.md	Closing with the user — who tests what, and what to ask back
reading-order.md	Which docs to read in which phase, and when to skip them
scripts/README.md	Automation scripts for the deterministic steps

文件	涵盖内容
SKILL.md（本文件）	五个阶段、交接就绪状态、命名约定和常见错误
astro/overview.md	Astro 请从此处开始——各阶段指南
hugo/overview.md	Hugo 请从此处开始——各阶段指南
eleventy/overview.md	Eleventy 请从此处开始——各阶段指南
audit.md	共享审计规则——对静态页面进行分类
page-building.md	当页面普查结果将页面归入 `pages` collection 或 page builder 时阅读
cc-friendly-conventions.md	Shared-UI 处理表
orchestration.md	在 subagent 中运行各阶段、问题处理、验证和规模评估
handoff.md	与用户完成收尾——由谁测试什么，以及应向用户回问什么
reading-order.md	各阶段应阅读哪些文档，以及何时可以跳过
scripts/README.md	用于执行确定性步骤的自动化脚本

Supported SSGs

支持的 SSG

SSG	Guide
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy	eleventy/overview.md

SSG	指南
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy	eleventy/overview.md

Chaining with upstream skills

与上游 skill 衔接

If the site is being generated as part of this task (e.g. converting from WordPress), read the target SSG's scaffolding conventions before scaffolding — Astro: astro/cc-friendly-conventions.md — it covers the structural choices that make the migration smooth. Once scaffolded, return here and run the migration phases.

如果站点是在当前任务中生成的（例如从 WordPress 转换而来），请在搭建脚手架前阅读目标 SSG 的脚手架约定——Astro：astro/cc-friendly-conventions.md——其中涵盖了能让迁移更加顺畅的结构选型。完成脚手架搭建后，返回此处并运行迁移阶段。

Step 1: Detect the SSG

步骤 1：检测 SSG

Run from the project root:

bash

npx @cloudcannon/cli configure detect-ssg

Use the detected SSG to pick the correct guide above.

从项目根目录运行：

bash

npx @cloudcannon/cli configure detect-ssg

根据检测到的 SSG，从上方选择正确的指南。

Migration phases

迁移阶段

Each SSG guide walks through these in order. Phases that delegate to standalone skills are marked below.

Audit — Analyze content structure, components, routing, and build pipeline before changing anything.
Configuration — Generate and customize CloudCannon config files.
- Read the
```
cloudcannon-configuration
```
  skill.
- If content uses components (MDX components, Hugo or Eleventy shortcodes) or inline HTML, also read the
```
cloudcannon-snippets
```
  skill.
Content — Restructure content files if needed so they're CMS-friendly.
Visual editing — Add editable regions for CloudCannon's Visual Editor.
- Read the
```
cloudcannon-visual-editing
```
  skill.
Build and test — Validate the migration end-to-end.

Not every site needs all phases. Small sites may skip Phase 3 if content is already well-structured. Phase 4 is optional but high-value.

每个 SSG 指南都会按顺序讲解以下内容。委派给独立 skill 的阶段已标注如下。

审计——在更改任何内容前，分析内容结构、组件、路由和构建管道。
配置——生成并自定义 CloudCannon 配置文件。
- 阅读
```
cloudcannon-configuration
```
  skill。
- 如果内容使用组件（MDX 组件、Hugo 或 Eleventy shortcode）或内联 HTML，还应阅读
```
cloudcannon-snippets
```
  skill。
内容——必要时重构内容文件，使其适合 CMS。
可视化编辑——为 CloudCannon 的 Visual Editor 添加可编辑区域。
- 阅读
```
cloudcannon-visual-editing
```
  skill。
构建和测试——端到端验证迁移。

并非每个站点都需要所有阶段。如果内容已经结构良好，小型站点可以跳过阶段 3。阶段 4 是可选的，但价值很高。

Per-phase workflow

各阶段工作流

The phase subagent does steps 1–4; the orchestrator does step 5. See orchestration.md.

Read the phase doc end-to-end before touching any files.
Track one task per checklist item in that phase doc, using the host's task/todo tool. If there is none, keep the checklist in the phase's migration note and tick items off there. Set the task
```
in_progress
```
before starting it; mark
```
completed
```
only when the checklist item is satisfied. Do not batch-complete tasks at the end of the phase.
Do the work — small, mechanical cross-phase fixes (adding a missing field, normalizing a value) are fine in any phase; list each in the return. Structural changes (moving files, reorganizing collections, altering rendering) wait for their proper phase.
Write
```
.cloudcannon/migration/<phase>.md
```
with findings, plus two sections later phases rely on:
- Decisions and why — each choice and the reason, so later phases follow it instead of re-deciding
- Open questions — non-blocking questions for the user, each with the default taken
Verify the handoff readiness row below, by the orchestrator or a fresh verifier per orchestration.md § Verification. Never by the subagent that did the phase.

Why: checklists catch things agents otherwise skim past — data collections missing from

collections_config

data_config

entries missing for referenced data files, blog/detail page editables skipped while focusing on page-builder blocks, arrays not linked to structures. Per-item tracking makes the skim visible.

阶段 subagent 执行步骤 1–4，orchestrator 执行步骤 5。请参阅 orchestration.md。

阅读——在接触任何文件之前，完整阅读阶段文档。
跟踪——使用宿主的任务/todo 工具，为该阶段文档中的每个清单项跟踪一项任务。如果宿主没有此类工具，则将清单保留在该阶段的迁移说明中，并在那里逐项勾选。开始前将任务设为
```
in_progress
```
；只有清单项得到满足后才标记为
```
completed
```
。不要在阶段结束时批量完成任务。
执行工作——小型、机械性的跨阶段修复（添加缺失字段、规范值）可以在任何阶段完成；在返回结果中列出每一项。结构性更改（移动文件、重组 collection、改变渲染方式）应等待进入相应阶段后再执行。
编写
```
.cloudcannon/migration/<phase>.md
```
，记录发现结果，并添加后续阶段依赖的两个部分：
- 决策及原因——记录每项选择及其原因，让后续阶段遵循这些决策，而不是重新决策
- 待解决问题——向用户提出不阻塞工作的问题，并注明每个问题采用的默认值
验证下方的阶段交接就绪状态行，由 orchestrator 或依据 orchestration.md § Verification 的全新验证者完成。绝不能由执行该阶段的 subagent 验证。

**原因：**清单能够捕捉 Agent 否则容易略过的问题——

collections_config

中遗漏数据 collection、引用数据文件却缺少

data_config

项、专注于 page builder 区块时漏掉博客/详情页可编辑项，以及数组未与结构关联。逐项跟踪能让这些“一扫而过”的问题变得可见。

Phase handoff readiness

阶段交接就绪状态

These rows define what must be true before the next phase's subagent starts. Cross-phase fixes (per step 3 above) are still fine.

After phase	Ready for handoff when…
1. Audit	`.cloudcannon/migration/audit.md` exists, contains the census table, and lists every collection + every page route. Sizing thresholds (orchestration.md § Sizing) have been evaluated; if tripped, `.cloudcannon/migration/plan.md` exists.
2. Configuration	`cloudcannon.config.yml` validates against the published JSON schema (no IDE red squigglies). Every collection in the audit has a `collections_config` entry; every referenced data file has a `data_config` entry. `.cloudcannon/migration/configuration.md` written.
3. Content	All structural content changes from Phase 2 are reflected in the files. `npm run build` (or project equivalent) succeeds. `.cloudcannon/migration/content.md` written.
4. Visual editing	Every audit census row with a yes in Needs editable region? has been wired or has a documented justification for not being wired. Every component used inside a wrapped section can re-render — registered (Astro: `registerComponents.ts` ) or resolvable (Hugo: a partial; Eleventy: a Liquid include — Nunjucks sections use primitive regions only). `.cloudcannon/migration/visual-editing.md` written.
5. Build and test	Production build succeeds locally. User has run their CloudCannon-side verification (preview, inline edit, save-to-git). `.cloudcannon/migration/build.md` written.

以下各行定义了进入下一阶段前必须满足的条件。跨阶段修复（见上述步骤 3）仍然适用。

阶段结束后	满足以下条件时即可交接
1. 审计	`.cloudcannon/migration/audit.md` 存在，包含普查表，并列出每个 collection 和每条页面路由。已评估规模阈值（orchestration.md § Sizing）；如果触发阈值，则 `.cloudcannon/migration/plan.md` 存在。
2. 配置	`cloudcannon.config.yml` 根据已发布的 JSON schema 验证通过（IDE 中没有红色波浪线）。审计中的每个 collection 都有 `collections_config` 项；每个被引用的数据文件都有 `data_config` 项。已编写 `.cloudcannon/migration/configuration.md` 。
3. 内容	阶段 2 中所有结构化内容更改均已反映在文件中。 `npm run build` （或项目中的等效命令）执行成功。已编写 `.cloudcannon/migration/content.md` 。
4. 可视化编辑	审计普查表中“需要可编辑区域？”一列为 yes 的每一行都已接入，或已记录不接入的理由。包装区块中使用的每个组件都可以重新渲染——已注册（Astro： `registerComponents.ts` ）或可解析（Hugo：partial；Eleventy：Liquid include——Nunjucks 区块仅使用 primitive 区域）。已编写 `.cloudcannon/migration/visual-editing.md` 。
5. 构建和测试	生产构建在本地执行成功。用户已执行 CloudCannon 端验证（预览、行内编辑、保存至 Git）。已编写 `.cloudcannon/migration/build.md` 。

Scripts

脚本

Deterministic migration steps are automated as scripts in scripts/. Run these before or during the relevant phase.

确定性的迁移步骤已自动化为 scripts/ 中的脚本。请在相关阶段之前或期间运行这些脚本。

Migration notes

迁移说明

All written to

.cloudcannon/migration/

(under

.cloudcannon/

so the CLI doesn't detect the folder as a collection): one file per phase (

audit.md

configuration.md

content.md

visual-editing.md

build.md

), plus

plan.md

if the migration is sectioned. See the per-phase workflow above for the gates that consume each file.

所有说明均写入

.cloudcannon/migration/

（放在

.cloudcannon/

下，以免 CLI 将该文件夹检测为 collection）：每个阶段一个文件（

audit.md

、

configuration.md

、

content.md

、

visual-editing.md

、

build.md

），如果迁移按板块拆分，还需提供

plan.md

。请参阅上述各阶段工作流，了解使用这些文件的关卡。

Naming conventions

命名约定

Follow existing project conventions when present. Otherwise:

```
kebab-case
```
for files
```
camelCase
```
for JavaScript and JSON
Markdown frontmatter and YAML: match existing component prop names so frontmatter keys pass through without translation
New fields with no existing convention: prefer
```
snake_case
```

如果项目中已有约定，请遵循现有项目约定。否则：

文件使用
```
kebab-case
```
JavaScript 和 JSON 使用
```
camelCase
```
Markdown frontmatter 和 YAML：匹配现有组件 prop 名称，使 frontmatter 键无需转换即可透传
新字段没有现有约定时：优先使用
```
snake_case
```

Cross-references for known pitfalls

已知问题的交叉参考

For specific architectural decisions and config-syntax mistakes, see:

Topic	Astro	Hugo	Eleventy
Classifying static pages (source-editable vs page-builder vs collection)	audit.md § Classifying static pages, then astro/audit.md	hugo/audit.md § Classifying static pages	eleventy/audit.md § Classifying static pages
Home page filename, collection-of-one	page-building.md § Common mistakes, then astro/page-building.md § Pages collection cheatsheet	hugo/page-building.md § Common mistakes	eleventy/page-building.md § Common mistakes
Shared UI (CTA banners, footers, share blocks)	cc-friendly-conventions.md § Shared-UI treatment table	Same table	Same table
Multi-schema collections	../cloudcannon-configuration/astro/configuration.md § Schemas	../cloudcannon-configuration/hugo/configuration.md § Schemas	../cloudcannon-configuration/schemas.md
Config-syntax hallucinations (wrong keys/types)	`cloudcannon-configuration` § Invalid keys	Same	Same
Build verification	build.md § Build verification checklist, then astro/build.md	build.md, then hugo/build.md	build.md, then eleventy/build.md

有关具体架构决策和配置语法错误，请参阅：

主题	Astro	Hugo	Eleventy
对静态页面进行分类（source-editable、page builder 或 collection）	audit.md § 对静态页面进行分类，然后 astro/audit.md § 对静态页面进行分类（source-editable 与 content collection）	hugo/audit.md § 对静态页面进行分类	eleventy/audit.md § 对静态页面进行分类
首页文件名、单条目 collection	page-building.md § 常见错误，然后 astro/page-building.md § Pages collection 速查表	hugo/page-building.md § 常见错误	eleventy/page-building.md § 常见错误
Shared UI（CTA 横幅、页脚、分享块）	cc-friendly-conventions.md § Shared-UI 处理表	同一表格	同一表格
多 schema collection	../cloudcannon-configuration/astro/configuration.md § Schemas	../cloudcannon-configuration/hugo/configuration.md § Schemas	../cloudcannon-configuration/schemas.md
配置语法幻觉（错误的键名或类型）	`cloudcannon-configuration` § 无效键	同上	同上
构建验证	build.md § 构建验证清单，然后 astro/build.md	build.md，然后 hugo/build.md	build.md，然后 eleventy/build.md

Common mistakes

常见错误

Excuse	Reality
"This site is simple enough to skip the audit"	The audit catches structural issues early. Skipping it means discovering problems mid-configuration.
"I'll do the checklist at the end"	Read checklists BEFORE starting each phase. They tell you what to aim for.
"Content restructuring can wait"	If a missing field blocks configuration, add it now. Phases are sequential, not siloed.
"Visual editing is optional so I'll skip it"	It's the highest-value phase for editors. Only skip if the user explicitly says so.
"The build passes so we're done"	A passing build doesn't mean the editor works. The user must verify in CloudCannon.
"I'll call the homepage file `home.md` — it's more descriptive"	CloudCannon resolves the URL from the slug; `home.md` with `url: "/[slug]/"` → `/home/` . Use the SSG's index filename so the slug collapses to `/` — Astro: `index.md` ; Hugo: `content/_index.md` ; Eleventy: `index.md` in the input directory.
"It's hardcoded, so it's developer-only"	If an editor can see it on the page, they must be able to edit it. The mechanism depends on the page: shared UI (CTA banners, footers, share blocks, author cards) → data file; pages whose sections editors add, remove or reorder → page-builder `pages` collection entry; long-form prose page → `default` schema in the `pages` collection; one-off page whose structure stays with the developer → `data-editable="source"` . See cc-friendly-conventions.md § Shared-UI treatment table and page-building.md § When to reach for a page builder.
"This page is unique so it should be source-editable"	Uniqueness isn't the test. Page builder is the default; source editables need every condition in page-building.md § When to reach for a page builder.
"I'll make a single-entry `homepage` collection"	Use one `pages` collection with `index.md` as one entry. Add `our-team.md` , `about.md` , etc. as more entries. CloudCannon collections support multiple schemas per collection — via `schemas:` config, and in Astro also via Zod `z.union` in the content config. See ../cloudcannon-configuration/schemas.md.
"Page builder is overkill for these few pages"	Page builder is the default when the project owns its layouts and has more than one unique-layout page. Pages a theme renders keep the theme's model — see audit.md § Classifying static pages. The cost is a catch-all route plus a block dispatcher — Astro: `[...slug].astro` + `BlockRenderer` ; Hugo: a `range` over `content_blocks` in the page layout; Eleventy: a `for` loop over `content_blocks` in the layout. All are mechanical. The benefit is editors can add new pages without engineering.

借口	实际情况
“这个站点足够简单，可以跳过审计”	审计可以尽早发现结构问题。跳过审计意味着在配置进行到一半时才发现问题。
“我会在最后才做清单”	在开始每个阶段前阅读清单。它们会告诉你目标是什么。
“内容重构可以之后再做”	如果缺少字段阻塞了配置，现在就添加。各阶段是顺序执行的，并非彼此隔离。
“可视化编辑是可选的，所以我会跳过它”	这是对编辑人员价值最高的阶段。除非用户明确要求跳过，否则不要跳过。
“构建通过了，所以完成了”	构建通过并不意味着编辑器能正常工作。用户必须在 CloudCannon 中验证。
“我会把首页文件命名为 `home.md` ——这个名称更有描述性”	CloudCannon 根据 slug 解析 URL；使用 `url: "/[slug]/"` 的 `home.md` → `/home/` 。使用 SSG 的 index 文件名，使 slug 折叠为 `/` ——Astro： `index.md` ；Hugo： `content/_index.md` ；Eleventy：输入目录中的 `index.md` 。
“这是硬编码的，所以只属于开发人员”	如果编辑人员能在页面上看到它，就应当能够编辑它。具体机制取决于页面：Shared UI（CTA 横幅、页脚、分享块、作者卡片）→ 数据文件；编辑人员可添加、删除或重新排序其区块的页面 → page builder 的 `pages` collection 项；长篇文本页面 → `pages` collection 中的 `default` schema；结构由开发人员保留的一次性页面 → `data-editable="source"` 。请参阅 cc-friendly-conventions.md § Shared-UI 处理表和 page-building.md § 何时使用 page builder。
“这个页面很独特，所以应该采用 source-editable”	独特性不是判断标准。当项目拥有自己的布局且有多个独特布局页面时，page builder 是默认方案。由主题渲染的页面应保留主题模型——请参阅 audit.md § 对静态页面进行分类。source-editable 需要满足 page-building.md § 何时使用 page builder 中的每一个条件。
“我会创建一个只有单个条目的 `homepage` collection”	使用一个 `pages` collection，并将 `index.md` 作为其中一个条目。随着条目增加，再添加 `our-team.md` 、 `about.md` 等。CloudCannon collection 支持通过 `schemas:` 配置为每个 collection 配置多个 schema；在 Astro 中，还可通过内容配置中的 Zod `z.union` 实现。请参阅 ../cloudcannon-configuration/schemas.md。
“对于这几个页面来说，page builder 有点大材小用”	当项目拥有自己的布局且有多个独特布局页面时，page builder 是默认方案。由主题渲染的页面应保留主题模型——请参阅 audit.md § 对静态页面进行分类。这需要引入一个 catch-all 路由和一个区块分发器——Astro： `[...slug].astro` + `BlockRenderer` ；Hugo：在页面布局中对 `content_blocks` 使用 `range` ；Eleventy：在布局中对 `content_blocks` 使用 `for` 循环。所有这些都是机械性的改动。其好处是编辑人员无需开发人员介入即可新增页面。