@sveltia/cms 0.82.0 → 0.83.0

package/README.md

@@ -10,7 +10,7 @@ The free, open source alternative/successor to Netlify/Decap CMS is now in publi
 
 ![Stock photo integration: Pexels, Pixabay, Unsplash](https://raw.githubusercontent.com/sveltia/sveltia-cms/main/docs/screenshot-3.webp?20250405)<br>
 
-![Full-fledged Asset Library; first-class internationalization support; translation API integration](https://raw.githubusercontent.com/sveltia/sveltia-cms/main/docs/screenshot-4.webp?20250405)<br>
+![Full-fledged Asset Library; first-class internationalization support; translation API integration](https://raw.githubusercontent.com/sveltia/sveltia-cms/main/docs/screenshot-4.webp?20250625)<br>
 
 ![Built-in image optimizer for WebP and SVG; mobile & tablet support](https://raw.githubusercontent.com/sveltia/sveltia-cms/main/docs/screenshot-5.webp?20250409)<br>
 
@@ -67,6 +67,7 @@ The free, open source alternative/successor to Netlify/Decap CMS is now in publi
   - [Using a custom media folder for a collection](#using-a-custom-media-folder-for-a-collection)
   - [Specifying default sort field and direction](#specifying-default-sort-field-and-direction)
   - [Including Hugo’s special index file in a folder collection](#including-hugos-special-index-file-in-a-folder-collection)
+  - [Using singletons](#using-singletons)
   - [Using keyboard shortcuts](#using-keyboard-shortcuts)
   - [Translating entry fields with one click](#translating-entry-fields-with-one-click)
   - [Localizing entry slugs](#localizing-entry-slugs)
@@ -128,9 +129,8 @@ Sveltia CMS is currently in **beta** and version 1.0 (GA) is expected to ship in
 While we fix reported bugs as quickly as possible, usually within 24 hours, our overall progress may be slower than you think. The thing is, it’s not just a personal project of [@kyoshino](https://github.com/kyoshino), but also a complicated system involving various kinds of activities that require considerable effort:
 
 - Ensuring substantial [compatibility with Netlify/Decap CMS](#compatibility)
-- Providing partial [compatibility with Static CMS](#compatibility-with-static-cms)
 - Tackling as many [Netlify/Decap CMS issues](https://github.com/decaporg/decap-cms/issues) as possible
-  - So far, 225+ issues, or 455+ if including duplicates, have been effectively solved in Sveltia CMS
+  - So far, 225+ issues, or 465+ if including duplicates, have been effectively solved in Sveltia CMS (Yes, you read it right)
   - Target:
     - 200 issues, or 400 if including duplicates, by GA — We did it! 🎉
     - 400 issues, or 800 if including duplicates, in the future 💪
@@ -193,7 +193,7 @@ Note: This lengthy section compares Sveltia CMS with both Netlify CMS and Decap
   - Click once (the Save button) instead of twice (Publish > Publish now) to save an entry. Or just hit the `Ctrl+S` (Windows/Linux) or `Command+S` (macOS) key to save your time.
   - The editor closes automatically when an entry is saved. This behaviour can be changed in the application settings.
 - Uploading files can be done with drag and drop.[^20]
-- Users can upload multiple files at once to the Asset Library.[^5]
+- Users can upload multiple files at once to the Asset Library.
 - Users can delete multiple entries and assets at once.
 - Instant full-text search with results sorted by relevance helps you find entries faster.
 - Some [keyboard shortcuts](#using-keyboard-shortcuts) are available for faster editing.
@@ -274,8 +274,8 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
   - Users can easily switch between locales while editing by clicking a button instead of a dropdown list when there are less than 5 locales.
   - Language labels appear in human-readable display names instead of ISO 639 language codes because it’s not easy for everyone to recognize `DE` as German, `NL` as Dutch, `ZH` as Chinese, and so on.
 - Content editing
-  - [Integrates Cloud Translation API](#translating-entry-fields-with-one-click) to allow translation of text fields from another locale with one click.
-    - Earlier versions of Sveltia CMS included DeepL integration, but it’s disabled for now [due to API limitations](https://github.com/sveltia/sveltia-cms/issues/437).
+  - [Integrates a translation service](#translating-entry-fields-with-one-click) to allow translation of text fields from another locale with one click.
+    - Earlier versions of Sveltia CMS included DeepL integration, but it’s disabled for now [due to an API limitation](https://github.com/sveltia/sveltia-cms/issues/437).
     - More translation services will be added in the future.
   - The Content Editor supports [RTL scripts](https://en.wikipedia.org/wiki/Right-to-left_script) such as Arabic, Hebrew and Persian.[^146]
   - It’s possible to [disable non-default locale content](#disabling-non-default-locale-content).[^15]
@@ -294,6 +294,7 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
 - Configuration
   - Provides some new options, including:
     - `icon`: [Choose a custom icon for each collection](#using-a-custom-icon-for-a-collection).[^3]
+      - The option can also be used for individual files within a file collection. The specified icon will then appear in the file list.
     - `thumbnail`: Specify the field name for a thumbnail displayed on the entry list, like `thumbnail: featuredImage`.[^130]
       - A nested field can be specified using dot notation, e.g. `heroImage.src`.
       - A wildcard in the field name is also supported, e.g. `images.*.src`.
@@ -315,6 +316,7 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
     - The `date` transformation supports the time zone argument. The only available value is `utc`, which converts a date to UTC. This is useful if the specified DateTime field is local, but you want to force UTC in the entry slug, e.g. `{{date | date('YYYYMMDD-HHmm', 'utc')}}`. ([Discussion](https://github.com/sveltia/sveltia-cms/issues/278#issuecomment-2565313420))
     - The `date` transformation returns an empty string if an invalid date is given.[^176]
     - Multiple transformations can be chained like `{{title | upper | truncate(20)}}`.
+  - Sveltia CMS supports [singletons](#using-singletons), a simple form of a file collection.[^233]
   - The collection `label` defaults to the `name` value according to the [Decap CMS document](https://decapcms.org/docs/configuration-options/#collections), while Netlify/Decap CMS actually throws a configuration error if the `label` option is omitted.
   - Nested fields (dot notation) can be used in the `path` option for a folder collection, e.g. `{{fields.state.name}}/{{slug}}`.[^62]
   - Markdown is supported in the `description` collection option.[^79] Bold, italic, strikethrough, code and links are allowed.
@@ -410,6 +412,7 @@ Note: The Date widget has been deprecated in Netlify CMS and removed from both D
 - DateTime
   - A DateTime field doesn’t trigger a change in the content draft status when you’ve just started editing a new entry.[^90]
   - User’s local time is not saved in UTC unless the `picker_utc` option is `true`.[^150]
+  - The widget doesn’t throw a `RangeError` for formatting days of the month.[^250]
 - Hidden
   - The `default` value supports the following template tags:
     - `{{locale}}`: The current locale code.[^101]
@@ -518,7 +521,7 @@ Note: The Date widget has been deprecated in Netlify CMS and removed from both D
   - Replace existing assets.
   - Download one or more selected assets at once.
   - Delete one or more selected assets at once.
-  - Upload multiple assets at once, including files in nested folders, by browsing or dragging and dropping them into the library.[^5]
+  - Upload multiple assets at once, including files in nested folders, by browsing or dragging and dropping them into the library.
   - 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.
 - Enhancements to media libraries:
@@ -530,6 +533,7 @@ Note: The Date widget has been deprecated in Netlify CMS and removed from both D
   - Other integrations
     - Integrates stock photo providers, including Pexels, Pixabay and Unsplash.[^8] Developers can [disable them](#disabling-stock-assets) if needed.
     - More integration options, including Amazon S3 and Cloudflare R2/Images/Stream, would be added in the future.
+- Assets stored in the subfolders of `media_folder` are scanned recursively and displayed in the Asset Library.[^249]
 - 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]
@@ -608,7 +612,7 @@ Found a compatibility issue or other missing feature? [Let us know](https://gith
 
 ### 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. This README will be updated as our development progresses.
+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.
 
 - Configuration options
   - Static CMS made [some breaking changes](https://staticjscms.netlify.app/docs/decap-migration-guide) to view filters/groups, List widget, etc. while Sveltia CMS follows Netlify/Decap CMS, so you should review your configuration carefully.
@@ -891,6 +895,45 @@ collections:
 
 Note that the special index file is placed right under the `folder`, regardless of the collection’s [`path` option](https://decapcms.org/docs/collection-folder/#folder-collections-path). For example, if the `path` is `{{year}}/{{slug}}`, a regular entry would be saved as `content/posts/2025/title.md`, but the index file remains at `content/posts/_index.md`.
 
+### Using singletons
+
+The singleton collection is an unnamed, non-nested variant of a [file collection](https://decapcms.org/docs/collection-file/) that can be used to manage static data files. Singleton files appear in the content library’s sidebar under the “Files” group, and users can open the Content Editor directly without navigating to a file list.
+
+To create this special file collection, add the new `singletons` option, along with an array of file definitions, to the root level of your site configuration:
+
+```yaml
+collections:
+  # Conventional file collection
+  - name: pages
+    label: Pages
+    files:
+      - name: home
+        label: Home Page
+        file: content/home.yaml
+        ...
+      - name: about
+        label: Site Settings
+        file: content/settings.yaml
+        ...
+
+# Singleton collection
+singletons:
+  - name: home
+    label: Home Page
+    file: content/home.yaml
+    icon: home # You can specify an icon
+    ...
+  - name: divider-1
+    divider: true # You can also add dividers
+  - name: about
+    label: Site Settings
+    file: content/settings.yaml
+    icon: settings
+    ...
+```
+
+If you want to reference a singleton file with a Relation field, use `_singletons` as the `collection` name.
+
 ### Using keyboard shortcuts
 
 - View the Content Library: `Alt+1`
@@ -908,11 +951,11 @@ Sveltia CMS comes with a handy Google Cloud Translation API integration so that
 
 1. Update your configuration file to enable the [i18n support](https://decapcms.org/docs/i18n/) with multiple locales.
 1. Sign in or sign up for [Google Cloud](https://cloud.google.com/) and create a new project.
-1. Enable [Cloud Translation API](https://console.cloud.google.com/apis/library/translate.googleapis.com).
-1. Create a [new API key](https://console.cloud.google.com/apis/credentials) and copy it.
+1. Enable the [Cloud Translation API](https://console.cloud.google.com/apis/library/translate.googleapis.com). It’s free up to 500,000 characters per month.
+1. Create a [new API key](https://console.cloud.google.com/apis/api/translate.googleapis.com/credentials) and copy it.
 1. Open an entry in Sveltia CMS.
 1. Click on the Translation button on the pane header or each field, right next to the 3-dot menu.
-1. Paste your key when prompted.
+1. Paste your API key when prompted.
 1. The field(s) will be automatically translated.
 
 Note that the Translation button on the pane header only translates empty fields, while in-field Translation buttons override any filled text.
@@ -1284,7 +1327,7 @@ Then, add the following origins depending on your Git backend and enabled integr
     ```
     https://images.unsplash.com https://api.unsplash.com
     ```
-- Google Translate:
+- Google Cloud Translation:
   - `connect-src`
     ```
     https://translation.googleapis.com
@@ -1345,23 +1388,34 @@ See [Contributing to Sveltia CMS](https://github.com/sveltia/sveltia-cms/blob/ma
 Due Q4 2025
 
 - Enhanced [compatibility with Netlify/Decap CMS](#current-limitations)
-- Tackling some more Netlify/Decap CMS issues
+- Tackling some more Netlify/Decap CMS issues:
+  - [Directory navigation in the asset library](https://github.com/sveltia/sveltia-cms/issues/420)[^240] (#5 top-voted feature of Netlify/Decap CMS)
+  - [Multiple file selection with the File and Image widgets](https://github.com/sveltia/sveltia-cms/issues/10)[^239] (#14)
+  - [Git LFS support for GitHub backend](https://github.com/sveltia/sveltia-cms/discussions/353)[^244] (#26)
+  - Advanced Relation fields[^242], including cascade updates/deletes[^243] and [reverse reference lists](https://github.com/sveltia/sveltia-cms/discussions/416)
+  - Cloudinary and Uploadcare issues, including existing file selection[^247]
+  - [Automatic file renaming with templates](https://github.com/sveltia/sveltia-cms/issues/422)[^241]
+  - [RTL localization support](https://github.com/sveltia/sveltia-cms/issues/385)[^245]
+  - Thorough site config validation[^246]
+  - [Entry pre-validation/normalization](https://github.com/sveltia/sveltia-cms/issues/395)[^248]
+  - and a few more bugs
 - Accessibility audit
 - [Localization](https://github.com/sveltia/sveltia-cms/blob/main/src/lib/locales/README.md)
 - Developer documentation (implementation guide)
 - Marketing site
-- Live demo site
+- [Live demo site](https://github.com/sveltia/sveltia-cms/issues/1)
 
 ### v2.0
 
-- Implementing [some deferred Netlify/Decap CMS features](#current-limitations)
-- Tackling even more Netlify/Decap CMS issues
+- Implementing [a few deferred Netlify/Decap CMS features](#current-limitations):
+  - [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)
 - End-user documentation
-- Contributor documentation
 
 ### Future
 
-- Tackling many of the remaining Netlify/Decap CMS issues, including MDX support,[^122] manual entry sorting,[^125] config editor,[^10] singletons,[^233] and other [top-voted features](https://github.com/decaporg/decap-cms/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) (some of them may be included in v2.0)
+- Tackling many of the remaining Netlify/Decap CMS issues, including MDX support,[^122] [manual entry sorting](https://github.com/sveltia/sveltia-cms/issues/214),[^125] config editor,[^10] offline support,[^238] and other [top-voted features](https://github.com/decaporg/decap-cms/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) (some of them may be included in v2.0)
 - Exploring features that require server-side implementation, including user management (Netlify Identity alternative), roles,[^23] commits without a Git service account (Git Gateway alternative), post locking (like [WordPress](https://codex.wordpress.org/Post_Locking))[^166] and scheduled posts[^167]
 - More integration options: stock photos, stock videos, cloud storage providers, translation services, maps, analytics tools, etc.
 - AI integrations for image generation, content writing, translation, etc.
@@ -1370,10 +1424,12 @@ Due Q4 2025
 - Marketplace for custom widgets, etc.
 - VS Code extension for `config.yml` schema validation
 - Official starter templates for the most popular frameworks, including SvelteKit and Next.js
+- Contributor documentation
 - and so much more!
 
 ## Trivia
 
+- As mentioned in the [Motivation](#motivation) section, Sveltia CMS is a complete rewrite of Netlify CMS. We rarely look at the predecessor’s code and don’t use any of it. This is why Sveltia CMS is free of their bugs.
 - The [original version of Netlify CMS](https://github.com/netlify/netlify-cms-legacy) was built with Ember before being rewritten in React. And now we are completely rewriting it in Svelte. So this is effectively the second time the application has gone through a framework migration.
 - Our [local repository workflow](#working-with-a-local-git-repository) shares implementation with the Test backend, as both utilize the [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API), allowing us to reduce maintenance costs. The seamless local workflow is critical not only for improved DX, but also for our rapid application development.
 
@@ -1400,8 +1456,6 @@ This software is provided “as is” without any express or implied warranty. W
 
 [^4]: Netlify/Decap CMS [#3671](https://github.com/decaporg/decap-cms/issues/3671)
 
-[^5]: Netlify/Decap CMS [#1032](https://github.com/decaporg/decap-cms/issues/1032)
-
 [^6]: Netlify/Decap CMS [#3240](https://github.com/decaporg/decap-cms/issues/3240)
 
 [^7]: Netlify/Decap CMS [#4386](https://github.com/decaporg/decap-cms/issues/4386), [#4888](https://github.com/decaporg/decap-cms/issues/4888), [#7332](https://github.com/decaporg/decap-cms/issues/7332), [#7514](https://github.com/decaporg/decap-cms/issues/7514)
@@ -1536,7 +1590,7 @@ This software is provided “as is” without any express or implied warranty. W
 
 [^72]: Netlify/Decap CMS [#7047](https://github.com/decaporg/decap-cms/issues/7047)
 
-[^73]: Netlify/Decap CMS [#6993](https://github.com/decaporg/decap-cms/issues/6993), [#7123](https://github.com/decaporg/decap-cms/issues/7123), [#7127](https://github.com/decaporg/decap-cms/issues/7127), [#7128](https://github.com/decaporg/decap-cms/issues/7128), [#7237](https://github.com/decaporg/decap-cms/issues/7237), [#7251](https://github.com/decaporg/decap-cms/issues/7251), [#7361](https://github.com/decaporg/decap-cms/issues/7361), [#7391](https://github.com/decaporg/decap-cms/issues/7391), [#7393](https://github.com/decaporg/decap-cms/issues/7393), [#7470](https://github.com/decaporg/decap-cms/issues/7470), [#7475](https://github.com/decaporg/decap-cms/issues/7475), [#7480](https://github.com/decaporg/decap-cms/issues/7480), [#7503](https://github.com/decaporg/decap-cms/issues/7503), [#7504](https://github.com/decaporg/decap-cms/issues/7504)
+[^73]: Netlify/Decap CMS [#6993](https://github.com/decaporg/decap-cms/issues/6993), [#7123](https://github.com/decaporg/decap-cms/issues/7123), [#7127](https://github.com/decaporg/decap-cms/issues/7127), [#7128](https://github.com/decaporg/decap-cms/issues/7128), [#7237](https://github.com/decaporg/decap-cms/issues/7237), [#7251](https://github.com/decaporg/decap-cms/issues/7251), [#7361](https://github.com/decaporg/decap-cms/issues/7361), [#7391](https://github.com/decaporg/decap-cms/issues/7391), [#7393](https://github.com/decaporg/decap-cms/issues/7393), [#7470](https://github.com/decaporg/decap-cms/issues/7470), [#7475](https://github.com/decaporg/decap-cms/issues/7475), [#7480](https://github.com/decaporg/decap-cms/issues/7480), [#7503](https://github.com/decaporg/decap-cms/issues/7503), [#7504](https://github.com/decaporg/decap-cms/issues/7504), [#7524](https://github.com/decaporg/decap-cms/issues/7524)
 
 [^74]: Netlify/Decap CMS [#4209](https://github.com/decaporg/decap-cms/issues/4209)
 
@@ -1856,7 +1910,7 @@ This software is provided “as is” without any express or implied warranty. W
 
 [^232]: Netlify/Decap CMS [#7457](https://github.com/decaporg/decap-cms/issues/7457)
 
-[^233]: Netlify/Decap CMS [#535](https://github.com/decaporg/decap-cms/issues/535)
+[^233]: Netlify/Decap CMS [#535](https://github.com/decaporg/decap-cms/issues/535), [#1284](https://github.com/decaporg/decap-cms/issues/1284), [#3846](https://github.com/decaporg/decap-cms/issues/3846)
 
 [^234]: Netlify/Decap CMS [#2019](https://github.com/decaporg/decap-cms/issues/2019) — Rather than relying on a third-party library, we built our own asset browser that integrates more seamlessly with the rest of the CMS.
 
@@ -1865,3 +1919,29 @@ This software is provided “as is” without any express or implied warranty. W
 [^236]: Netlify/Decap CMS [#7507](https://github.com/decaporg/decap-cms/issues/7507)
 
 [^237]: Netlify/Decap CMS [#7375](https://github.com/decaporg/decap-cms/issues/7375), [#7518](https://github.com/decaporg/decap-cms/issues/7518)
+
+[^238]: Netlify/Decap CMS [#1502](https://github.com/decaporg/decap-cms/issues/1502)
+
+[^239]: Netlify/Decap CMS [#213](https://github.com/decaporg/decap-cms/issues/213), [#1032](https://github.com/decaporg/decap-cms/issues/1032), [#3244](https://github.com/decaporg/decap-cms/issues/3244), [#6730](https://github.com/decaporg/decap-cms/issues/6730), [#7459](https://github.com/decaporg/decap-cms/discussions/7459)
+
+[^240]: Netlify/Decap CMS [#2113](https://github.com/decaporg/decap-cms/issues/2113), [#3240](https://github.com/decaporg/decap-cms/issues/3240)
+
+[^241]: Netlify/Decap CMS [#857](https://github.com/decaporg/decap-cms/issues/857)
+
+[^242]: Netlify/Decap CMS [#192](https://github.com/decaporg/decap-cms/issues/192)
+
+[^243]: Netlify/Decap CMS [#717](https://github.com/decaporg/decap-cms/issues/717), [#5750](https://github.com/decaporg/decap-cms/issues/5750), [#6895](https://github.com/decaporg/decap-cms/issues/6895)
+
+[^244]: Netlify/Decap CMS [#1206](https://github.com/decaporg/decap-cms/issues/1206)
+
+[^245]: Netlify/Decap CMS [#1769](https://github.com/decaporg/decap-cms/issues/1769)
+
+[^246]: Netlify/Decap CMS [#1074](https://github.com/decaporg/decap-cms/issues/1074), [#1693](https://github.com/decaporg/decap-cms/issues/1693), [#3803](https://github.com/decaporg/decap-cms/issues/3803)
+
+[^247]: Netlify/Decap CMS [#1794](https://github.com/decaporg/decap-cms/issues/1794), [#2966](https://github.com/decaporg/decap-cms/issues/2966)
+
+[^248]: Netlify/Decap CMS [#836](https://github.com/decaporg/decap-cms/issues/836), [#3524](https://github.com/decaporg/decap-cms/issues/3524)
+
+[^249]: Netlify/Decap CMS [#4208](https://github.com/decaporg/decap-cms/issues/4208)
+
+[^250]: Netlify/Decap CMS [#6609](https://github.com/decaporg/decap-cms/issues/6609), [#6802](https://github.com/decaporg/decap-cms/issues/6802), [#6824](https://github.com/decaporg/decap-cms/issues/6824), [#6832](https://github.com/decaporg/decap-cms/issues/6832), [#6848](https://github.com/decaporg/decap-cms/issues/6848), [#6851](https://github.com/decaporg/decap-cms/issues/6851), [#7287](https://github.com/decaporg/decap-cms/issues/7287), [#7522](https://github.com/decaporg/decap-cms/issues/7522)