@sveltia/cms 0.39.18 → 0.40.1

package/README.md

@@ -12,6 +12,61 @@ Sveltia CMS is a Git-based lightweight headless CMS under active development as
 
 ![Screenshot: Works with Remote (GitHub, GitLab) and Local Repositories; Single Line Migration from Netlify/Decap CMS (depending on your current setup); Sveltia CMS](https://raw.githubusercontent.com/sveltia/sveltia-cms/main/docs/screenshot-5-20240507.webp)<br>
 
+## Table of contents
+
+- [Motivation](#motivation)
+  - [Our advantage](#our-advantage)
+  - [Our goals](#our-goals)
+- [Development status](#development-status)
+- [Differentiators](#differentiators)
+  - [Better UX](#better-ux)
+  - [Better performance](#better-performance)
+  - [Better productivity](#better-productivity)
+  - [Better accessibility](#better-accessibility)
+  - [Better security](#better-security)
+  - [Better configuration](#better-configuration)
+  - [Better backend support](#better-backend-support)
+  - [Better i18n support](#better-i18n-support)
+  - [Better collections](#better-collections)
+  - [Better content editing](#better-content-editing)
+  - [Better data output](#better-data-output)
+  - [Better widgets](#better-widgets)
+    - [New widgets](#new-widgets)
+  - [Better asset management](#better-asset-management)
+- [Compatibility](#compatibility)
+  - [Features not to be implemented](#features-not-to-be-implemented)
+  - [Current limitations](#current-limitations)
+- [Getting started](#getting-started)
+  - [New users](#new-users)
+  - [Migration](#migration)
+    - [Migrating from Git Gateway backend](#migrating-from-git-gateway-backend)
+    - [Moving your site from Netlify to another hosting service](#moving-your-site-from-netlify-to-another-hosting-service)
+  - [Installing with npm](#installing-with-npm)
+  - [Updates](#updates)
+- [Tips \& tricks](#tips--tricks)
+  - [Providing a JSON configuration file](#providing-a-json-configuration-file)
+  - [Working around authentication error](#working-around-authentication-error)
+  - [Working with a local Git repository](#working-with-a-local-git-repository)
+  - [Enabling local development in Brave](#enabling-local-development-in-brave)
+  - [Using a custom icon for a collection](#using-a-custom-icon-for-a-collection)
+  - [Adding dividers to the collection list](#adding-dividers-to-the-collection-list)
+  - [Using a custom media folder for a collection](#using-a-custom-media-folder-for-a-collection)
+  - [Using keyboard shortcuts](#using-keyboard-shortcuts)
+  - [Using DeepL to translate entry fields](#using-deepl-to-translate-entry-fields)
+  - [Localizing entry slugs](#localizing-entry-slugs)
+  - [Disabling non-default locale content](#disabling-non-default-locale-content)
+  - [Using a random ID for an entry slug](#using-a-random-id-for-an-entry-slug)
+  - [Disabling automatic deployments](#disabling-automatic-deployments)
+  - [Setting up Content Security Policy](#setting-up-content-security-policy)
+- [Support \& feedback](#support--feedback)
+- [Contributions](#contributions)
+- [Roadmap](#roadmap)
+  - [Before the 1.0 release](#before-the-10-release)
+  - [After the 1.0 release](#after-the-10-release)
+- [Related links](#related-links)
+  - [As seen on](#as-seen-on)
+- [Disclaimer](#disclaimer)
+
 ## 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.
@@ -56,26 +111,19 @@ Sveltia CMS **version 1.0 is expected to ship by the end of 2024**. Check our [r
 
 ![120 Netlify/Decap CMS Issues Solved in Sveltia CMS](https://raw.githubusercontent.com/sveltia/sveltia-cms/main/docs/headline-1-20240928.webp)<br>
 
-## Features
+## Differentiators
 
 We are working hard to create a **significantly better alternative to Netlify CMS and Decap CMS** by improving everything. Here’s what makes Sveltia CMS different. Look how serious we are!
 
-### Compatible with Netlify/Decap CMS
-
-- Ready to be used as a drop-in replacement for Netlify/Decap CMS _in some casual use case scenarios_ with a single line of code update.
-- Your existing [configuration file](https://decapcms.org/docs/configuration-options/) can be reused as is.
-- However, some features are still missing or will not be added, most notably Git Gateway and Netlify Identity. Look at the [compatibility info](#compatibility) below to see if you can migrate now or soon.
-
 ### Better UX
 
 - Created and maintained by an [experienced UX engineer](https://github.com/kyoshino) who loves code, design and marketing. You can expect constant improvements to the user experience (UX) and developer experience (DX) across the platform.
 - Offers a modern, intuitive user interface, including an immersive dark mode[^2], inspired in part by the Netlify CMS v3 prototype[^1].
 - Comes with touch device support, such as larger buttons for easier tapping. While the UI is not yet optimized for small screens, it should work well with large tablets like iPad Pro or Pixel Tablet. Mobile support and other optimizations such as swipe navigation are planned after the 1.0 release.
 - Made with Svelte, not React, means we can spend more time on UX rather than tedious state management. It also allows us to avoid common fatal application crashes[^113][^129]. Best of all, Svelte offers unmatched performance!
-- The Account menu contains relevant links, including release notes, feedback and help.
+- The Help menu provides all links to useful resources, including release notes, feedback and support.
 - Users can customize the application with various settings.
 - Never miss out on the latest features and bug fixes by being notified when an update to the CMS is available[^31]. Then update to the latest version with a single click[^66].
-- The screenshots above are worth a thousand words, but read on to learn about many other improvements in detail.
 
 ### Better performance
 
@@ -100,6 +148,7 @@ We are working hard to create a **significantly better alternative to Netlify CM
   - A local backup of an entry draft is automatically created without interruption by a confirmation dialog, which annoys users and can cause a page navigation problem if dismissed[^106]. The backup can then be reliably restored without unexpected overwriting[^85].
   - Click once (the Save button) instead of twice (Publish > Publish now) to save an entry.
   - The editor closes automatically when an entry is saved. This behaviour can be changed in Settings.
+- Uploading files can be done with drag and drop[^20].
 - You can upload multiple assets at once[^5].
 - You can delete multiple entries and assets at once.
 - Some [keyboard shortcuts](#using-keyboard-shortcuts) are available for faster editing.
@@ -112,7 +161,7 @@ We are working hard to create a **significantly better alternative to Netlify CM
 - Ensures sufficient contrast between the foreground text and background colours.
 - Enabled and disabled buttons can be clearly distinguished[^105].
 - Links are underlined by default to make them easier to recognize. This behaviour can be changed in the Accessibility Settings if you prefer.
-- Honours your operating system’s [reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) and [reduced transparency](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-transparency) settings. (Support for [high contrast mode](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) will be added later.)
+- Honours your operating system’s [reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) and [reduced transparency](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-transparency) settings. Support for [high contrast mode](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) will be added later.
 - Browser console logs for developers are readable in either light or dark mode[^116].
 - We’ll continue to test and improve the application to meet [WCAG 2.2](https://w3c.github.io/wcag/guidelines/22/).
 
@@ -270,6 +319,7 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
     - A new asset can be uploaded by dragging & dropping it into the dialog[^20].
     - A URL can also be entered in the dialog.
     - Integration with Pexels, Pixabay and Unsplash makes it easy to select and insert a free stock photo[^8]. More stock photo providers will be added in the future.
+  - You can also simply drag and drop a file onto a File/Image field to attach it without having to open the Select File dialog.
   - Large images automatically fit in the preview pane instead of being displayed at their original size, which can easily exceed the width of the pane.
 - List and Object
   - The `summary` is displayed correctly when it refers to a Relation field[^36] or a simple List field.
@@ -294,7 +344,7 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
 
 ### 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[^96].
+- A completely new, full-fledged Asset Library, built separately from the image selection dialog, makes it easy to manage all of your files, including images, videos and documents[^96].
   - Navigate between the global media folder and per-collection media folders[^6].
   - Preview image, audio, video, text and PDF files. Check your site’s [CSP](#setting-up-content-security-policy) if the preview doesn’t work.
   - Copy the public URL[^74], file path, text data or image data of a selected asset to clipboard. The file path starts with `/` as expected[^48].
@@ -315,7 +365,7 @@ Sveltia CMS has been built with a multilingual architecture from the very beginn
 
 ## Compatibility
 
-We are trying to make Sveltia CMS compatible with Netlify/Decap CMS where possible, so that more users can seamlessly switch to our modern, powerful, high performance alternative. However, some features will be omitted due to deprecations and other factors.
+We are trying to make Sveltia CMS compatible with Netlify/Decap CMS where possible, so that more users can seamlessly switch to our modern, powerful, high performance alternative. It’s ready to be used as a drop-in replacement for Netlify/Decap CMS _in some casual use case scenarios_ with a [single line of code update](#migration). However, some features will be omitted due to deprecations and other factors. Look at the compatibility info below to see if you can migrate now or soon.
 
 ### Features not to be implemented
 
@@ -352,31 +402,6 @@ These limitations are expected to be resolved before or shortly after GA:
 
 Missing any other features? Let us know by [filing an issue](https://github.com/sveltia/sveltia-cms/issues/new).
 
-## Roadmap
-
-### Before the 1.0 release
-
-- [Svelte 5](https://svelte.dev/blog/svelte-5-release-candidate) _runes_ migration
-- Enhanced [compatibility with Netlify/Decap CMS](#compatibility)
-- Certain compatibility with Static CMS, a now-discontinued community fork of Netlify CMS, specifically the [KeyValue widget](https://staticjscms.netlify.app/docs/widget-keyvalue)[^123]
-- Localization with the new [Fluent](https://projectfluent.org)-powered sveltia-i18n library
-- Accessibility audit
-- Developer documentation (implementation guide)
-- Marketing site
-- Live demo site
-- Official starter templates for the most popular frameworks, including SvelteKit and Next.js
-- Broad automation test coverage (Vitest + Playwright)
-
-### After the 1.0 release
-
-- Tackling more Netlify/Decap CMS issues, especially the [top voted features](https://github.com/decaporg/decap-cms/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc), including MDX support[^122], manual entry sorting[^125], roles[^23], mobile optimization[^18] and config editor[^10] — Some features are already implemented in Sveltia CMS
-- Advanced digital asset management (DAM) features, including image editing and tagging[^114]
-- AI integrations for image generation and content writing
-- End-user documentation
-- Contributor documentation
-- Marketplace for custom widgets, etc.
-- and so much more!
-
 ## Getting started
 
 ### New users
@@ -420,6 +445,20 @@ That’s it! You can open `https://[hostname]/admin/` as before to start editing
 
 That said, we strongly recommend testing your new Sveltia CMS instance first on your local machine. [See below](#working-with-a-local-git-repository) for how.
 
+#### 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.
+
+Once you have migrated from the Git Gateway and Netlify Identity combo, you can remove the Netlify Identity widget script tag from your HTML:
+
+```diff
+-<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
+```
+
+#### Moving your site from Netlify to another hosting service
+
+You can host your Sveltia CMS-managed site anywhere, such as [Cloudflare Pages](https://pages.cloudflare.com/) or [GitHub Pages](https://pages.github.com/). But moving away from Netlify means you can no longer sign in with GitHub or GitLab via Netlify. Instead, you can use [our own OAuth client](https://github.com/sveltia/sveltia-cms-auth), which can be easily deployed to Cloudflare Workers, or [any other 3rd party client](https://decapcms.org/docs/external-oauth-clients/) made for Netlify/Decap CMS.
+
 ### Installing with npm
 
 For advanced users, we have also made the bundle available as an [npm package](https://www.npmjs.com/package/@sveltia/cms). You can install it by running `npm i @sveltia/cms` or `pnpm add @sveltia/cms` on your project. The [manual initialization](https://decapcms.org/docs/manual-initialization/) flow with the `init` method is the same as for Netlify/Decap CMS.
@@ -442,20 +481,6 @@ Sveltia CMS supports a configuration file written in the JSON format in addition
 
 Alternatively, you can [manually initialize](https://decapcms.org/docs/manual-initialization/) the CMS with a JavaScript configuration object.
 
-### 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.
-
-Once you have migrated from the Git Gateway and Netlify Identity combo, you can remove the Netlify Identity widget script tag from your HTML:
-
-```diff
--<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
-```
-
-### Moving your site from Netlify to another hosting service
-
-You can host your Sveltia CMS-managed site anywhere, such as [Cloudflare Pages](https://pages.cloudflare.com/) or [GitHub Pages](https://pages.github.com/). But moving away from Netlify means you can no longer sign in with GitHub or GitLab via Netlify. Instead, you can use [our own OAuth client](https://github.com/sveltia/sveltia-cms-auth), which can be easily deployed to Cloudflare Workers, or [any other 3rd party client](https://decapcms.org/docs/external-oauth-clients/) made for Netlify/Decap CMS.
-
 ### Working around authentication error
 
 If you get an “Authentication Aborted” error when trying to sign in to GitHub or GitLab using the authorization code flow, you may need to check your site’s [`Cross-Origin-Opener-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy). The COOP header is not widely used, but it’s known to break the OAuth flow with a popup window. If that’s your case, changing `same-origin` to `same-origin-allow-popups` solves the problem. ([Discussion](https://github.com/sveltia/sveltia-cms/issues/131))
@@ -634,7 +659,7 @@ i18n:
 
 ### Disabling non-default locale content
 
-You can now disable output of content in selected non-default locales by adding the `save_all_locales` property to the top-level or per-collection `i18n` configuration. Then you’ll find “Disable (locale name)” in the three-dot menu in the top right corner of the content editor. This is useful if the translation isn’t ready yet, but you want to publish the default locale content first.
+You can disable output of content in selected non-default locales by adding the `save_all_locales` property to the top-level or per-collection `i18n` configuration. Then you’ll find “Disable (locale name)” in the three-dot menu in the top right corner of the content editor. This is useful if the translation isn’t ready yet, but you want to publish the default locale content first.
 
 With the following configuration, you can disable the French and/or German translation while writing in English.
 
@@ -807,6 +832,31 @@ Looking to build a website with Sveltia CMS? Maintainer [@kyoshino](https://gith
 
 See [Contributing to Sveltia CMS](https://github.com/sveltia/sveltia-cms/blob/main/CONTRIBUTING.md).
 
+## Roadmap
+
+### Before the 1.0 release
+
+- [Svelte 5](https://svelte.dev/blog/svelte-5-release-candidate) _runes_ migration
+- Enhanced [compatibility with Netlify/Decap CMS](#compatibility)
+- Certain compatibility with Static CMS, a now-discontinued community fork of Netlify CMS, specifically the [KeyValue widget](https://staticjscms.netlify.app/docs/widget-keyvalue)[^123]
+- Localization with the new [Fluent](https://projectfluent.org)-powered sveltia-i18n library
+- Accessibility audit
+- Developer documentation (implementation guide)
+- Marketing site
+- Live demo site
+- Official starter templates for the most popular frameworks, including SvelteKit and Next.js
+- Broad automation test coverage (Vitest + Playwright)
+
+### After the 1.0 release
+
+- Tackling more Netlify/Decap CMS issues, especially the [top voted features](https://github.com/decaporg/decap-cms/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc), including MDX support[^122], manual entry sorting[^125], roles[^23], mobile optimization[^18] and config editor[^10] — Some features are already implemented in Sveltia CMS
+- Advanced digital asset management (DAM) features, including image editing and tagging[^114]
+- AI integrations for image generation and content writing
+- End-user documentation
+- Contributor documentation
+- Marketplace for custom widgets, etc.
+- and so much more!
+
 ## 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)
@@ -1044,7 +1094,7 @@ This software is provided “as is” without any express or implied warranty. W
 
 [^112]: Netlify/Decap CMS [#5815](https://github.com/decaporg/decap-cms/issues/5815), [#6522](https://github.com/decaporg/decap-cms/issues/6522), [#6532](https://github.com/decaporg/decap-cms/issues/6532), [#6588](https://github.com/decaporg/decap-cms/issues/6588), [#6617](https://github.com/decaporg/decap-cms/issues/6617), [#6640](https://github.com/decaporg/decap-cms/issues/6640), [#6663](https://github.com/decaporg/decap-cms/issues/6663), [#6695](https://github.com/decaporg/decap-cms/issues/6695), [#6697](https://github.com/decaporg/decap-cms/issues/6697), [#6764](https://github.com/decaporg/decap-cms/issues/6764), [#6765](https://github.com/decaporg/decap-cms/issues/6765), [#6835](https://github.com/decaporg/decap-cms/issues/6835), [#6983](https://github.com/decaporg/decap-cms/issues/6983), [#7205](https://github.com/decaporg/decap-cms/issues/7205)
 
-[^113]: Netlify/Decap CMS [#5656](https://github.com/decaporg/decap-cms/issues/5656), [#5837](https://github.com/decaporg/decap-cms/issues/5837), [#5972](https://github.com/decaporg/decap-cms/issues/5972), [#6476](https://github.com/decaporg/decap-cms/issues/6476), [#6516](https://github.com/decaporg/decap-cms/issues/6516), [#6930](https://github.com/decaporg/decap-cms/issues/6930), [#6965](https://github.com/decaporg/decap-cms/issues/6965), [#7080](https://github.com/decaporg/decap-cms/issues/7080), [#7105](https://github.com/decaporg/decap-cms/issues/7105), [#7106](https://github.com/decaporg/decap-cms/issues/7106), [#7119](https://github.com/decaporg/decap-cms/issues/7119), [#7176](https://github.com/decaporg/decap-cms/issues/7176), [#7194](https://github.com/decaporg/decap-cms/issues/7194), [#7244](https://github.com/decaporg/decap-cms/issues/7244) — These `removeChild` crashes are common in React apps and seem to be caused by a [browser extension](https://github.com/facebook/react/issues/17256) or [Google Translate](https://github.com/facebook/react/issues/11538).
+[^113]: Netlify/Decap CMS [#5656](https://github.com/decaporg/decap-cms/issues/5656), [#5837](https://github.com/decaporg/decap-cms/issues/5837), [#5972](https://github.com/decaporg/decap-cms/issues/5972), [#6476](https://github.com/decaporg/decap-cms/issues/6476), [#6516](https://github.com/decaporg/decap-cms/issues/6516), [#6930](https://github.com/decaporg/decap-cms/issues/6930), [#6965](https://github.com/decaporg/decap-cms/issues/6965), [#7080](https://github.com/decaporg/decap-cms/issues/7080), [#7105](https://github.com/decaporg/decap-cms/issues/7105), [#7106](https://github.com/decaporg/decap-cms/issues/7106), [#7119](https://github.com/decaporg/decap-cms/issues/7119), [#7176](https://github.com/decaporg/decap-cms/issues/7176), [#7194](https://github.com/decaporg/decap-cms/issues/7194), [#7244](https://github.com/decaporg/decap-cms/issues/7244), [#7301](https://github.com/decaporg/decap-cms/issues/7301) — These `removeChild` crashes are common in React apps and seem to be caused by a [browser extension](https://github.com/facebook/react/issues/17256) or [Google Translate](https://github.com/facebook/react/issues/11538).
 
 [^114]: Netlify/Decap CMS [#5029](https://github.com/decaporg/decap-cms/issues/5029), [#5048](https://github.com/decaporg/decap-cms/issues/5048)