hugo-sveltia-cms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hugo + Sveltia CMS Skill

Hugo + Sveltia CMS 技能指南

Two primary workflows:

Bootstrap: New Hugo site with Sveltia CMS + Basecoat UI, deployed to Cloudflare Pages
Convert: Migrate from TinaCMS, Decap/Netlify CMS, WordPress, Jekyll, Eleventy, or other platforms to Hugo + Sveltia CMS

两种核心工作流：

快速搭建：创建搭载Sveltia CMS + Basecoat UI的全新Hugo站点，并部署至Cloudflare Pages
迁移转换：将TinaCMS、Decap/Netlify CMS、WordPress、Jekyll、Eleventy或其他平台的站点迁移至Hugo + Sveltia CMS架构

Why This Stack

为何选择该技术栈

Hugo — Fastest SSG, single binary, Go templates
Sveltia CMS — Git-based headless CMS, drop-in Decap/Netlify CMS replacement with better UX and i18n. Beta, v1.0 early 2026. Same
```
config.yml
```
format as Decap
Basecoat — shadcn/ui components without React. Tailwind CSS utility classes (
```
btn
```
,
```
card
```
,
```
input
```
), minimal JS, dark mode, themeable
Cloudflare Pages — Primary deploy target. Free tier, fast CDN, Workers for OAuth
GitHub — Only supported Git backend

Hugo — 速度最快的SSG，单二进制文件，基于Go模板
Sveltia CMS — 基于Git的无头CMS，可无缝替代Decap/Netlify CMS，拥有更优的用户体验和国际化支持。当前为Beta版本，1.0版本预计2026年初发布。与Decap使用相同的
```
config.yml
```
配置格式
Basecoat — 无需React的shadcn/ui组件库。提供Tailwind CSS工具类（如
```
btn
```
、
```
card
```
、
```
input
```
），仅含少量JS代码，支持深色模式和主题定制
Cloudflare Pages — 首选部署目标。免费套餐、高速CDN，可通过Workers实现OAuth认证
GitHub — 唯一支持的Git后端

Critical Knowledge

关键注意事项

YAML front matter only. Sveltia CMS has bugs with TOML (
```
+++
```
). Always use YAML (
```
---
```
) and set
```
format: yaml
```
on every collection.
Use
hugo.yaml
not
```
hugo.toml
```
for config consistency.
Admin files in
static/admin/
. Hugo copies
```
static/
```
to build root.

Media paths.

media_folder: "static/images/uploads"

(repo) →

public_folder: "/images/uploads"

(URL). Hugo strips

static/

GitHub OAuth required. Deploy
```
sveltia-cms-auth
```
as a Cloudflare Worker. Netlify git-gateway NOT supported.
Always set
```
extension: "md"
```
and
```
format: "yaml"
```
on every folder collection.

Schema line at top of

config.yml

# yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

仅使用YAML前置元数据。Sveltia CMS在处理TOML（
```
+++
```
）时存在Bug。请始终使用YAML（
```
---
```
），并为每个集合设置
```
format: yaml
```
。
**使用
```
hugo.yaml
```
**而非
```
hugo.toml
```
以保证配置一致性。
管理文件存放于
static/admin/
目录。Hugo会将
```
static/
```
目录内容复制到构建根目录。
媒体文件路径。
```
media_folder: "static/images/uploads"
```
（仓库路径）对应
```
public_folder: "/images/uploads"
```
（访问URL）。Hugo会自动去除
```
static/
```
前缀。
必须配置GitHub OAuth。将
```
sveltia-cms-auth
```
部署为Cloudflare Worker。不支持Netlify git-gateway。
务必为每个文件夹集合设置
```
extension: "md"
```
和
```
format: "yaml"
```
。

config.yml
顶部需添加Schema行：

# yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

Workflow: Bootstrap

工作流：快速搭建

Step 1: Gather Requirements

步骤1：收集需求

Ask:

Site purpose: Consulting/services, medical practice, blog, portfolio, docs?
Content types: What content will they manage?
Basecoat approach: Full Tailwind pipeline (recommended) or CDN-only prototype?
Custom domain: For CF Pages + OAuth setup

询问用户：

站点用途：咨询/服务、医疗诊所、博客、作品集、文档站？
内容类型：需要管理哪些类型的内容？
Basecoat集成方式：完整Tailwind流水线（推荐）还是仅CDN引入的原型？
自定义域名：用于Cloudflare Pages + OAuth配置

Step 2: Scaffold Hugo + Basecoat

步骤2：搭建Hugo + Basecoat框架

bash

hugo new site <site-name> --format yaml
cd <site-name>

Read

references/hugo-sveltia-setup.md § Basecoat Integration

for setup details.

Production (recommended):

npm init -y && npm install -D tailwindcss @tailwindcss/cli basecoat-css

, create

assets/css/main.css

with

@import "tailwindcss"; @import "basecoat-css";

, wire via Hugo's

css.TailwindCSS

pipe.

CDN (quick start): Add CDN links to

baseof.html

<head>

bash

hugo new site <site-name> --format yaml
cd <site-name>

查看

references/hugo-sveltia-setup.md § Basecoat Integration

获取详细配置说明。

生产环境（推荐）：执行

npm init -y && npm install -D tailwindcss @tailwindcss/cli basecoat-css

，创建

assets/css/main.css

并添加

@import "tailwindcss"; @import "basecoat-css";

，通过Hugo的

css.TailwindCSS

管道引入。

快速原型（仅CDN）：在

baseof.html

的

<head>

中添加CDN链接。

Step 3: Create Admin Interface

步骤3：创建管理界面

Create

static/admin/index.html

and

static/admin/config.yml

using

templates/

. Build collections from the domain-specific patterns in the reference file.

使用

templates/

模板创建

static/admin/index.html

和

static/admin/config.yml

。参考文档中的领域特定模式构建集合。

Step 4: Build Layouts with Basecoat Components

步骤4：使用Basecoat组件构建布局

Create Hugo partials wrapping Basecoat classes:

partials/components/card.html

button.html

badge.html

alert.html

nav.html

. These accept parameters via Hugo

dict

and emit styled HTML.

创建封装Basecoat类的Hugo局部模板：

partials/components/card.html

、

button.html

、

badge.html

、

alert.html

、

nav.html

。这些模板可通过Hugo

dict

接收参数并生成样式化HTML。

Step 5: Create Archetypes + Seed Content

步骤5：创建原型模板 + 初始内容

One archetype per content type in

archetypes/

在

archetypes/

目录中为每种内容类型创建一个原型模板。

Step 6: Deploy to Cloudflare Pages

步骤6：部署至Cloudflare Pages

Register GitHub OAuth App → get Client ID + Secret
Deploy
```
sveltia-cms-auth
```
Cloudflare Worker
Connect repo to CF Pages, set
```
HUGO_VERSION
```
env var
Build command:
```
hugo --minify
```
, output:
```
public
```

The bootstrap creates

.github/workflows/deploy.yml

automatically — set

CLOUDFLARE_API_TOKEN

CLOUDFLARE_ACCOUNT_ID

as GitHub Secrets and

PAGES_PROJECT_NAME

as a GitHub Variable

注册GitHub OAuth应用 → 获取客户端ID和密钥
部署
```
sveltia-cms-auth
```
Cloudflare Worker
将仓库连接至Cloudflare Pages，设置
```
HUGO_VERSION
```
环境变量
构建命令：
```
hugo --minify
```
，输出目录：
```
public
```
快速搭建流程会自动创建
```
.github/workflows/deploy.yml
```
— 在GitHub Secrets中设置
```
CLOUDFLARE_API_TOKEN
```
、
```
CLOUDFLARE_ACCOUNT_ID
```
，并在GitHub Variables中设置
```
PAGES_PROJECT_NAME
```

Step 7: Test Locally

步骤7：本地测试

Sveltia CMS detects localhost and uses File System Access API (Chromium) — no OAuth needed locally. Run

hugo server

, visit

/admin/

Sveltia CMS会自动检测本地环境并使用文件系统访问API（Chromium浏览器）—— 本地测试无需OAuth认证。运行

hugo server

，访问

/admin/

即可。

Workflow: Convert

工作流：迁移转换

From TinaCMS

从TinaCMS迁移

TinaCMS uses GraphQL API +

tina/config.ts

schema + TinaCloud auth. Fundamentally different architecture.

Field type mapping:

TinaCMS `type`	Sveltia `widget`	Notes
`string`	`string`
`string` + `list: true`	`list`
`datetime`	`datetime`
`boolean`	`boolean`
`image`	`image`
`rich-text`	`markdown`	Shortcode templates won't carry over
`object`	`object`	Map subfields recursively
`reference`	`relation`	Set `collection` , `search_fields` , `value_field`
`number`	`number`	Set `value_type: int` or `float`

Config mapping:

tina/config.ts

collections[].path

→

config.yml

collections[].folder

Steps:

Read
```
tina/config.{ts,js}
```
, map each collection's fields using table above
Content files (Markdown + YAML front matter) stay as-is — Hugo reads them directly
Delete
```
tina/
```
directory, remove
```
tinacms
```
from
```
package.json
```
, remove Tina build commands
Create
```
static/admin/
```
with Sveltia CMS files

Map Tina media config (

mediaRoot

publicFolder

) → Sveltia

media_folder

public_folder

Document shortcodes used in content (no CMS-side visual editing for these)
Deploy via CF Pages + GitHub OAuth

Key win: No more TinaCloud dependency, no GraphQL build step, no

tina/__generated__/

TinaCMS采用GraphQL API +

tina/config.ts

配置 + TinaCloud认证，架构差异较大。

字段类型映射：

TinaCMS `type`	Sveltia `widget`	说明
`string`	`string`
`string` + `list: true`	`list`
`datetime`	`datetime`
`boolean`	`boolean`
`image`	`image`
`rich-text`	`markdown`	短代码模板无法直接迁移
`object`	`object`	递归映射子字段
`reference`	`relation`	设置 `collection` , `search_fields` , `value_field`
`number`	`number`	设置 `value_type: int` 或 `float`

配置映射：

tina/config.ts

中的

collections[].path

对应

config.yml

中的

collections[].folder

迁移步骤：

读取
```
tina/config.{ts,js}
```
，根据上表映射每个集合的字段
内容文件（Markdown + YAML前置元数据）可直接保留 — Hugo可直接读取
删除
```
tina/
```
目录，从
```
package.json
```
中移除
```
tinacms
```
依赖，删除Tina相关构建命令
创建
```
static/admin/
```
目录并添加Sveltia CMS文件

将Tina媒体配置（

mediaRoot

publicFolder

）映射为Sveltia的

media_folder

public_folder

记录内容中使用的短代码（CMS端无法可视化编辑这些短代码）
通过Cloudflare Pages + GitHub OAuth部署站点

核心优势： 不再依赖TinaCloud，无需GraphQL构建步骤，无

tina/__generated__/

目录。

From Decap CMS / Netlify CMS

从Decap CMS / Netlify CMS迁移

Drop-in replacement:

Replace script tag:

<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>

Existing
```
config.yml
```
works as-is
Replace
```
git-gateway
```
with GitHub OAuth + CF Worker
Test all collections

无缝替代：

替换脚本标签为：

<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>

现有
```
config.yml
```
可直接使用
将
```
git-gateway
```
替换为GitHub OAuth + Cloudflare Worker
测试所有集合

From WordPress

从WordPress迁移

Export via

wordpress-export-to-markdown

hugo import jekyll

after Jekyll export

Clean front matter (strip
```
wp_id
```
,
```
guid
```
)
Map taxonomies → Hugo taxonomies
Download media →
```
static/images/
```
Build collections matching cleaned structure

使用
```
wordpress-export-to-markdown
```
工具导出，或先导出至Jekyll再使用
```
hugo import jekyll
```
导入
清理前置元数据（移除
```
wp_id
```
、
```
guid
```
字段）
将WordPress分类法映射为Hugo分类法
下载媒体文件至
```
static/images/
```
目录
根据清理后的内容结构构建集合

From Jekyll

从Jekyll迁移

hugo import jekyll <jekyll-root> <hugo-root>

(built-in)

Review front matter, add Sveltia CMS per standard workflow

使用内置命令

hugo import jekyll <jekyll-root> <hugo-root>

检查前置元数据，按照标准流程添加Sveltia CMS

From Eleventy / Other SSGs

从Eleventy / 其他SSG迁移

Copy Markdown + YAML front matter files into
```
content/
```
Adjust for Hugo conventions (
```
date
```
format,
```
draft
```
boolean)
Rebuild templates in Hugo, add Sveltia CMS

将Markdown + YAML前置元数据文件复制至
```
content/
```
目录
调整为Hugo规范（如
```
date
```
格式、
```
draft
```
布尔值）
重新构建Hugo模板，添加Sveltia CMS

Domain-Specific Collections

领域特定集合

Read

references/hugo-sveltia-setup.md § Domain Collection Patterns

for ready-made configs:

Consulting / Services — Services, case studies, testimonials, team members
Medical Practice — Providers, locations, services/specialties, conditions, patient resources
Content / Blog — Posts, pages, authors, newsletter, categories

Mix and match. Each includes full field definitions.

查看

references/hugo-sveltia-setup.md § Domain Collection Patterns

获取现成配置：

咨询/服务站 — 服务项目、案例研究、客户评价、团队成员
医疗诊所站 — 医护人员、诊所位置、服务/专科、病症信息、患者资源
内容/博客站 — 文章、页面、作者、通讯、分类

可按需组合使用。每个集合包含完整的字段定义。

File Checklist

文件检查清单

```
hugo.yaml
```
```
package.json
```
+
```
assets/css/main.css
```
(Basecoat/Tailwind, if npm path)

static/admin/index.html

static/admin/config.yml

```
archetypes/
```
— one per content type
```
content/
```
— seed or converted content
```
layouts/
```
— Basecoat-styled templates + component partials
```
.github/workflows/deploy.yml
```
— CI/CD for Cloudflare Pages
```
.gitignore
```

```
hugo.yaml
```
```
package.json
```
+
```
assets/css/main.css
```
（若使用npm方式集成Basecoat/Tailwind）

static/admin/index.html

static/admin/config.yml

```
archetypes/
```
— 每种内容类型对应一个原型模板
```
content/
```
— 初始或迁移后的内容
```
layouts/
```
— Basecoat样式模板 + 组件局部模板
```
.github/workflows/deploy.yml
```
— Cloudflare Pages CI/CD的GitHub Actions工作流
```
.gitignore
```

Reference Files

参考文件

```
references/hugo-sveltia-setup.md
```
— Full config reference, domain collections, Basecoat setup, widgets, auth, CF Pages deploy, gotchas, i18n
```
templates/admin-index.html
```
— Admin page template
```
templates/config.yml
```
— Annotated CMS config starter
```
templates/deploy.yml
```
— GitHub Actions workflow for Cloudflare Pages CI/CD
```
scripts/bootstrap-hugo-sveltia.sh
```
— One-command scaffolding
```
scripts/convert-toml-to-yaml.py
```
— Batch front matter conversion

```
references/hugo-sveltia-setup.md
```
— 完整配置参考、领域集合、Basecoat配置、组件、认证、Cloudflare Pages部署、注意事项、国际化
```
templates/admin-index.html
```
— 管理页面模板
```
templates/config.yml
```
— 带注释的CMS配置模板
```
templates/deploy.yml
```
— Cloudflare Pages CI/CD的GitHub Actions工作流模板
```
scripts/bootstrap-hugo-sveltia.sh
```
— 一键搭建脚本
```
scripts/convert-toml-to-yaml.py
```
— 批量前置元数据转换脚本