@sveltia/cms 0.46.5 → 0.47.1

package/README.md

@@ -1,8 +1,8 @@
 # Sveltia CMS
 
-Sveltia CMS is a Git-based lightweight headless CMS under active development as a modern, quick replacement for Netlify CMS and Decap CMS. In some simple cases, migration is as easy as a single line of code change, although we are still working on improving compatibility.
+Sveltia CMS is a Git-based lightweight headless CMS under active development as a modern, powerful, quick replacement for Netlify CMS and Decap CMS. In some simple cases, migration is as easy as a single line of code change, although we are still working on improving compatibility.
 
-The free, open source alternative to Netlify/Decap CMS is now in public beta, turbocharged with great UX, performance, i18n support and many more enhancements.
+The free, open source alternative to Netlify/Decap CMS is now in public beta, turbocharged with great UX, performance, i18n support and so many more enhancements.
 
 ![Screenshot: Open Source Git-based Headless CMS](https://raw.githubusercontent.com/sveltia/sveltia-cms/main/docs/screenshot-1-20240507.webp)<br>
 
@@ -40,6 +40,7 @@ The free, open source alternative to Netlify/Decap CMS is now in public beta, tu
 - [Compatibility](#compatibility)
   - [Features not to be implemented](#features-not-to-be-implemented)
   - [Current limitations](#current-limitations)
+  - [Other notes](#other-notes)
 - [Getting started](#getting-started)
   - [New users](#new-users)
   - [Migration](#migration)
@@ -96,7 +97,7 @@ While Sveltia CMS is specifically designed to replace legacy Netlify CMS instanc
 - Emerging as the leading open source offering in the Git-based CMS market
 - Empowering small businesses and individuals who need a simple, free, yet powerful CMS solution
 - Extending its capabilities as digital asset management (DAM) software
-- Showcasing the vast potential of the Svelte framework
+- Showcasing the power of Svelte and UX engineering
 
 ## Development status
 
@@ -110,7 +111,7 @@ While we fix reported bugs as quickly as possible, usually within 24 hours, our
   - Target: 150 issues by GA, 250 or all relevant and fixable issues in a future release
   - Note: Issues include both feature requests and bug reports; we also track their [stale issues](https://github.com/decaporg/decap-cms/issues?q=is%3Aissue+%22Closing+as+stale%22) and [discussions](https://github.com/decaporg/decap-cms/discussions)
   - [Let us know](https://github.com/sveltia/sveltia-cms/issues/new) if you have any specific issues you’d like to see solved!
-- Responding to feedback from clients and regular users
+- Responding to feedback from [@kyoshino](https://github.com/kyoshino)’s clients and regular users
 - Implementing our own enhancement ideas for every part of the product
 
 ![140 Netlify/Decap CMS Issues Solved in Sveltia CMS](https://raw.githubusercontent.com/sveltia/sveltia-cms/main/docs/headline-1-20241104.webp)<br>
@@ -192,7 +193,7 @@ We are working hard to create a **significantly better alternative to Netlify CM
 - Developers can [disable automatic deployments](#disabling-automatic-deployments) by default or on demand to save costs and resources associated with CI/CD and to publish multiple changes at once[^24].
 - The GitLab backend support comes with background [service status](https://status.gitlab.com/) checking, just like GitHub.
 - Service status checks are performed frequently and an incident notification is displayed prominently.
-- Users can quickly open the source file of an entry or asset in your repository using View on GitHub (or GitLab) under the 3-dot menu.
+- Users can quickly open the source file of an entry or asset in your repository using View on GitHub (or GitLab) under the 3-dot menu when Developer Mode is enabled.
 - We provide [our own OAuth client](https://github.com/sveltia/sveltia-cms-auth) for GitHub and GitLab.
 - Users won’t get a 404 Not Found error when you sign in to the GitLab backend[^115].
 - Features the all-new local backend that boosts DX. See the [productivity section](#better-productivity) above.
@@ -200,7 +201,7 @@ We are working hard to create a **significantly better alternative to Netlify CM
 
 ### Better i18n support
 
-Sveltia CMS has been built with a multilingual architecture from the very beginning. You can expect first-class internationalization (i18n) support, as it’s required by clients of maintainer [@kyoshino](https://github.com/kyoshino), who himself was a long-time Japanese localizer for Mozilla and currently lives in a [multicultural city](https://en.wikipedia.org/wiki/Toronto) where 150+ languages are spoken.
+Sveltia CMS has been built with a multilingual architecture from the very beginning. You can expect best-in-class internationalization (i18n) support, as it’s required by clients of maintainer [@kyoshino](https://github.com/kyoshino), who himself was a long-time Japanese localizer for Mozilla and currently lives in a [multicultural city](https://en.wikipedia.org/wiki/Toronto) where 150+ languages are spoken.
 
 - Configuration
   - The [i18n limitations](https://decapcms.org/docs/i18n/#limitations) in Netlify/Decap CMS do not apply to Sveltia CMS:
@@ -237,22 +238,27 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
     - `thumbnail`: Specify the field name for a thumbnail displayed on the entry list[^130]. A nested field can be specified using dot notation, e.g. `images.0.src`. If undefined, the `name` of the first image field is used.
   - Developers can use nested fields (dot notation) in the `path` option for a folder collection, e.g. `{{fields.state.name}}/{{slug}}`[^62].
   - Developers can use Markdown in the `description` collection option[^79]. Bold, italic, strikethrough, code and links are allowed.
+  - The collection `folder` can be an empty string (or `.` or `/`) if you want to store entries in the root folder. This supports a typical VitePress setup.
+  - A folder collection `filter` supports multiple possible values by using an array for the `value`[^151].
+  - Multiple [summary string transformations](https://decapcms.org/docs/summary-strings/) can be chained like `{{title | upper | truncate(20)}}`.
 - Entry slugs
   - It’s possible to [use a random UUID for an entry slug](#using-a-random-id-for-an-entry-slug).
   - Slug generation is fail-safe: If a slug cannot be determined from entry content, part of a random UUID is used instead of throwing an error or filling in with arbitrary string field values[^133].
-  - Entry slug template tags support [filter transformations](https://decapcms.org/docs/summary-strings/) just like summary string template tags[^29].
+  - If a collection only has the Markdown `body` field, an entry slug will be generated from a header in the `body`, if exists. This supports a typical VitePress setup.
+  - Entry slug template tags support [transformations](https://decapcms.org/docs/summary-strings/) just like summary string template tags[^29].
   - Single quotes (apostrophes) in a slug will be replaced with `sanitize_replacement` (default: hyphen) rather than being removed[^52].
   - Developers can set the maximum number of characters for an entry slug with the new `slug_length` collection option to avoid deployment errors with Netlify or other platforms[^25].
   - Setting the collection `path` doesn’t affect the entry slugs stored with the Relation widget[^137].
   - Entry slugs are [localizable](#localizing-entry-slugs)[^80].
 - Entry listing
   - The collection list displays the number of items in each collection.
-  - A folder collection filter with a boolean value works as expected[^93].
+  - A folder collection `filter` with a boolean value works as expected[^93].
+  - Sorting entries by a DateTime field works as expected[^110].
   - Entry grouping and sorting can work together. For example, it’s possible to group by year and then sort by year if configured properly.
-  - Hugo’s special `_index.md` files are ignored in folder collections unless the `path` option is configured to end with `_index` and the `extension` is `md`[^120]. You can still manage these files as part of a file collection if necessary.
+  - Hugo’s special `_index.md` files, including localized ones like `_index.en.md`, are ignored in folder collections unless the `path` option is configured to end with `_index` and the `extension` is `md`[^120]. You can still manage these files as part of a file collection if necessary.
+  - A console error won’t be thrown when a collection doesn’t have the `title` field[^152]. In that case, an entry summary will be generated from a header in the Markdown `body` field, if exists, or from the entry slug, so the summary will never be an empty. This supports a typical VitePress setup.
   - If there was an error while parsing an entry file, such as duplicate front matter keys, it won’t show up as a blank entry, and a clear error message will be displayed in the browser console[^121].
-  - Sorting entries by a DateTime field works as expected[^110].
-  - The entry list supports basic Markdown formatting syntax in the titles: bold, italic and code are allowed. HTML character references (entities) are also parsed properly[^69].
+  - In an entry summary, basic Markdown syntax used in the title, including bold, italic and code, are parsed as Markdown. HTML character references (entities) are also parsed properly[^69].
   - If you update an entry field that appears in the collection’s `summary`, such as `title`, the entry list displays an updated summary after you save the entry.
   - If entries don’t have an Image field for thumbnails, the entry list will only be displayed in list view, because it doesn’t make sense to show grid view[^143].
   - Assets stored in a [collection media folder](#using-a-custom-media-folder-for-a-collection) can be displayed next to the entries.
@@ -351,6 +357,7 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
   - If the `public_folder` contains `{{slug}}` and you’ve edited a slug field (e.g. `title`) of a new entry after uploading an asset, the updated slug will be used in the saved asset path[^140]. Other dynamic template tags such as `{{filename}}` will also be populated as expected[^141].
 - List and Object
   - The `summary` is displayed correctly when it refers to a Relation field[^36] or a simple List field.
+  - The `summary` template tags support [transformations](https://decapcms.org/docs/summary-strings/), e.g. `{{fields.date | date('YYYY-MM-DD')}}`.
 - Markdown, String and Text
   - A required field containing only spaces or line breaks will result in a validation error, as if no characters were entered.
 - Relation and Select
@@ -384,6 +391,7 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
   - Upload multiple assets at once, including files in nested folders, by browsing or dragging and dropping them into the library[^5].
   - Sort or filter assets by name or file type.
   - View asset details, including size, dimensions, commit author/date and a list of entries that use the selected asset.
+- The global `media_folder` can be an empty string (or `.` or `/`) if you want to store assets in the root folder.
 - PDF documents are displayed with a thumbnail image in both the Asset Library and the Select File dialog, making it easier to find the file you’re looking for[^38].
 - Assets stored in an entry-relative media folder are displayed in the Asset Library[^142].
 - These entry-relative assets are automatically deleted when the associated entry is deleted because these are not available for other entries[^22]. When you’re [working with a local repository](#working-with-a-local-git-repository), the empty enclosing folder is also deleted.
@@ -427,32 +435,34 @@ These limitations are expected to be resolved before or shortly after GA:
 
 | Feature | Status in Sveltia CMS |
 | --- | --- |
-| Backends | The Test backend needed for our demo site is not yet added. We’ll see if Azure DevOps can also be supported. |
+| Backends | The [Test](https://decapcms.org/docs/test-backend/) backend needed for our demo site is not yet added. We’ll see if [Azure DevOps](https://decapcms.org/docs/azure-backend/) can also be supported. |
 | Configuration | Comprehensive config validation is not yet implemented. |
 | Localization | The application UI is only available in English and Japanese at this time. |
-| Media Libraries | Cloudinary and Uploadcare are not yet supported. |
-| Workflow | Editorial Workflow and Open Authoring are not yet supported and will be implemented after the 1.0 release. |
-| Collections | Nested Collections are not yet supported and will be implemented after the 1.0 release. |
-| Widgets | Custom widgets are not yet supported. See the table below for other limitations. |
-| Customizations | Custom previews and event subscriptions are not yet supported. |
+| Media Libraries | [Cloudinary](https://decapcms.org/docs/cloudinary/) and [Uploadcare](https://decapcms.org/docs/uploadcare/) are not yet supported. |
+| Workflow | [Editorial Workflow](https://decapcms.org/docs/editorial-workflows/) and [Open Authoring](https://decapcms.org/docs/open-authoring/) are not yet supported and will be implemented after the 1.0 release. |
+| Collections | [Nested Collections](https://decapcms.org/docs/collection-nested/) (beta) are not yet supported and will be implemented after the 1.0 release. |
+| Widgets | [Custom widgets](https://decapcms.org/docs/custom-widgets/) are not yet supported. See the table below for other limitations. |
+| Customizations | [Custom previews](https://decapcms.org/docs/customization/) and [event subscriptions](https://decapcms.org/docs/registering-events/) are not yet supported. |
 
 | Widget | Status in Sveltia CMS |
 | --- | --- |
-| Code | Not yet supported. |
-| DateTime | The `date_format` and `time_format` options with Moment.js tokens are not yet supported. Note that [Decap CMS 3.1.1](https://github.com/decaporg/decap-cms/releases/tag/decap-cms%403.1.1) replaced Moment.js with [Day.js](https://day.js.org/), and [Decap CMS 3.3.0](https://github.com/decaporg/decap-cms/releases/tag/decap-cms%403.3.0) made other changes to the widget behaviour; we’ll follow these changes where it makes sense. |
-| File/Image | Field-specific media folders and media library options are not yet supported other than `media_library.config.max_file_size` for the default media library. |
-| Map | Not yet supported. |
-| Markdown | Editor components, including built-in `image` and `code-block` as well as custom components, are not yet supported. |
+| [Code](https://decapcms.org/docs/widgets/#code) | Not yet supported. |
+| [DateTime](https://decapcms.org/docs/widgets/#datetime) | The `date_format` and `time_format` options with Moment.js tokens are not yet supported. Note that [Decap CMS 3.1.1](https://github.com/decaporg/decap-cms/releases/tag/decap-cms%403.1.1) replaced Moment.js with [Day.js](https://day.js.org/), and [Decap CMS 3.3.0](https://github.com/decaporg/decap-cms/releases/tag/decap-cms%403.3.0) made other changes to the widget behaviour; we’ll follow these changes where it makes sense. |
+| [File](https://decapcms.org/docs/widgets/#file)/[Image](https://decapcms.org/docs/widgets/#image) | Field-specific media folders (beta) and media library options are not yet supported other than `media_library.config.max_file_size` for the default media library. |
+| [Map](https://decapcms.org/docs/widgets/#map) | Not yet supported. |
+| [Markdown](https://decapcms.org/docs/widgets/#markdown) | Editor components, including built-in `image` and `code-block` as well as custom components, are not yet supported. |
 
-We also plan to provide partial compatibility with new features added to Static CMS, such as the [KeyValue widget](https://staticjscms.netlify.app/docs/widget-keyvalue).
+### Other notes
 
-Found a compatibility issue or other missing feature? Let us know by [filing an issue](https://github.com/sveltia/sveltia-cms/issues/new).
+- The GitLab backend requires GitLab 16.3 or later.
+- We plan to provide partial compatibility with now-discontinued Static CMS, such as the [KeyValue widget](https://staticjscms.netlify.app/docs/widget-keyvalue).
+- Found a compatibility issue or other missing feature? Let us know by [filing an issue](https://github.com/sveltia/sveltia-cms/issues/new).
 
 ## Getting started
 
 ### New users
 
-Currently, Sveltia CMS is primarily intended for existing Netlify/Decap CMS users. If you don’t have it yet, follow [their documentation](https://decapcms.org/docs/basic-steps/) to add it to your site and create a configuration file first. Then migrate to Sveltia CMS as described below.
+Currently, Sveltia CMS is primarily intended for existing Netlify/Decap CMS users. If you don’t have it yet, follow [their documentation](https://decapcms.org/docs/basic-steps/) to add it to your site and create a configuration file first. Make sure you choose the [GitHub](https://decapcms.org/docs/github-backend/) or [GitLab](https://decapcms.org/docs/gitlab-backend/) backend (and ignore the Choosing a Backend page). Then migrate to Sveltia CMS as described below.
 
 As the product evolves, we’ll implement a built-in configuration editor and provide comprehensive documentation to make it easier for everyone to get started with Sveltia CMS.
 
@@ -467,7 +477,7 @@ Alternatively, you can probably use one of the [Netlify/Decap CMS templates](htt
 
 ### Migration
 
-Have a look at the [compatibility info](#compatibility) above first. If you’re already using Netlify/Decap CMS with the GitHub or GitLab backend and don’t have any custom widget, custom preview or plugin, migrating to Sveltia CMS is super easy — it works as a drop-in replacement. Edit `/admin/index.html` to replace the CMS `<script>` tag, and push the change to your repository. Your new `<script>` tag is:
+Have a look at the [compatibility info](#compatibility) above first. If you’re already using Netlify/Decap CMS with the GitHub or GitLab backend and don’t have any unsupported features like custom widgets or nested collections, migrating to Sveltia CMS is super easy — it works as a drop-in replacement. Edit `/admin/index.html` to replace the CMS `<script>` tag, and push the change to your repository. Your new `<script>` tag is:
 
 ```html
 <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
@@ -493,7 +503,7 @@ That said, we strongly recommend testing your new Sveltia CMS instance first on
 
 #### Migrating from Git Gateway backend
 
-Sveltia CMS does not support the Git Gateway backend due to performance limitations. If you don’t care about user management with Netlify Identity, you can use the [GitHub backend](https://decapcms.org/docs/github-backend/) or [GitLab backend](https://decapcms.org/docs/gitlab-backend/) instead. Make sure **you install an OAuth client** on GitHub or GitLab in addition to updating your configuration file. As noted in the document, Netlify is still able to facilitate the auth flow.
+Sveltia CMS does not support the Git Gateway backend due to performance limitations. If you don’t care about user management with Netlify Identity, you can use the [GitHub](https://decapcms.org/docs/github-backend/) or [GitLab](https://decapcms.org/docs/gitlab-backend/) backend instead. Make sure **you install an OAuth client** on GitHub or GitLab in addition to updating your configuration file. As noted in the document, Netlify is still able to facilitate the auth flow.
 
 To allow multiple users to edit content, simply invite people to your GitHub repository with the write role assigned.
 
@@ -537,7 +547,7 @@ If you get an “Authentication Aborted” error when trying to sign in to GitHu
 
 ### Working with a local Git repository
 
-Sveltia CMS has simplified the local repository workflow by removing the need for additional configuration (the `local_backend` property) and a proxy server, thanks to the [File System Access API](https://developer.chrome.com/articles/file-system-access/) available in [some modern browsers](https://developer.mozilla.org/en-US/docs/web/api/window/showopenfilepicker#browser_compatibility).
+Sveltia CMS has simplified the local repository workflow by removing the need for additional configuration (the `local_backend` property) and a proxy server (`netlify-cms-proxy-server` or `decap-server`), thanks to the [File System Access API](https://developer.chrome.com/articles/file-system-access/) available in [some modern browsers](https://developer.mozilla.org/en-US/docs/web/api/window/showopenfilepicker#browser_compatibility).
 
 Basically there are only two differences from Netlify/Decap CMS: you don’t need to run the proxy server, and you need to select your project folder in the browser instead. Here are the detailed steps:
 
@@ -561,7 +571,7 @@ Keep in mind that, as with Netlify/Decap CMS, the local repository support in Sv
 
 Also, at this point, you have to reload the CMS to see the latest content after retrieving remote updates. This manual work will hopefully be unnecessary once the proposed `FileSystemObserver` API, which is being [implemented in Chromium](https://issues.chromium.org/issues/40105284) behind a flag, becomes available.
 
-If you have migrated from Netlify/Decap CMS and are happy with the local workflow of Sveltia CMS, you can remove the `local_backend` property from your configuration and uninstall the proxy server (`netlify-cms-proxy-server` or `decap-server`). If you have configured a custom port number with the `.env` file, you can remove it as well.
+If you have migrated from Netlify/Decap CMS and are happy with the local workflow of Sveltia CMS, you can remove the `local_backend` property from your configuration and uninstall the proxy server. If you have configured a custom port number with the `.env` file, you can remove it as well.
 
 ### Enabling local development in Brave
 
@@ -743,7 +753,7 @@ It’s simple — just specify `{{uuid}}` (full UUID v4), `{{uuid_short}}` (last
 
 ### Editing data files with a top-level list
 
-Sveltia CMS allows you to edit and save a list at the top-level of a data file, without a field name. All you need to do is create a single List field with the new `root` option set to `true`. The configuration below reproduces a [Jekyll data file example](https://jekyllrb.com/docs/datafiles/#example-list-of-members):
+Sveltia CMS allows you to edit and save a list at the top-level of a data file, without a field name. All you need to do is create a single List field with the new `root` option set to `true`. The configuration below reproduces [this Jekyll data file example](https://jekyllrb.com/docs/datafiles/#example-list-of-members):
 
 ```yaml
 collections:
@@ -1252,3 +1262,7 @@ This software is provided “as is” without any express or implied warranty. W
 [^149]: Netlify/Decap CMS [#13](https://github.com/decaporg/decap-cms/issues/13) — The issue appears to have been closed without a fix being available.
 
 [^150]: Netlify/Decap CMS [#7319](https://github.com/decaporg/decap-cms/issues/7319)
+
+[^151]: Netlify/Decap CMS [#7328](https://github.com/decaporg/decap-cms/issues/7328)
+
+[^152]: Netlify/Decap CMS [#2491](https://github.com/decaporg/decap-cms/issues/2491)