@sveltia/cms 0.8.5 → 0.9.0

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/). You can use it with your favourite static site generator like SvelteKit, Eleventy, Next.js and Hugo to manage content as static files in a Git repository. The free open source 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>
 
@@ -10,13 +10,13 @@ Sveltia CMS is a Git-based lightweight headless CMS under active development as
 
 ![Screenshot: All-New Asset Library; Full Internationalization Support with DeepL](docs/screenshot-4-20231124.webp)<br>
 
-![Screenshot: Easy Local Workflow; Single-Line Migration from Netlify/Decap CMS (depending on your current setup); Sveltia CMS](docs/screenshot-5-20231124.webp)<br>
+![Screenshot: Easy Local Workflow; Single-Line Migration from Netlify/Decap CMS (depending on your current setup); Sveltia CMS](docs/screenshot-5-20231127.webp)<br>
 
 ## Motivation
 
 Sveltia CMS was born in November 2022, when the progress of Netlify CMS was stalled for more than six months. [@kyoshino](https://github.com/kyoshino)’s clients wanted to replace their Netlify CMS instances without much effort, mainly to get better internationalization (i18n) support.
 
-To achieve radical improvements in UX, performance and i18n, it was decided to build an alternative from the ground up, while ensuring an easy migration path from the other. After proving the concept with a rapid [Svelte](https://svelte.dev/) prototype, development was accelerated to address their primary use cases. The new offering has since been released as open source software to encourage wider adoption.
+To achieve radical improvements in UX, performance and i18n, it was decided to build an alternative from the ground up, while ensuring an easy migration path from the other. After proving the concept with a rapid [Svelte](https://svelte.dev/) prototype, development was accelerated to address their primary use cases. The new offering has since been named Sveltia CMS and released as open source software to encourage wider adoption.
 
 Our goal is to make it a viable successor to Netlify CMS, expand the Git-based headless CMS market, empower small businesses and individuals who need a simple yet powerful CMS solution, and showcase the huge potential of the Svelte framework.
 
@@ -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
 
@@ -70,32 +71,34 @@ Here are some highlights mainly compared to Netlify/Decap CMS:
 - You can [disable non-default locale content](#disable-non-default-locale-content)[^15].
 - You can [use a random UUID for an entry slug](#use-a-random-id-for-an-entry-slug), which is a good option for locales that write in non-Latin characters[^12].
 - 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_folder` i18n structure[^21].
+- [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 performance overhead[^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 media 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](https://github.com/sveltia/sveltia-cms/blob/main/src/lib/locales/README.md)
+- Localization
 - Documentation
 - Marketing site
 - Demo site
 - Starter templates
+- Roles[^23]
 - Config editor[^10]
 - Mobile support[^18]
 
@@ -183,6 +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)
+
+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
 
@@ -215,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
 
@@ -295,6 +303,43 @@ 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/updated entry, as well as any other unpublished entries and assets, click the 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.
+
+Either way, 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:
+  - 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.
@@ -338,6 +383,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
@@ -364,13 +420,13 @@ Want to build a website with Sveltia CMS? Maintainer [@kyoshino](https://github.
 
 Sveltia CMS is still in early beta, so we do expect various problems. Please [report any bugs to us](https://github.com/sveltia/sveltia-cms/issues/new). Feel free to submit feature requests as well. Meanwhile, pull requests may not be accepted for the time being due to limited review resources. As we get closer to the 1.0 release, we’ll be welcoming [localizers](https://github.com/sveltia/sveltia-cms/blob/main/src/lib/locales/README.md).
 
-## Related Links
+## Related links
 
 - Introducing Sveltia CMS: a short technical presentation by [@kyoshino](https://github.com/kyoshino) during the _This Week in Svelte_ online meetup on March 31, 2023 — [recording](https://youtu.be/-YjLubiieYs?t=1660) & [slides](https://docs.google.com/presentation/d/1Wi4ty-1AwOp2-zy7LctmzCV4rrdYPfke9NGhO0DdRdM)
 
 ## Disclaimer
 
-This software is provided “as is” without any express or implied warranty. This product is not affiliated with or endorsed by Netlify, Decap CMS or any other integrated services. All product names, logos, and brands are the property of their respective owners.
+This software is provided “as is” without any express or implied warranty. We are not obligated to provide any support for the application. This product is not affiliated with or endorsed by Netlify, Decap CMS or any other integrated services. All product names, logos, and brands are the property of their respective owners.
 
 [^1]: [Netlify/Decap CMS #2557](https://github.com/decaporg/decap-cms/issues/2557)
 [^2]: [Netlify/Decap CMS #3267](https://github.com/decaporg/decap-cms/issues/3267)
@@ -382,10 +438,10 @@ This software is provided “as is” without any express or implied warranty. T
 [^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), [Netlify/Decap CMS #5596](https://github.com/decaporg/decap-cms/issues/5596) 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), [Netlify/Decap CMS #5920](https://github.com/decaporg/decap-cms/issues/5920), [Netlify/Decap CMS #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)
@@ -394,3 +450,6 @@ This software is provided “as is” without any express or implied warranty. T
 [^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)