Overview
The theme includes optional support for Sveltia CMS, a git-based content management system that provides a browser-based editing interface for pages, articles, and fragments. Sveltia CMS is a modern replacement for Netlify CMS / Decap CMS and uses the same configuration format.
When enabled, an /admin/ route serves the CMS interface. Editors authenticate via their Git provider (GitHub, GitLab, or Gitea) and create or edit content through a form-based UI. Changes are committed directly to the repository.
The CMS is fully optional and disabled by default. When disabled, no admin route exists and the build includes zero CMS-related output.
Enabling the CMS
In astro.config.mjs, find the cmsIntegration registration and set enabled: true:
cmsIntegration({ enabled: true }),Configuring the Backend
The CMS configuration lives at src/site/config/cms/config.yml. Edit the backend section with your Git provider and repository details:
backend:
name: github
repo: your-org/your-repo
branch: mainSupported backends: github, gitlab, gitea.
Authentication
The CMS authenticates editors via OAuth through the configured Git provider. You need to register an OAuth application with your provider and configure the callback URL. Options include:
- Sveltia’s cloud OAuth — zero-infrastructure option; register a GitHub/GitLab OAuth app pointing to Sveltia’s hosted callback
- Self-hosted OAuth proxy — deploy your own callback handler for full control
- Platform identity services — Netlify Identity or similar if your hosting platform provides one
Refer to the Sveltia CMS documentation for provider-specific setup instructions.
Collections
Three content collections are exposed to editors:
Pages — utility and content pages from src/content/pages/. Editors can create, edit, and delete pages with fields for title, description, dates, author, category, tags, hero content, OG image, table of contents toggle, and the markdown body.
Articles — blog posts, news, and case studies from src/content/articles/. Same field set as pages.
Fragments — reusable content blocks from src/content/fragments/. Fragments use fragmentId as their identity field. Editors set title, fragment ID, tags, draft status, notes, and the markdown body.
Developer-only fields (layout overrides, SEO controls, rendering toggles) are not exposed in the CMS interface. These remain editable only through direct file editing.
Media Handling
Uploaded images are stored under src/site/assets/images/uploads/ with per-collection subdirectories:
src/site/assets/images/uploads/articles/src/site/assets/images/uploads/pages/src/site/assets/images/uploads/fragments/
Image references in markdown use the @site/ Vite alias (e.g., @site/assets/images/uploads/articles/photo.jpg), which routes through Astro’s image optimization pipeline for automatic WebP/AVIF conversion and responsive srcset generation.
Version Pinning
By default, the admin page loads the latest version of Sveltia CMS from the unpkg CDN. For production sites that need stability guarantees, you can pin a specific version by editing src/core/pages/admin/index.astro and changing the script source:
<script
is:inline
src="https://unpkg.com/@sveltia/[email protected]/dist/sveltia-cms.js"
></script>Replace 0.151.3 with the desired version. Available versions are listed on the npm package page.
Content Security Policy
The admin page loads JavaScript from unpkg.com. If your site enforces Content Security Policy headers, add https://unpkg.com to the script-src directive for the /admin/ path. The CMS also makes API calls to your Git provider’s API domain (e.g., api.github.com).
Robots and Indexing
When the CMS is enabled, the admin page includes <meta name="robots" content="noindex"> and the integration automatically adds /admin/ to the robots.txt disallow list. No manual robots configuration is needed.