hugo-sveltia-cms

Hugo + Sveltia CMS Skill

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

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

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

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

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

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:

TinaCMS type

Sveltia widget

Notes

string

list: true

list

datetime

boolean

image

rich-text

markdown

Shortcode templates won't carry over

object

Map subfields recursively

reference

relation

Set collection , search_fields , value_field

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

From 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

From WordPress

Export via wordpress-export-to-markdown or 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

From Jekyll

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

From Eleventy / Other SSGs

Copy Markdown + YAML front matter files into content/
Adjust for Hugo conventions (date format, draft boolean)
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

hugo-sveltia-cms

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

kitchen-sink-design-system

design-lookup

local-ocr

nextjs-tinacms