@sveltia/cms 0.104.0 → 0.104.2

package/README.md

@@ -44,9 +44,9 @@ Welcome to the only Netlify CMS successor you can trust!
   - [Better customization](#better-customization)
   - [Better localization](#better-localization)
 - [Compatibility](#compatibility)
+  - [Current limitations](#current-limitations)
   - [Features not to be implemented](#features-not-to-be-implemented)
   - [Other breaking changes](#other-breaking-changes)
-  - [Current limitations](#current-limitations)
   - [Compatibility with Static CMS](#compatibility-with-static-cms)
   - [Framework support](#framework-support)
   - [Backend support](#backend-support)
@@ -244,6 +244,7 @@ Note: This lengthy section compares Sveltia CMS with both Netlify CMS and Decap
 
 ### Better configuration
 
+- We provide clear [compatibility information](#compatibility) to help you avoid unsupported options and configurations that might cause errors. By contrast, the Netlify/Decap CMS documentation does not mention the deprecation of camel case options, the removal of the Date widget and the replacement of Moment.js.
 - Sveltia CMS supports a [JSON configuration file](#providing-a-json-configuration-file) that can be generated for bulk or complex collections.[^60]
 - Also supports [multiple configuration files](#providing-multiple-configuration-files) to allow developers to modularize the configuration.[^197]
 - We provide an [up-to-date JSON schema](#enabling-autocomplete-and-validation-for-the-configuration-file) for YAML/JSON configuration files, which enables autocomplete and validation in VS Code and other editors.[^253]
@@ -601,12 +602,36 @@ We are trying to make Sveltia CMS compatible with Netlify/Decap CMS where possib
 
 However, 100% feature parity is never planned, and some features are still missing or will not be added due to performance, deprecation and other factors. Look at the compatibility info below to see if you can migrate now or in the near future.
 
+### Current limitations
+
+These Netlify/Decap CMS features are not yet implemented in Sveltia CMS. We are working hard to add them before the 1.0 release due late 2025. Check our [release notes](https://github.com/sveltia/sveltia-cms/releases) and [Bluesky](https://bsky.app/profile/sveltiacms.app) for updates.
+
+- Comprehensive site config validation
+- [Cloudinary](https://decapcms.org/docs/cloudinary/) and [Uploadcare](https://decapcms.org/docs/uploadcare/) media libraries ([#4](https://github.com/sveltia/sveltia-cms/discussions/4))
+- LineString and Polygon types for the [Map](https://decapcms.org/docs/widgets/#map) widget
+- Advanced customization features:
+  - Preview for [custom editor components](https://decapcms.org/docs/custom-widgets/#registereditorcomponent)
+  - [Custom widgets](https://decapcms.org/docs/custom-widgets/)
+  - [Custom preview templates](https://decapcms.org/docs/customization/#registerpreviewtemplate) ([#51](https://github.com/sveltia/sveltia-cms/issues/51))
+  - [Event hooks](https://decapcms.org/docs/registering-events/) ([#167](https://github.com/sveltia/sveltia-cms/issues/167))
+
+[Localization](https://github.com/sveltia/sveltia-cms/blob/main/src/lib/locales/README.md), [documentation](https://github.com/sveltia/sveltia-cms/issues/485) and [demo site](https://github.com/sveltia/sveltia-cms/issues/1) will all be prepared once the 1.0 Release Candidate is ready.
+
+Due to the complexity, we have decided to defer the following features to the 2.0 release due early 2026. Netlify/Decap CMS has dozens of open issues with these collaboration and beta features — we want to implement them the right way.
+
+- [Editorial workflow](https://decapcms.org/docs/editorial-workflows/)
+- [Open authoring](https://decapcms.org/docs/open-authoring/)
+- [Nested collections](https://decapcms.org/docs/collection-nested/) (beta)
+- The `media_folder` and `public_folder` options (beta) for the [File](https://decapcms.org/docs/widgets/#file) and [Image](https://decapcms.org/docs/widgets/#image) widgets ([#497](https://github.com/sveltia/sveltia-cms/issues/497))
+
 ### Features not to be implemented
 
+The following Netlify/Decap CMS features will not be implemented, primarily due to deprecation and performance considerations.
+
 - **Azure and Bitbucket backends**: For performance reasons. We’ll support these platforms if their APIs improve to allow the CMS to fetch multiple entries at once.
 - **Git Gateway backend**: Also for performance reasons. [Git Gateway](https://github.com/netlify/git-gateway) has not been actively maintained since Netlify CMS was abandoned, and it’s known to be slow and prone to rate limit violations. We plan to develop a GraphQL-based high-performance alternative [in the future](#roadmap).
 - **Netlify Identity Widget**: It’s not useful without Git Gateway, and the Netlify Identity service itself is now [deprecated](https://www.netlify.com/changelog/deprecation-netlify-identity/). We plan to develop an alternative solution with role support [in the future](#roadmap), most likely using [Cloudflare Workers](https://workers.cloudflare.com/) and [Auth.js](https://authjs.dev/).
-- [Gatsby plugin](https://github.com/decaporg/gatsby-plugin-decap-cms): Given the [decline of Gatsby](https://2024.stateofjs.com/en-US/libraries/meta-frameworks/), we won’t invest time in developing a plugin for it. You can still create `index.html` yourself. Note: We don’t support Netlify Identity Widget; the favicon can be specified with the `logo_url` option.
+- [Gatsby plugin](https://github.com/decaporg/gatsby-plugin-decap-cms): In light of Gatsby’s [decline](https://2024.stateofjs.com/en-US/libraries/meta-frameworks/) and [apparent ending](https://github.com/gatsbyjs/gatsby/discussions/39062), we won’t be investing time in developing a plugin for it. You can still create `index.html` yourself. Note: We don’t support Netlify Identity Widget; the favicon can be specified with the `logo_url` option.
 - The deprecated client-side implicit grant for the GitLab backend: It has already been [removed from GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/344609). Use the client-side PKCE authorization instead.
 - The deprecated Netlify Large Media service: Consider other storage providers.
 - Deprecated camel case configuration options: Use snake case instead, according to the current Decap CMS document.
@@ -617,7 +642,7 @@ However, 100% feature parity is never planned, and some features are still missi
   - [Relation](https://decapcms.org/docs/widgets/#relation) widget: `displayFields`, `searchFields`, `valueField`
   - Note: Some other camel case options, including Color widget options, are not deprecated.
 - The deprecated Date widget: It was removed from Decap CMS 3.0 and Sveltia CMS 0.10. Use the DateTime widget with the [`time_format: false` option](#changing-the-input-type-of-a-datetime-field) instead.
-- The theme and keymap inline settings for the Code widget, along with support for some languages. Instead of [CodeMirror](https://codemirror.net/), we use Lexical’s code block functionality powered by [Prism](https://prismjs.com/), which will soon be [replaced by Shiki](https://github.com/facebook/lexical/issues/6575).
+- The theme and keymap inline settings for the Code widget, along with support for some languages. Instead of [CodeMirror](https://codemirror.net/), we use Lexical’s code block functionality powered by [Prism](https://prismjs.com/), which is slated to be [replaced by Shiki](https://github.com/facebook/lexical/issues/6575).
 - Remark plugins for the Markdown widget: Not compatible with our Lexical-based rich text editor.
 - An absolute URL in the [`public_folder`](https://decapcms.org/docs/configuration-options/#public-folder) option: Such configuration is not recommended, as stated in the Netlify/Decap CMS document.
 - Performance-related options: Sveltia CMS has [drastically improved performance](#better-performance) with GraphQL enabled by default, so these are no longer relevant:
@@ -638,26 +663,6 @@ There are some differences in behaviour between Sveltia CMS and Netlify/Decap CM
 
 [Let us know](https://github.com/sveltia/sveltia-cms/issues/new?type=bug) if you have encounter any compatibility issues that are not listed here.
 
-### Current limitations
-
-These Netlify/Decap CMS features are not yet implemented in Sveltia CMS. We are working hard to add them before the 1.0 release due late 2025. Check our [release notes](https://github.com/sveltia/sveltia-cms/releases) and [Bluesky](https://bsky.app/profile/sveltiacms.app) for updates.
-
-- Comprehensive site config validation
-- [Localization](https://github.com/sveltia/sveltia-cms/blob/main/src/lib/locales/README.md) other than English and Japanese
-- [Cloudinary](https://decapcms.org/docs/cloudinary/) and [Uploadcare](https://decapcms.org/docs/uploadcare/) media libraries ([#4](https://github.com/sveltia/sveltia-cms/discussions/4))
-- LineString and Polygon types for the [Map](https://decapcms.org/docs/widgets/#map) widget
-- [Custom widgets](https://decapcms.org/docs/custom-widgets/)
-- Preview for [custom editor components](https://decapcms.org/docs/custom-widgets/#registereditorcomponent)
-- [Custom preview templates](https://decapcms.org/docs/customization/#registerpreviewtemplate) ([#51](https://github.com/sveltia/sveltia-cms/issues/51))
-- [Event hooks](https://decapcms.org/docs/registering-events/) ([#167](https://github.com/sveltia/sveltia-cms/issues/167))
-
-Due to the complexity, we have decided to defer the following features to the 2.0 release due early 2026. Netlify/Decap CMS has dozens of open issues with these collaboration and beta features — we want to implement them the right way.
-
-- [Editorial workflow](https://decapcms.org/docs/editorial-workflows/)
-- [Open authoring](https://decapcms.org/docs/open-authoring/)
-- [Nested collections](https://decapcms.org/docs/collection-nested/) (beta)
-- The `media_folder` and `public_folder` options (beta) for the [File](https://decapcms.org/docs/widgets/#file) and [Image](https://decapcms.org/docs/widgets/#image) widgets ([#497](https://github.com/sveltia/sveltia-cms/issues/497))
-
 ### Compatibility with Static CMS
 
 Sveltia CMS provides partial compatibility with [Static CMS](https://github.com/StaticJsCMS/static-cms), a now-defunct fork of Netlify CMS. Since Static CMS was archived some time ago, we don’t plan to implement additional compatibility beyond what’s listed below. However, we may still adopt some of their features that we find useful.
@@ -691,6 +696,8 @@ We have added support for features and file structures used in certain framework
 
 ### Backend support
 
+Sveltia CMS supports the GitHub, GitLab and Gitea/Forgejo [backends](#better-backend-support). The Test backend is also available for local testing. There are a few differences compared to Netlify/Decap CMS:
+
 - The GitLab backend requires GitLab 16.3 or later.
 - The Gitea/Forgejo backend requires Gitea 1.24, Forgejo 12.0 or later. The default origin of the `base_url` and `api_root` [backend options](https://decapcms.org/docs/backends-overview/#backend-configuration) is set to `https://gitea.com` (public free service) instead of `https://try.gitea.io` (test instance).
 
@@ -800,27 +807,32 @@ You can also generate a personal access token (PAT) on GitHub or GitLab, and use
 
 Sveltia CMS provides a full [JSON schema](https://json-schema.org/) for the configuration file, so you can get autocomplete and validation in your favourite code editor while editing the site configuration. The schema is generated from the source and always up to date with the latest CMS version.
 
-If you use VS Code, you can enable it for the YAML configuration file by installing the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and adding the following to your project’s [VS Code settings file](https://code.visualstudio.com/docs/configure/settings#_settings-json-file) at `.vscode/settings.json`:
+If you use VS Code, you can enable it for the YAML configuration file by installing the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and adding the following line to the top of `config.yml`:
 
-```json
-{
-  "yaml.schemas": {
-    "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json": ["/static/admin/config.yml"]
-  }
-}
+```yaml
+# yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json
 ```
 
-If your configuration is in JSON format (see the [next section](#providing-a-json-configuration-file)), no extension is needed. Just add the following to the same VS Code settings file:
+If your configuration is in JSON format (see the [next section](#providing-a-json-configuration-file)), no extension is needed. Just add the following line to the top of `config.json`, within the curly braces:
 
 ```json
-{
-  "json.schemas": [
-    {
-      "fileMatch": ["/static/admin/config.json"],
-      "url": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json"
-    }
-  ]
-}
+"$schema": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json",
+```
+
+Alternatively, you can add the following to your project’s [VS Code settings file](https://code.visualstudio.com/docs/configure/settings#_settings-json-file) at `.vscode/settings.json`, within the outer curly braces:
+
+```jsonc
+// For YAML config file
+"yaml.schemas": {
+  "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json": ["/static/admin/config.yml"]
+},
+// For JSON config file
+"json.schemas": [
+  {
+    "fileMatch": ["/static/admin/config.json"],
+    "url": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json"
+  }
+],
 ```
 
 The configuration file location varies by framework and project structure, so adjust the path accordingly. For example, if you use Astro, the file is typically located in the `/public/admin/` directory.
@@ -1136,7 +1148,9 @@ Sveltia CMS comes with a handy translation API integration so that you can trans
 1. Select a translation service from the dropdown menu and paste your API key when prompted.
 1. The field(s) will be automatically translated.
 
-You can also provide your API keys in the Settings dialog.
+You can also provide your API keys in the Settings dialog or change the default translation service.
+
+If you don’t want some text to be translated, use the HTML [`translate`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/translate) attribute or [`notranslate`](https://developers.google.com/search/blog/2008/10/helping-you-break-language-barrier) class, e.g. `<div translate="no">...</div>` or `<span class="notranslate">...</span>`. For Anthropic and OpenAI, you can also use the `notranslate` comment to exclude specific parts of Markdown content from translation, e.g. `<!-- notranslate -->...<!-- /notranslate -->`.
 
 Note that the Translation button on the pane header only translates empty fields, while in-field Translation buttons override any filled text.
 
@@ -1725,7 +1739,7 @@ Due late 2025
   - [Entry pre-validation/normalization](https://github.com/sveltia/sveltia-cms/issues/395)[^248]
 - Accessibility audit
 - [Localization](https://github.com/sveltia/sveltia-cms/blob/main/src/lib/locales/README.md)
-- Developer documentation (implementation guide)
+- [Developer documentation](https://github.com/sveltia/sveltia-cms/issues/485) (implementation guide)
 - Marketing site
 - [Live demo site](https://github.com/sveltia/sveltia-cms/issues/1)