@sveltia/cms 0.87.3 → 0.87.4

package/types/public.d.ts

@@ -1,12 +1,14 @@
 /**
- * Standard IETF locale tag like `en` or `en-US`.
+ * Standard [IETF locale tag](https://en.wikipedia.org/wiki/IETF_language_tag) like `en` or `en-US`.
  */
 export type LocaleCode = string;
 /**
  * An entry field name. It can be written in dot notation like `author.name` if the field is nested
- * with an Object field. For a List subfield, a wildcard can be used like `authors.*.name`. We
- * call this a key path, which is derived from the IndexedDB API terminology, and use it everywhere,
- * as entry data is managed as a flatten object for easier access.
+ * with an Object field. For a List subfield, a wildcard can be used like `authors.*.name`. We call
+ * this a key path, which is derived from the [IndexedDB API
+ * terminology](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Basic_Terminology#key_path),
+ * and use it everywhere, as entry data is managed as a [flatten
+ * object](https://www.npmjs.com/package/flat) for easier access.
  */
 export type FieldKeyPath = string;
 /**
@@ -28,7 +30,8 @@ export type VectorImageFormat = "svg";
  */
 export type RasterImageConversionFormat = "webp";
 /**
- * Raster image transformation options.
+ * Raster image transformation options. See our
+ * [README](https://github.com/sveltia/sveltia-cms#optimizing-images-for-upload) for details.
  */
 export type RasterImageTransformationOptions = {
     /**
@@ -122,7 +125,8 @@ export type DefaultMediaLibraryConfig = {
     /**
      * File transformation option map. The key is an
      * original format like `png` or `jpeg`. It can also be `raster_image` that matches any supported
-     * raster image format.
+     * raster image format. See our
+     * [README](https://github.com/sveltia/sveltia-cms#optimizing-images-for-upload) for details.
      */
     transformations?: FileTransformations;
 };
@@ -136,7 +140,7 @@ export type DefaultMediaLibrary = {
     config?: DefaultMediaLibraryConfig;
 };
 /**
- * Options for the Cloudinary media library.
+ * Options for the [Cloudinary media library](https://decapcms.org/docs/cloudinary/).
  */
 export type CloudinaryMediaLibrary = {
     /**
@@ -156,13 +160,14 @@ export type CloudinaryMediaLibrary = {
     /**
      * Options to be passed to Cloudinary, such as `multiple`.
      * The `cloud_name` and `api_key` options are required for the global `media_library` option. See
-     * https://cloudinary.com/documentation/media_library_widget#2_set_the_configuration_options for a
-     * full list of available options.
+     * the [Cloudinary
+     * documentation](https://cloudinary.com/documentation/media_library_widget#2_set_the_configuration_options)
+     * for a full list of available options.
      */
     config?: Record<string, any>;
 };
 /**
- * Settings for the Uploadcare media library.
+ * Settings for the [Uploadcare media library](https://decapcms.org/docs/uploadcare/).
  */
 export type UploadcareMediaLibrarySettings = {
     /**
@@ -177,13 +182,14 @@ export type UploadcareMediaLibrarySettings = {
     defaultOperations?: string;
 };
 /**
- * Options for the Uploadcare media library.
+ * Options for the [Uploadcare media library](https://decapcms.org/docs/uploadcare/).
  */
 export type UploadcareMediaLibrary = {
     /**
      * Options to be passed to Uploadcare, such as `multiple`.
-     * The `publicKey` option is required for the global `media_library` option. See
-     * https://uploadcare.com/docs/uploads/file-uploader-options/ for a full list of available options.
+     * The `publicKey` option is required for the global `media_library` option. See the [Uploadcare
+     * documentation](https://uploadcare.com/docs/uploads/file-uploader-options/) for a full list of
+     * available options.
      */
     config?: Record<string, any>;
     /**
@@ -207,11 +213,13 @@ export type StockAssetMediaLibrary = {
     providers?: StockAssetProviderName[];
 };
 /**
- * Supported media library.
+ * Supported [media library](https://decapcms.org/docs/configuration-options/#media-library).
  */
 export type MediaLibrary = DefaultMediaLibrary | CloudinaryMediaLibrary | UploadcareMediaLibrary | StockAssetMediaLibrary;
 /**
- * Unified media library option that supports multiple libraries.
+ * Unified media library option that supports multiple libraries. See our
+ * [README](https://github.com/sveltia/sveltia-cms#configuring-multiple-media-libraries) for
+ * details.
  */
 export type MediaLibraries = {
     /**
@@ -314,8 +322,9 @@ export type MediaFieldProps = {
     default?: string;
     /**
      * File types that the field should accept. The value would be a
-     * comma-separated list of unique file type specifiers, the format used for the HTML `accept`
-     * attribute: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept.
+     * comma-separated list of unique file type specifiers, the format used for the HTML
+     * [`accept`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept)
+     * attribute.
      */
     accept?: string;
     /**
@@ -408,8 +417,8 @@ export type VariableFieldType = {
      */
     summary?: string;
     /**
-     * Set of subfields. This option can be omitted; in that case, only
-     * the `type` property will be saved.
+     * Set of subfields. This option can be omitted; in that case, only the
+     * `type` property will be saved.
      */
     fields?: Field[];
 };
@@ -488,9 +497,9 @@ export type CodeFieldProps = {
      */
     default?: string | Record<string, string>;
     /**
-     * Default language to be selected, like `js`. See
-     * https://prismjs.com/#supported-languages for a list of supported languages. Default: empty
-     * string, which is plaintext.
+     * Default language to be selected, like `js`. See the [Prism
+     * documentation](https://prismjs.com/#supported-languages) for a list of supported languages.
+     * Default: empty string, which is plaintext.
      */
     default_language?: string;
     /**
@@ -573,20 +582,22 @@ export type DateTimeFieldProps = {
      */
     default?: string;
     /**
-     * Storage format written in Moment.js tokens. See
-     * https://momentjs.com/docs/#/displaying/format/ for supported tokens. Default: ISO 8601 format.
+     * Storage format written in [Moment.js
+     * tokens](https://momentjs.com/docs/#/displaying/format/). Default: ISO 8601 format.
      */
     format?: string;
     /**
-     * Date storage format written in Moment.js tokens if the
-     * value is a string and the `format` option is not defined. If `true`, ISO 8601 format is used
-     * unless the `format` option is defined. If `false`, date input/output is disabled.
+     * Date storage format written in [Moment.js
+     * tokens](https://momentjs.com/docs/#/displaying/format/) if the value is a string and the `format`
+     * option is not defined. If `true`, ISO 8601 format is used unless the `format` option is defined.
+     * If `false`, date input/output is disabled.
      */
     date_format?: string | boolean;
     /**
-     * Time storage format written in Moment.js tokens if the
-     * value is a string and the `format` option is not defined. If `true`, ISO 8601 format is used
-     * unless the `format` option is defined. If `false`, time input/output is disabled.
+     * Time storage format written in [Moment.js
+     * tokens](https://momentjs.com/docs/#/displaying/format/) if the value is a string and the `format`
+     * option is not defined. If `true`, ISO 8601 format is used unless the `format` option is defined.
+     * If `false`, time input/output is disabled.
      */
     time_format?: string | boolean;
     /**
@@ -643,7 +654,7 @@ export type ImageFieldProps = {
  */
 export type ImageField = CommonFieldProps & StandardFieldProps & MediaFieldProps & ImageFieldProps;
 /**
- * KeyValue field properties.
+ * KeyValue field properties compatible with Static CMS.
  */
 export type KeyValueFieldProps = {
     /**
@@ -722,8 +733,9 @@ export type ListFieldProps = {
     /**
      * Whether to save the field value at the top-level of the data file
      * without the field name. If the `single_file` i18n structure is enabled, the lists will still be
-     * saved under locale keys. Default: `false`. See
-     * https://github.com/sveltia/sveltia-cms#editing-data-files-with-a-top-level-list for details.
+     * saved under locale keys. Default: `false`. See our
+     * [README](https://github.com/sveltia/sveltia-cms#editing-data-files-with-a-top-level-list) for
+     * details.
      */
     root?: boolean;
 };
@@ -740,8 +752,9 @@ export type MapFieldProps = {
      */
     widget: "map";
     /**
-     * Default value. Accepts a stringified single GeoJSON geometry object
-     * that contains `type` and `coordinates` properties.
+     * Default value. Accepts a stringified single
+     * [GeoJSON](https://geojson.org/) geometry object that contains `type` and `coordinates`
+     * properties.
      */
     default?: string;
     /**
@@ -1049,6 +1062,11 @@ export type UuidField = CommonFieldProps & StandardFieldProps & UuidFieldProps;
  * Entry field using a built-in widget.
  */
 export type StandardField = BooleanField | CodeField | ColorField | ComputeField | DateTimeField | FileField | HiddenField | ImageField | KeyValueField | ListField | MapField | MarkdownField | NumberField | ObjectField | RelationField | SelectField | StringField | TextField | UuidField;
+/**
+ * Name of a built-in widget. Sveltia CMS supports all the built-in widgets provided by Decap CMS as
+ * well as some new widgets.
+ */
+export type BuiltInWidgetName = "boolean" | "code" | "color" | "compute" | "datetime" | "file" | "hidden" | "image" | "keyvalue" | "list" | "map" | "markdown" | "number" | "object" | "relation" | "select" | "string" | "text" | "uuid";
 /**
  * Custom field properties.
  */
@@ -1056,7 +1074,7 @@ export type CustomFieldProps = {
     /**
      * Widget name.
      */
-    widget: string;
+    widget: Exclude<string, BuiltInWidgetName>;
 };
 /**
  * Entry field using a custom widget.
@@ -1091,22 +1109,24 @@ export type I18nOptions = {
     /**
      * Locales to be enabled when
      * creating a new entry draft. If this option is used, users will be able to disable the output of
-     * non-default locales through the UI. See
-     * https://github.com/sveltia/sveltia-cms#disabling-non-default-locale-content for details.
+     * non-default locales through the UI. See our
+     * [README](https://github.com/sveltia/sveltia-cms#disabling-non-default-locale-content) for
+     * details.
      */
     initial_locales?: LocaleCode[] | "all" | "default";
     /**
      * Whether to save collection entries in all the locales. If
-     * `false`, users will be able to disable the output of non-default locales through the UI. See
-     * https://github.com/sveltia/sveltia-cms#disabling-non-default-locale-content for details.
+     * `false`, users will be able to disable the output of non-default locales through the UI. See our
+     * [README](https://github.com/sveltia/sveltia-cms#disabling-non-default-locale-content) for
+     * details.
      */
     save_all_locales?: boolean;
     /**
      * Property name and value template used
      * to add a canonical slug to entry files, which helps Sveltia CMS and some frameworks to link
      * localized files when entry slugs are localized. The default property name is `translationKey`
-     * used in Hugo’s multilingual support, and the default value is the default locale’s slug. See
-     * https://github.com/sveltia/sveltia-cms#localizing-entry-slugs for details.
+     * used in Hugo’s multilingual support, and the default value is the default locale’s slug. See our
+     * [README](https://github.com/sveltia/sveltia-cms#localizing-entry-slugs) for details.
      */
     canonical_slug?: {
         key: string;
@@ -1116,8 +1136,8 @@ export type I18nOptions = {
      * Whether to exclude the default locale
      * from entry filenames. Default: `false`. This option applies to entry collections with the
      * `multiple_files` i18n structure enabled, as well as to file/singleton collection items with the
-     * `file` path ending with `.{{locale}}.<extension>`, aiming to support Zola’s multilingual sites:
-     * https://www.getzola.org/documentation/content/multilingual/.
+     * `file` path ending with `.{{locale}}.<extension>`, aiming to support [Zola’s multilingual
+     * sites](https://www.getzola.org/documentation/content/multilingual/).
      */
     omit_default_locale_from_filename?: boolean;
 };
@@ -1134,8 +1154,11 @@ export type CollectionFile = {
      */
     label?: string;
     /**
-     * Name of a Material Symbols icon to be displayed in the collection file
-     * list and other places.
+     * Name of a [Material Symbols
+     * icon](https://fonts.google.com/icons?icon.set=Material+Symbols) to be displayed in the collection
+     * file list and other places. See our
+     * [README](https://github.com/sveltia/sveltia-cms#using-a-custom-icon-for-a-collection) for
+     * details.
      */
     icon?: string;
     /**
@@ -1182,7 +1205,7 @@ export type CollectionFile = {
     preview_path_date_field?: FieldKeyPath;
 };
 /**
- * Supported file extension.
+ * Supported file extension. Actually it can be any string.
  */
 export type FileExtension = "yml" | "yaml" | "toml" | "json" | "md" | "markdown" | "html" | string;
 /**
@@ -1235,8 +1258,9 @@ export type SortableFields = {
      */
     fields: FieldKeyPath[];
     /**
-     * Default sort settings. See
-     * https://github.com/sveltia/sveltia-cms#specifying-default-sort-field-and-direction for details.
+     * Default sort settings. See our
+     * [README](https://github.com/sveltia/sveltia-cms#specifying-default-sort-field-and-direction) for
+     * details.
      */
     default?: SortableFieldsDefaultOptions;
 };
@@ -1324,7 +1348,9 @@ export type CollectionMetaData = {
     path?: CollectionMetaDataPath;
 };
 /**
- * Index file inclusion options.
+ * Index file inclusion options. See our
+ * [README](https://github.com/sveltia/sveltia-cms#including-hugos-special-index-file-in-a-folder-collection)
+ * for details.
  */
 export type CollectionIndexFile = {
     /**
@@ -1338,7 +1364,8 @@ export type CollectionIndexFile = {
      */
     label?: string;
     /**
-     * Name of a Material Symbols icon to be displayed in the editor UI.
+     * Name of a [Material Symbols
+     * icon](https://fonts.google.com/icons?icon.set=Material+Symbols) to be displayed in the editor UI.
      * Default: `home`.
      */
     icon?: string;
@@ -1353,7 +1380,9 @@ export type CollectionIndexFile = {
     editor?: EditorOptions;
 };
 /**
- * A divider in the collection list and singleton list.
+ * A divider in the collection list and singleton list. See our
+ * [README](https://github.com/sveltia/sveltia-cms#adding-dividers-to-the-collection-list) for
+ * details.
  */
 export type CollectionDivider = {
     /**
@@ -1394,7 +1423,9 @@ export type Collection = {
      */
     description?: string;
     /**
-     * Name of a Material Symbols icon to be displayed in the collection list.
+     * Name of a [Material Symbols
+     * icon](https://fonts.google.com/icons?icon.set=Material+Symbols) to be displayed in the collection
+     * list.
      */
     icon?: string;
     /**
@@ -1421,7 +1452,11 @@ export type Collection = {
     path?: string;
     /**
      * Internal media folder path for the collection. This overrides
-     * the global `media_folder` option.
+     * the global `media_folder` option. It can be a relative path from the project root if it starts
+     * with a slash. Otherwise it’s a path relative to the entry. If this option is omitted, the global
+     * `media_folder` option value is used. See our
+     * [README](https://github.com/sveltia/sveltia-cms#using-a-custom-media-folder-for-a-collection) for
+     * details.
      */
     media_folder?: string;
     /**
@@ -1468,7 +1503,9 @@ export type Collection = {
     frontmatter_delimiter?: string | string[];
     /**
      * Item slug template. Entry collection only. Default: `identifier_field`
-     * option value.
+     * option value. It’s possible to [localize the
+     * slug](https://github.com/sveltia/sveltia-cms#localizing-entry-slugs) or [use a random
+     * ID](https://github.com/sveltia/sveltia-cms#using-a-random-id-for-an-entry-slug).
      */
     slug?: string;
     /**
@@ -1484,7 +1521,9 @@ export type Collection = {
     /**
      * Custom sortable fields. Entry
      * collection only. Default: `title`, `name`, `date`, `author` and `description`. For a Git backend,
-     * commit author and commit date are also included by default.
+     * commit author and commit date are also included by default. See our
+     * [README](https://github.com/sveltia/sveltia-cms#specifying-default-sort-field-and-direction) for
+     * details.
      */
     sortable_fields?: FieldKeyPath[] | SortableFields;
     /**
@@ -1525,7 +1564,9 @@ export type Collection = {
     /**
      * Index file inclusion options. Entry
      * collection only. If `true`, the default index file name is `_index`, which is used for Hugo’s
-     * special index file.
+     * special index file. See our
+     * [README](https://github.com/sveltia/sveltia-cms#including-hugos-special-index-file-in-a-folder-collection)
+     * for details.
      */
     index_file?: CollectionIndexFile | boolean;
     /**
@@ -1618,14 +1659,15 @@ export type BackendOptions = {
     graphql_api_root?: string;
     /**
      * Site domain used for OAuth, which will be included in the
-     * `site_id` param to be sent to the API endpoint. Git backends only. Default: `location.hostname`.
+     * `site_id` param to be sent to the API endpoint. Git backends only. Default:
+     * [`location.hostname`](https://developer.mozilla.org/en-US/docs/Web/API/Location/hostname).
      */
     site_domain?: string;
     /**
      * OAuth base URL origin. Git backends only. Required when using an
-     * OAuth client other than Netlify, including Sveltia CMS Authenticator. Default:
-     * `https://api.netlify.com` (GitHub), `https://gitlab.com` (GitLab) or `https://gitea.com/`
-     * (Gitea).
+     * OAuth client other than Netlify, including [Sveltia CMS
+     * Authenticator](https://github.com/sveltia/sveltia-cms-auth). Default: `https://api.netlify.com`
+     * (GitHub), `https://gitlab.com` (GitLab) or `https://gitea.com/` (Gitea).
      */
     base_url?: string;
     /**
@@ -1674,7 +1716,7 @@ export type BackendOptions = {
      * Whether to enable or disable automatic deployments
      * with any connected CI/CD provider, such as GitHub Actions or Cloudflare Pages. If `false`, the
      * `[skip ci]` prefix will be added to commit messages. Git backends only. Default: `undefined`. See
-     * https://github.com/sveltia/sveltia-cms#disabling-automatic-deployments for details.
+     * our [README](https://github.com/sveltia/sveltia-cms#disabling-automatic-deployments) for details.
      */
     automatic_deployments?: boolean;
 };
@@ -1763,8 +1805,8 @@ export type OutputOptions = {
 export type SiteConfig = {
     /**
      * Whether to load YAML/JSON site configuration file(s) when
-     * manually initializing the CMS. This works only in the `CMS.init()` method’s `config` option.
-     * Default: `true`.
+     * [manually initializing the CMS](https://decapcms.org/docs/manual-initialization/). This works
+     * only in the `CMS.init()` method’s `config` option. Default: `true`.
      */
     load_config_file?: boolean;
     /**
@@ -1794,11 +1836,14 @@ export type SiteConfig = {
     media_library?: MediaLibrary & GlobalMediaLibraryOptions;
     /**
      * Unified media library option that supports multiple
-     * libraries.
+     * libraries. See our
+     * [README](https://github.com/sveltia/sveltia-cms#configuring-multiple-media-libraries) for
+     * details.
      */
     media_libraries?: MediaLibraries;
     /**
-     * Site URL. Default: current site’s origin (`location.origin`).
+     * Site URL. Default: current site’s origin
+     * ([`location.origin`](https://developer.mozilla.org/en-US/docs/Web/API/Location/origin)).
      */
     site_url?: string;
     /**
@@ -1827,7 +1872,8 @@ export type SiteConfig = {
     /**
      * Set of singleton files, such as
      * the site configuration file or the homepage file. They are not part of any collection and can be
-     * accessed directly through the collection list. The list can also contain dividers.
+     * accessed directly through the collection list. The list can also contain dividers. See our
+     * [README](https://github.com/sveltia/sveltia-cms#using-singletons) for details.
      */
     singletons?: (CollectionFile | CollectionDivider)[];
     /**
@@ -1839,7 +1885,8 @@ export type SiteConfig = {
      */
     editor?: EditorOptions;
     /**
-     * Data output options.
+     * Data output options. See our
+     * [README](https://github.com/sveltia/sveltia-cms#controlling-data-output) for details.
      */
     output?: OutputOptions;
 };
@@ -1864,7 +1911,8 @@ export type EditorComponentDefinition = {
      */
     label: string;
     /**
-     * Name of a Material Symbols icon to be displayed in the editor UI.
+     * Name of a [Material Symbols
+     * icon](https://fonts.google.com/icons?icon.set=Material+Symbols) to be displayed in the editor UI.
      */
     icon?: string;
     /**