@sveltia/cms 0.8.6 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # Sveltia CMS
 
-Sveltia CMS is a Git-based lightweight headless CMS under active development as a modern, quick replacement for [Netlify/Decap CMS](https://decapcms.org/). In some cases, migration is as easy as a single line of code change, although we’re still working on improving compatibility. The free, open source, UX-focused alternative to Netlify/Decap CMS is now in public beta — with more features to come.
+Sveltia CMS is a Git-based lightweight headless CMS under active development as a modern, quick replacement for [Netlify/Decap CMS](https://decapcms.org/). In some simple cases, migration is as easy as a single line of code change, although we’re still working on improving compatibility. The free, open source, UX-focused alternative to Netlify/Decap CMS is now in public beta — with more features to come.
 
 ![Screenshot: Git-based Headless CMS with Dark Mode](docs/screenshot-1-20231124.webp)<br>
 
@@ -44,6 +44,7 @@ Here are some highlights mainly compared to Netlify/Decap CMS:
 - Uses the GraphQL API for GitHub to quickly fetch content at once, so that entries and assets can be listed and searched instantly. This avoids the slowness and potential API rate limit violations caused by hundreds of requests with relation widgets[^14].
 - Saving entries and assets is also much faster thanks to the [GraphQL mutation](https://github.blog/changelog/2021-09-13-a-simpler-api-for-authoring-commits/).
 - Caches Git files locally to further speed up startup and reduce bandwidth.
+- You can [disable automatic deployments](#disable-automatic-deployments) by default or on demand to save costs and resources associated with CI/CD and to publish multiple changes at once[^24].
 
 ### Better productivity
 
@@ -72,30 +73,32 @@ Here are some highlights mainly compared to Netlify/Decap CMS:
 - Resolves the [limitations in the list and object widgets](https://decapcms.org/docs/beta-features/#i18n-support) so that changes made with these widgets will be duplicated between locales as expected when using the `i18n: duplicate` field configuration[^7].
 - [Entry-relative media folders](https://decapcms.org/docs/beta-features/#folder-collections-media-and-public-folder) can be used in conjunction with the `multiple_folders` i18n structure[^21].
 
-### Collection enhancements
+### Better collections
 
 - You can choose a [custom icon for each collection](#use-a-custom-icon-for-a-collection)[^3].
 - A [per-collection media folder](#use-a-custom-media-folder-for-a-collection) will appear next to the entries.
 - String values in YAML files can be quoted with the new `yaml_quote: true` option for a collection, mainly for framework compatibility[^9].
-- Assets stored in an entry-relative media folder are automatically deleted when the associated entry is deleted[^22].
+- You can set the maximum number of characters for an entry slug with the new `slug_length` collection option[^25].
 
-### Field enhancements
+### Better fields/widgets
 
+- Relation field options are displayed with no additional API requests[^14]. The `options_length` property is therefore ignored.
 - Required fields, not optional fields, are clearly marked for efficient data entry.
 - Provides a reimagined all-in-one asset selection dialog for file and image fields.
   - [Collection-specific assets](#use-a-custom-media-folder-for-a-collection) will be listed first for easy selection, while all assets can also be displayed in a separate tab[^19].
   - New assets can be uploaded by dragging & dropping them into the dialog[^20].
   - A file/image URL can also be entered in the dialog.
   - Integration with Pexels, Pixabay and Unsplash makes it easy to select and insert free stock photos[^8].
-- Optional object fields (`widget: object` with `required: false`) can be manually added or removed. If removed, the required subfields will no longer trigger validation errors[^16].
+- Optional object fields (`widget: object` with `required: false`) can be manually added or removed. If unadded or removed, the required subfields won’t trigger validation errors[^16].
 - You can revert changes to all fields or a specific field.
 
-### Asset management enhancements
+### Better asset management
 
 - A completely new Asset Library, built separately from the image selection dialog, makes it easy to manage all of your files, including images, videos and documents.
-- You can sort or filter assets by name or file type and view asset details, including size, dimensions, and a list of entries that use the selected asset.
-- You can upload multiple assets at once, including files in nested folders, by browsing or dragging & dropping them into the media library[^5].
-- You can navigate between the global media folder and per-collection media folders[^6].
+  - You can sort or filter assets by name or file type and view asset details, including size, dimensions, and a list of entries that use the selected asset.
+  - You can upload multiple assets at once, including files in nested folders, by browsing or dragging & dropping them into the library[^5].
+  - You can navigate between the global media folder and per-collection media folders[^6].
+- Assets stored in an entry-relative media folder are automatically deleted when the associated entry is deleted because these assets are not available for other entries[^22].
 
 ## Compatibility
 
@@ -154,6 +157,7 @@ While it’s not our goal to recreate all the features found in Netlify/Decap CM
 
 ### Other features
 
+- Netlify Identity Widget is not supported yet.
 - Comprehensive config validation is not implemented yet.
 - Auto-saving a draft entry is not implemented yet.
 - Downloading an asset in the media library is not implemented yet.
@@ -163,11 +167,12 @@ While it’s not our goal to recreate all the features found in Netlify/Decap CM
 
 - [Svelte 5](https://svelte.dev/blog/runes) migration
 - Further Netlify/Decap CMS compatibility, including Editorial Workflow
-- Localization
+- Localization other than Japanese
 - Documentation
 - Marketing site
 - Demo site
 - Starter templates
+- Roles[^23]
 - Config editor[^10]
 - Mobile support[^18]
 
@@ -183,9 +188,9 @@ Here are some starter kits for popular frameworks created by community members.
 
 - [Eleventy starter template](https://github.com/danurbanowicz/eleventy-sveltia-cms-starter) by [@danurbanowicz](https://github.com/danurbanowicz)
 - [Hugo module](https://github.com/privatemaker/headless-cms) by [@privatemaker](https://github.com/privatemaker)
-- [Astro starter template](https://github.com/majesticostudio/astro-sveltia-cms) by [@zanhk](https://github.com/zanhk)
+- Astro: [astro-sveltia-cms](https://github.com/majesticostudio/astro-sveltia-cms), [astro-starter](https://github.com/zankhq/astro-starter) and [astros](https://github.com/zankhq/astros) by [@zanhk](https://github.com/zanhk)
 
-Alternatively, you can also use one of the [Netlify/Decap CMS templates](https://decapcms.org/docs/start-with-a-template/) and make a quick migration to Sveltia CMS.
+Alternatively, you can probably use one of the [Netlify/Decap CMS templates](https://decapcms.org/docs/start-with-a-template/) and make a quick migration to Sveltia CMS.
 
 ### Migration
 
@@ -218,7 +223,7 @@ You can use Sveltia CMS with a local Git repository, like the [beta feature](htt
 1. Open the dev site at `http://localhost:[port]/` to check the rendered pages.
 1. Commit and push the changes if satisfied, or discard them if you’re just testing.
 
-Remember that the local repository support doesn’t do any Git operation. You have to pull, commit and push all changes manually with a Git client. Also, at this point, you have to reload the CMS to see the latest content after fetching remote updates (this will be unnecessary once browsers support the proposed `FileSystemObserver` API).
+Remember that the local repository support doesn’t do any Git operation. You have to fetch, pull, commit and push all changes manually with a Git client. Also, at this point, you have to reload the CMS to see the latest content after retrieving remote updates (this will be unnecessary once browsers support the proposed `FileSystemObserver` API).
 
 ### Use a custom icon for a collection
 
@@ -298,6 +303,45 @@ It’s simple — just specify `{{uuid}}` (full UUID v4), `{{uuid_short}}` (last
 +    slug: '{{uuid_short}}'
 ```
 
+### Disable automatic deployments
+
+You may already have a CI/CD tool set up on your Git repository to automatically deploy changes to production. Occasionally, you make a lot of changes to your content to quickly reach the CI/CD provider’s (free) build limits, or you just don’t want to see builds triggered for every single small change.
+
+With Sveltia CMS, you can disable automatic deployments by default and manually trigger deployments at your convenience. This is done by adding the `[skip ci]` prefix to commit messages, the convention supported by [GitHub](https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs), [GitLab](https://docs.gitlab.com/ee/ci/pipelines/#skip-a-pipeline), [CircleCI](https://circleci.com/docs/skip-build/#skip-jobs), [Travis CI](https://docs.travis-ci.com/user/customizing-the-build/#skipping-a-build), [Netlify](https://docs.netlify.com/site-deploys/manage-deploys/#skip-a-deploy), [Cloudflare Pages](https://developers.cloudflare.com/pages/platform/branch-build-controls/#skip-builds) and others. Here are the steps to use it:
+
+1. Add the new `automatic_deployments` property to your `backend` configuration with a value of `false`:
+   ```diff
+    backend:
+      name: github
+      repo: owner/repo
+      branch: main
+   +  automatic_deployments: false
+   ```
+1. Commit and deploy the change to the config file and reload the CMS.
+1. Now, whenever you save an entry or asset, `[skip ci]` is automatically added to each commit message. However, deletions are always committed without the prefix to avoid unexpected data retention on your site.
+1. If you want to deploy a new or updated entry, as well as any other unpublished entries and assets, click an arrow next to the Save button in the content editor, then select **Save and Publish**. This will trigger CI/CD by omitting `[skip ci]`.
+
+If you set `automatic_deployments` to `true`, the behaviour is reversed. CI/CD will be triggered by default, while you have an option to **Save without Publishing** that adds `[skip ci]` only to the associated commit.
+
+_Gotcha:_ Unpublished entries and assets are not drafts. Once committed to your repository, those changes can be deployed any time another commit is pushed without `[skip ci]`, or when a manual deployment is triggered.
+
+If the `automatic_deployments` property is defined, you can manually trigger a deployment by selecting **Publish Changes** under the Account button in the top right corner of the CMS. To use this feature:
+
+- GitHub Actions:
+  1. Without any configuration, Publish Changes will [trigger a `repository_dispatch` event](https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event) with the `sveltia-cms-publish` event type. Update your build workflow to receive this event:
+     ```diff
+      on:
+        push:
+          branches: [$default-branch]
+     +  repository_dispatch:
+     +    types: [sveltia-cms-publish]
+     ```
+- Other CI/CD providers:
+  1. Select Settings under the Account button in the top right corner of the CMS.
+  1. Select the Advanced tab.
+  1. Enter the deploy hook URL for your provider, e.g. [Netlify](https://docs.netlify.com/configure-builds/build-hooks/) or [Cloudflare Pages](https://developers.cloudflare.com/pages/platform/deploy-hooks/).
+  1. Configure the CSP if necessary. See below.
+
 ### Set up Content Security Policy
 
 If your site adopts Content Security Policy (CSP), use the following policy for Sveltia CMS, or some features may not work.
@@ -341,6 +385,17 @@ And combine the following policies depending on your Git backend and enabled int
   connect-src https://api.deepl.com;
   ```
 
+If you choose to [disable automatic deployments](#disable-automatic-deployments) and have configured a webhook URL, you may need to add the origin to the `connect-src` directive. For example,
+
+- Netlify:
+  ```csp
+  connect-src https://api.netlify.com;
+  ```
+- Cloudflare Pages
+  ```csp
+  connect-src https://api.cloudflare.com;
+  ```
+
 If you have image field(s) and expect that images will be inserted as URLs, you may want to allow any source using a wildcard instead of specifying individual origins:
 
 ```csp
@@ -385,10 +440,10 @@ This software is provided “as is” without any express or implied warranty. W
 [^8]: [Netlify/Decap CMS #2579](https://github.com/decaporg/decap-cms/issues/2579)
 [^9]: [Netlify/Decap CMS #3505](https://github.com/decaporg/decap-cms/issues/3505)
 [^10]: [Netlify/Decap CMS #341](https://github.com/decaporg/decap-cms/issues/341)
-[^11]: [Netlify/Decap CMS #1382](https://github.com/decaporg/decap-cms/issues/1382), [#5596](https://github.com/decaporg/decap-cms/issues/5596), [#5752](https://github.com/decaporg/decap-cms/issues/5752), [#6994](https://github.com/decaporg/decap-cms/issues/6994) and many more. We’ll be updating this list after reviewing their issue list.
+[^11]: [Netlify/Decap CMS #1382](https://github.com/decaporg/decap-cms/issues/1382), [#2370](https://github.com/decaporg/decap-cms/issues/2370), [#5596](https://github.com/decaporg/decap-cms/issues/5596), [#5752](https://github.com/decaporg/decap-cms/issues/5752), [#6325](https://github.com/decaporg/decap-cms/issues/6325), [#6994](https://github.com/decaporg/decap-cms/issues/6994) and more. We’ll be updating this list after reviewing their issue list.
 [^12]: [Netlify/Decap CMS #1975](https://github.com/decaporg/decap-cms/issues/1975)
-[^13]: [Netlify/Decap CMS #5112](https://github.com/decaporg/decap-cms/issues/5112)
-[^14]: [Netlify/Decap CMS #4635](https://github.com/decaporg/decap-cms/issues/4635), [\#5920](https://github.com/decaporg/decap-cms/issues/5920), [\#6410](https://github.com/decaporg/decap-cms/issues/6410)
+[^13]: [Netlify/Decap CMS #5112](https://github.com/decaporg/decap-cms/issues/5112), [#5653](https://github.com/decaporg/decap-cms/issues/5653)
+[^14]: [Netlify/Decap CMS #4635](https://github.com/decaporg/decap-cms/issues/4635), [#4738](https://github.com/decaporg/decap-cms/issues/4738), [#5920](https://github.com/decaporg/decap-cms/issues/5920), [#6410](https://github.com/decaporg/decap-cms/issues/6410)
 [^15]: [Netlify/Decap CMS #6932](https://github.com/decaporg/decap-cms/issues/6932)
 [^16]: [Netlify/Decap CMS #2103](https://github.com/decaporg/decap-cms/issues/2103)
 [^17]: [Netlify/Decap CMS #1333](https://github.com/decaporg/decap-cms/issues/1333)
@@ -397,3 +452,6 @@ This software is provided “as is” without any express or implied warranty. W
 [^20]: [Netlify/Decap CMS #4563](https://github.com/decaporg/decap-cms/issues/4563)
 [^21]: [Netlify/Decap CMS #4781](https://github.com/decaporg/decap-cms/issues/4781)
 [^22]: [Netlify/Decap CMS #6642](https://github.com/decaporg/decap-cms/issues/6642)
+[^23]: [Netlify/Decap CMS #2](https://github.com/decaporg/decap-cms/issues/2)
+[^24]: [Netlify/Decap CMS #6831](https://github.com/decaporg/decap-cms/issues/6831)
+[^25]: [Netlify/Decap CMS #6987](https://github.com/decaporg/decap-cms/issues/6987)