hugo-sveltia-cms（雨果斯维尔蒂亚 CMS）

Hugo + Sveltia CMS Skill

Two primary workflows:

1. Bootstrap: New Hugo site with Sveltia CMS + Basecoat UI, deployed to Cloudflare Pages
2. Convert: Migrate from TinaCMS, Decap/Netlify CMS, WordPress, Jekyll, Eleventy, or other platforms to 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

Critical Knowledge

1. YAML front matter only. Sveltia CMS has bugs with TOML (+++). Always use YAML (---) and set format: yaml on every collection.
2. Use hugo.yaml not hugo.toml for config consistency.
3. Admin files in static/admin/. Hugo copies static/ to build root.
4. Media paths. media_folder: "static/images/uploads" (repo) → public_folder: "/images/uploads" (URL). Hugo strips static/.
5. GitHub OAuth required. Deploy sveltia-cms-auth as a Cloudflare Worker. Netlify git-gateway NOT supported.
6. Always set extension: "md" and format: "yaml" on every folder collection.
7. Schema line at top of config.yml: # yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

Workflow: Bootstrap

Step 1: Gather Requirements

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

Step 2: Scaffold Hugo + Basecoat

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>.

Step 3: Create Admin Interface

Create static/admin/index.html and static/admin/config.yml using templates/. Build collections from the domain-specific patterns in the reference file.

Step 4: Build Layouts with Basecoat Components

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.

Step 5: Create Archetypes + Seed Content

One archetype per content type in archetypes/.

Step 6: Deploy to Cloudflare Pages

1. Register GitHub OAuth App → get Client ID + Secret
2. Deploy sveltia-cms-auth Cloudflare Worker
3. Connect repo to CF Pages, set HUGO_VERSION env var
4. Build command: hugo --minify, output: public
5. 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

Step 7: Test Locally

Sveltia CMS detects localhost and uses File System Access API (Chromium) — no OAuth needed locally. Run hugo server, visit /admin/.

Workflow: Convert

From TinaCMS

TinaCMS uses GraphQL API + tina/config.ts schema + TinaCloud auth. Fundamentally different architecture.

Field type mapping:

Config mapping: tina/config.ts collections[].path → config.yml collections[].folder

Steps:

1. Read tina/config.{ts,js}, map each collection's fields using table above
2. Content files (Markdown + YAML front matter) stay as-is — Hugo reads them directly
3. Delete tina/ directory, remove tinacms from package.json, remove Tina build commands
4. Create static/admin/ with Sveltia CMS files
5. Map Tina media config (mediaRoot/publicFolder) → Sveltia media_folder/public_folder
6. Document shortcodes used in content (no CMS-side visual editing for these)
7. Deploy via CF Pages + GitHub OAuth

Key win: No more TinaCloud dependency, no GraphQL build step, no tina/__generated__/.

From Decap CMS / Netlify CMS

Drop-in replacement:

1. Replace script tag: <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
2. Existing config.yml works as-is
3. Replace git-gateway with GitHub OAuth + CF Worker
4. Test all collections

From WordPress

1. Export via wordpress-export-to-markdown or hugo import jekyll after Jekyll export
2. Clean front matter (strip wp_id, guid)
3. Map taxonomies → Hugo taxonomies
4. Download media → static/images/
5. Build collections matching cleaned structure

From Jekyll

1. hugo import jekyll <jekyll-root> <hugo-root> (built-in)
2. Review front matter, add Sveltia CMS per standard workflow

From Eleventy / Other SSGs

1. Copy Markdown + YAML front matter files into content/
2. Adjust for Hugo conventions (date format, draft boolean)
3. Rebuild templates in Hugo, add 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.

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

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