DOCSEARCHbyAlgolia
Submit Docs

Sveltia CMS Documentation

repository·main·Indexed 25 days ago

https://github.com/sveltia/sveltia-cms

Sveltia CMS is a modern, lightweight, Git-based headless content management system for Jamstack sites. Designed as a high-performance successor to Netlify/Decap CMS, it is framework-agnostic and works with vanilla JavaScript or Static Site Generators like Astro, Eleventy, and Hugo. Key features include first-class internationalization (i18n) support, mobile support, and a single-page web application architecture served from a CDN.

Tokens
10.4K
Snippets
7
Records
65
Agent score
83%

What's inside Sveltia CMS

  1. Overview of Sveltia CMS

    main

    Sveltia CMS is a Git-based headless CMS designed for Jamstack sites. It is a modern, open-source rewrite of Netlify CMS (now Decap CMS), delivered as a lightweight, single-page web application served from a CDN.

    Key characteristics:

    • Framework-agnostic: Works with vanilla JavaScript or Static Site Generators (SSG) like Astro, Eleventy, or Hugo.
    • Git-based: Manages content directly within your Git repository.
    • High Compatibility: Designed as a successor to Netlify/Decap CMS with high compatibility for existing installations.
    • Features: Includes first-class internationalization (i18n) support, mobile support, and improved performance/security over its predecessors.

  2. Use MessageFormat 2 (MF2) for pluralization and gender

    main

    Sveltia CMS uses Unicode MessageFormat 2 (MF2) for handling complex translations such as pluralization and gender-specific strings.

    Implementation Details

    • Pluralization: You must implement the correct pluralization rules for your specific language. Some languages require multiple forms (e.g., Arabic, Polish, Russian), while others require only one (e.g., Chinese, Japanese).
    • Syntax: Refer to the MF2 translator guide and the Sveltia I18n documentation for specific syntax requirements.
    • RTL Support: Right-to-left (RTL) languages are supported; the CMS layout adjusts automatically based on the language direction.

  3. Getting started with Sveltia CMS

    main

    To begin using Sveltia CMS, you can follow the official documentation guides:

    • Introduction: Learn about product highlights, use cases, and project goals.
    • Getting Started: Follow step-by-step setup instructions to integrate Sveltia CMS into your project.
    • Migration: If you are moving from another CMS (like Netlify/Decap CMS or WordPress), refer to the Migration Guides for specific instructions.

  4. Contribute translations to Sveltia CMS

    main

    To localize Sveltia CMS, you must follow a specific workflow involving GitHub issues and pull requests. You are required to translate two separate files located in different repositories:

    1. Sveltia UI strings: Located in the sveltia-ui repository.
    2. Sveltia CMS strings: Located in the sveltia-cms repository.

    Workflow Steps

    1. Check existing translations: Verify if your language is already on the waiting list or already translated.
    2. File an issue: Create a new issue with the label l10n (e.g., "French localization"). This is required before submitting a PR to prevent duplication. You can request an AI-generated draft in the issue.
    3. Submit Pull Request: Use the title format Add [language] localization or Update [language] localization.
    4. Review: Translations will be reviewed for YAML and MessageFormat 2 (MF2) syntax errors.

  5. Technical guidelines for localization files

    main

    Localization files in Sveltia CMS must adhere to the following technical specifications:

    File Format and Naming

    • Format: YAML
    • Encoding: UTF-8
    • Line Endings: LF (Unix format)
    • Naming Convention: Use ISO 639-1 language codes following Firefox l10n conventions. Use short codes where possible (e.g., ko instead of ko-KR, fr instead of fr-FR), otherwise use the full code (e.g., en-US, pt-BR).

    YAML Formatting Rules

    • Indentation: Maintain correct hierarchy.
    • Comments: Do not translate or delete comments; they provide essential context.
    • Quotes: Omit quotes unless required by YAML syntax (e.g., for colons or brackets). Use key: value instead of key: 'value'.
    • Typography: Use curly quotes (“ ”) for content if your language uses them, but use straight quotes (" ") for code snippets and technical terms.
    • Formatting: Preserve all HTML or Markdown formatting (links, code snippets, etc.) within the strings.

  6. Linting configuration for Sveltia CMS

    main

    Sveltia CMS uses ESLint with a flat configuration (eslint.config.js) that integrates several plugins to enforce code quality, styling, and documentation standards. The configuration covers JavaScript, Svelte, and package.json files.

    Key features of the linting setup include:

    • Styling: Enforced via @stylistic/eslint-plugin and prettier to ensure consistent code formatting.
    • Svelte Support: Uses eslint-plugin-svelte for Svelte-specific linting rules.
    • Documentation: Enforces JSDoc standards using eslint-plugin-jsdoc.
    • Import Management: Uses import-x and unused-imports to manage and sort module imports.
    • Package Management: Uses eslint-plugin-package-json to validate package.json files.

    Files ignored by the linter include **/*.cjs, **/*.d.ts, package/, and .vite/.

  7. How to manually initialize Sveltia CMS

    main

    By default, Sveltia CMS attempts to initialize itself automatically. If you want to prevent automatic initialization (for example, to perform setup tasks before the CMS starts), set window.CMS_MANUAL_INIT to true before the script loads.

    To start the CMS manually after your custom logic is complete, call window.initCMS().

  8. How App Branding and PWA Manifests are generated

    main

    Sveltia CMS uses the configured branding to automatically support Progressive Web App (PWA) features. The process follows this lifecycle:

    1. Title & Logo Extraction: The system reads app_title and logo.src (or logo_url) from your configuration.
    2. Icon Transformation: The system fetches the logo image and generates two WebP thumbnails: a small icon (192x192) and a large icon (512x512). These are used for the app manifest and Apple touch icons.
    3. Manifest Creation: A JSON manifest is dynamically generated as a Blob URL. This manifest includes:
      • name and short_name: Derived from app_title.
      • start_url: The current origin and pathname.
      • display: Set to standalone.
      • icons: The generated WebP thumbnails.

    This allows your CMS to be 'installable' on mobile devices and desktops as a standalone application.

  9. Configure the development site URL

    main

    In development mode, Sveltia CMS assumes the local site is running on http://localhost:5174 by default. If your site is running on a different port (e.g., a Next.js app on port 3000), you can specify the URL using the VITE_SITE_URL environment variable.

    Example:

    VITE_SITE_URL=http://localhost:3000 pnpm dev

    Important: Ensure your dev server provides the Access-Control-Allow-Origin: * HTTP header to avoid CORS errors when the CMS attempts to fetch the configuration file.

  10. Configure App Branding in Sveltia CMS

    main

    You can customize the branding of your Sveltia CMS instance by providing specific fields in your CMS configuration. The branding affects the application title, the logo displayed in the UI, and the PWA (Progressive Web App) manifest.

    Configuration Keys

    • app_title: A string that sets the name of the CMS. If not provided, it defaults to Sveltia CMS.
    • logo.src: The URL for the application logo. This is the preferred method for setting a custom logo.
    • logo_url: A deprecated field used for backward compatibility to set the logo URL.

    When these values are configured, Sveltia CMS automatically generates a WebP-transformed app icon and a web manifest for PWA support.

  11. Configure the GitLab backend

    main

    To use GitLab as your Sveltia CMS backend, include a backend object in your cmsConfig. The configuration determines how the CMS connects to your GitLab instance, handles authentication, and identifies the project.

    Available configuration keys:

    • name: Must be set to the GitLab backend name (internally matched against BACKEND_NAME).
    • repo: The full path to your project (e.g., namespace/project). In GitLab, the namespace can include groups and subgroups.
    • branch: The branch to use for content management.
    • base_url: (Optional) The root URL for authentication. Defaults to DEFAULT_AUTH_ROOT.
    • auth_endpoint: (Optional) The authentication endpoint path. Defaults to DEFAULT_AUTH_PATH.
    • app_id: (Optional) Your GitLab OAuth application client ID.
    • api_root: (Optional) The base URL for the REST API (e.g., https://gitlab.com/api/v1). Defaults to DEFAULT_API_ROOT.
    • graphql_api_root: (Optional) The base URL for the GraphQL API. If not provided, it is derived from api_root.
    • include_credentials: (Optional) Boolean indicating if credentials should be included in requests. Defaults to false.

  12. Troubleshoot Sveltia CMS loading warnings

    main

    Sveltia CMS performs several environment checks and will issue warnings in the browser console if it detects configurations that may cause issues:

    1. Invalid Stylesheet: If you include <link rel="stylesheet" href=".../sveltia-cms.css">, remove it. Sveltia CMS does not require an external stylesheet.
    2. ES Module Attribute: If your <script> tag for Sveltia CMS includes type="module", remove it. The script is not an ES module, and using this attribute can cause unexpected behavior with the JavaScript API.
    3. Netlify Identity Widget: If https://identity.netlify.com/v1/netlify-identity-widget.js is detected in the document, note that the Netlify Identity Widget is not compatible with Sveltia CMS.