Update docs
This commit is contained in:
Daniel Lautzenheiser
parent
0744da1619
commit
68eb00e598
@ -277,11 +277,16 @@ export interface WidgetControlProps<T, F extends BaseField = UnknownField, EV =
|
||||
hidden: boolean;
|
||||
label: string;
|
||||
locale: string | undefined;
|
||||
// @deprecated Use useMediaInsert instead
|
||||
mediaPaths: Record<string, MediaPath>;
|
||||
onChange: (value: T | null | undefined) => void;
|
||||
// @deprecated Use useMediaInsert instead
|
||||
clearMediaControl: EditorControlProps['clearMediaControl'];
|
||||
// @deprecated Use useMediaInsert instead
|
||||
openMediaLibrary: EditorControlProps['openMediaLibrary'];
|
||||
// @deprecated Use useMediaInsert instead
|
||||
removeInsertedMedia: EditorControlProps['removeInsertedMedia'];
|
||||
// @deprecated Use useMediaInsert instead
|
||||
removeMediaControl: EditorControlProps['removeMediaControl'];
|
||||
i18n: I18nSettings | undefined;
|
||||
hasErrors: boolean;
|
||||
|
||||
@ -18,16 +18,18 @@ npm install @staticcms/core@latest
|
||||
yarn add @staticcms/core@latest
|
||||
```
|
||||
|
||||
Then create a new route for your project (for instance at `/admin`), and import Static CMS:
|
||||
Then create a new route for your project (for instance at `/admin`), then import Static CMS and its styles:
|
||||
|
||||
```js
|
||||
import CMS from '@staticcms/core';
|
||||
import '@staticcms/core/dist/main.css';
|
||||
```
|
||||
|
||||
The default export is a _CMS_ object, which has an `init` method that takes an object with a `config` attribute. The `config` attribute is an object representing the [configuration options](/docs/configuration-options). You can use destructuring assignment syntax as shorthand:
|
||||
|
||||
```js
|
||||
import CMS from '@staticcms/core';
|
||||
import '@staticcms/core/dist/main.css';
|
||||
import config from './config';
|
||||
|
||||
// Initialize the CMS object
|
||||
@ -38,12 +40,13 @@ CMS.registerPreviewTemplate('my-template', MyTemplate);
|
||||
|
||||
**Note**: Wherever you initialize Static CMS (via `CMS.init()`), it takes over the current page. Make sure you only run the initialization code on your CMS page.
|
||||
|
||||
If the CMS object is initialized without being passed an object with a valid config attribute, it will try to fetch and read a `config.yml` file, via http, within the same path where the CMS resides (`/admin/config.yml`).
|
||||
If the CMS object is initialized without being passed an object with a valid config attribute, it will try to fetch and read a `config.yml` file, via http, within the same path where Static CMS resides (`/admin/config.yml`).
|
||||
|
||||
```js
|
||||
import CMS from '@staticcms/core';
|
||||
import '@staticcms/core/dist/main.css';
|
||||
|
||||
// Initialize the CMS object
|
||||
// Initialize Static CMS object
|
||||
CMS.init();
|
||||
// Now the registry is available via the CMS object.
|
||||
CMS.registerPreviewTemplate('my-template', MyTemplate);
|
||||
@ -85,7 +88,7 @@ The configuration above specifies your backend protocol and your publication bra
|
||||
|
||||
### Media and Public Folders
|
||||
|
||||
Static CMS allows users to upload images directly within the editor. For this to work, the CMS needs to know where to save them. If you already have an `images` folder in your project, you could use its path, possibly creating an `uploads` sub-folder, for example:
|
||||
Static CMS allows users to upload images directly within the editor. For this to work, Static CMS needs to know where to save them. If you already have an `images` folder in your project, you could use its path, possibly creating an `uploads` sub-folder, for example:
|
||||
|
||||
<CodeTabs>
|
||||
```js
|
||||
@ -249,7 +252,7 @@ Netlify's Identity and Git Gateway services allow you to manage CMS admin users
|
||||
1. Go to **Settings > Identity**, and select **Enable Identity service**.
|
||||
2. Under **Registration preferences**, select **Open** or **Invite only**. In most cases, you want only invited users to access your CMS, but if you're just experimenting, you can leave it open for convenience.
|
||||
3. If you'd like to allow one-click login with services like Google and GitHub, check the boxes next to the services you'd like to use, under **External providers**.
|
||||
4. Scroll down to **Services > Git Gateway**, and click **Enable Git Gateway**. This authenticates with your Git host and generates an API access token. In this case, we're leaving the **Roles** field blank, which means any logged in user may access the CMS. For information on changing this, check the [Netlify Identity documentation](https://www.netlify.com/docs/identity/).
|
||||
4. Scroll down to **Services > Git Gateway**, and click **Enable Git Gateway**. This authenticates with your Git host and generates an API access token. In this case, we're leaving the **Roles** field blank, which means any logged in user may access Static CMS. For information on changing this, check the [Netlify Identity documentation](https://www.netlify.com/docs/identity/).
|
||||
|
||||
### Add the Netlify Identity Widget
|
||||
|
||||
@ -261,7 +264,7 @@ With the backend set to handle authentication, now you need a frontend interface
|
||||
|
||||
Add this to the `<head>` of your CMS index page at `/admin/index.html`, as well as the `<head>` of your site's main index page. Depending on how your site generator is set up, this may mean you need to add it to the default template, or to a "partial" or "include" template. If you can find where the site stylesheet is linked, that's probably the right place. Alternatively, you can include the script in your site using Netlify's [Script Injection](https://www.netlify.com/docs/inject-analytics-snippets/) feature.
|
||||
|
||||
When a user logs in with the Netlify Identity widget, an access token directs to the site homepage. In order to complete the login and get back to the CMS, redirect the user back to the `/admin/` path. To do this, add the following script before the closing `body` tag of your site's main index page:
|
||||
When a user logs in with the Netlify Identity widget, an access token directs to the site homepage. In order to complete the login and get back to Static CMS, redirect the user back to the `/admin/` path. To do this, add the following script before the closing `body` tag of your site's main index page:
|
||||
|
||||
```html
|
||||
<script>
|
||||
@ -279,7 +282,7 @@ When a user logs in with the Netlify Identity widget, an access token directs to
|
||||
|
||||
Note: This example script requires modern JavaScript and does not work on IE11. For legacy browser support, use function expressions (`function () {}`) in place of the arrow functions (`() => {}`), or use a transpiler such as [Babel](https://babeljs.io/).
|
||||
|
||||
## Accessing the CMS
|
||||
## Accessing Static CMS
|
||||
|
||||
Your site CMS is now fully configured and ready for login!
|
||||
|
||||
|
||||
@ -45,11 +45,12 @@ In this example, we pull the `admin/index.html` file from a public CDN.
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<link rel="stylesheet" hef="https://unpkg.com/@staticcms/app@^2.0.0-beta.1/dist/main.css" />
|
||||
<title>Content Manager</title>
|
||||
</head>
|
||||
<body>
|
||||
<!-- Include the script that builds the page and powers Static CMS -->
|
||||
<script src="https://unpkg.com/@staticcms/app@^1.0.0/dist/static-cms-app.js"></script>
|
||||
<script src="https://unpkg.com/@staticcms/app@^2.0.0-beta.1/dist/static-cms-app.js"></script>
|
||||
<script>
|
||||
window.CMS.init();
|
||||
</script>
|
||||
@ -57,7 +58,7 @@ In this example, we pull the `admin/index.html` file from a public CDN.
|
||||
</html>
|
||||
```
|
||||
|
||||
In the code above the `script` is loaded from the `unpkg` CDN. Should there be any issue, `jsDelivr` can be used as an alternative source. Simply set the `src` to `https://cdn.jsdelivr.net/npm/@staticcms/app@%5E1.0.0/dist/static-cms-app.js`
|
||||
In the code above the `script` is loaded from the `unpkg` CDN. Should there be any issue, `jsDelivr` can be used as an alternative source. Simply replace `https://unpkg.com/` with `https://cdn.jsdelivr.net/npm/`
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -91,7 +92,7 @@ The configuration above specifies your backend protocol and your publication bra
|
||||
|
||||
### Media and Public Folders
|
||||
|
||||
Static CMS allows users to upload images directly within the editor. For this to work, the CMS needs to know where to save them. If you already have an `images` folder in your project, you could use its path, possibly creating an `uploads` sub-folder, for example:
|
||||
Static CMS allows users to upload images directly within the editor. For this to work, Static CMS needs to know where to save them. If you already have an `images` folder in your project, you could use its path, possibly creating an `uploads` sub-folder, for example:
|
||||
|
||||
<CodeTabs>
|
||||
```yaml
|
||||
@ -256,7 +257,7 @@ Netlify's Identity and Git Gateway services allow you to manage CMS admin users
|
||||
1. Go to **Settings > Identity**, and select **Enable Identity service**.
|
||||
2. Under **Registration preferences**, select **Open** or **Invite only**. In most cases, you want only invited users to access your CMS, but if you're just experimenting, you can leave it open for convenience.
|
||||
3. If you'd like to allow one-click login with services like Google and GitHub, check the boxes next to the services you'd like to use, under **External providers**.
|
||||
4. Scroll down to **Services > Git Gateway**, and click **Enable Git Gateway**. This authenticates with your Git host and generates an API access token. In this case, we're leaving the **Roles** field blank, which means any logged in user may access the CMS. For information on changing this, check the [Netlify Identity documentation](https://www.netlify.com/docs/identity/).
|
||||
4. Scroll down to **Services > Git Gateway**, and click **Enable Git Gateway**. This authenticates with your Git host and generates an API access token. In this case, we're leaving the **Roles** field blank, which means any logged in user may access Static CMS. For information on changing this, check the [Netlify Identity documentation](https://www.netlify.com/docs/identity/).
|
||||
|
||||
### Add the Netlify Identity Widget
|
||||
|
||||
@ -268,7 +269,7 @@ With the backend set to handle authentication, now you need a frontend interface
|
||||
|
||||
Add this to the `<head>` of your CMS index page at `/admin/index.html`, as well as the `<head>` of your site's main index page. Depending on how your site generator is set up, this may mean you need to add it to the default template, or to a "partial" or "include" template. If you can find where the site stylesheet is linked, that's probably the right place. Alternatively, you can include the script in your site using Netlify's [Script Injection](https://www.netlify.com/docs/inject-analytics-snippets/) feature.
|
||||
|
||||
When a user logs in with the Netlify Identity widget, an access token directs to the site homepage. In order to complete the login and get back to the CMS, redirect the user back to the `/admin/` path. To do this, add the following script before the closing `body` tag of your site's main index page:
|
||||
When a user logs in with the Netlify Identity widget, an access token directs to the site homepage. In order to complete the login and get back to Static CMS, redirect the user back to the `/admin/` path. To do this, add the following script before the closing `body` tag of your site's main index page:
|
||||
|
||||
```html
|
||||
<script>
|
||||
@ -286,7 +287,7 @@ When a user logs in with the Netlify Identity widget, an access token directs to
|
||||
|
||||
Note: This example script requires modern JavaScript and does not work on IE11. For legacy browser support, use function expressions (`function () {}`) in place of the arrow functions (`() => {}`), or use a transpiler such as [Babel](https://babeljs.io/).
|
||||
|
||||
## Accessing the CMS
|
||||
## Accessing Static CMS
|
||||
|
||||
Your site CMS is now fully configured and ready for login!
|
||||
|
||||
|
||||
@ -4,7 +4,10 @@ title: Beta Features
|
||||
weight: 200
|
||||
---
|
||||
|
||||
<Alert severity="error">Features on this page may be broken or may not function as expected. We are working to test and fix the features as well as update the docs. Use at your own risk.</Alert>
|
||||
<Alert severity="error">
|
||||
Features on this page may be broken or may not function as expected. We are working to test and
|
||||
fix the features as well as update the docs. Use at your own risk.
|
||||
</Alert>
|
||||
|
||||
Static CMS runs new functionality in an open beta format from time to time. That means that this functionality is totally available for use, an it might be ready for primetime, but it could break or change without notice.
|
||||
|
||||
@ -12,11 +15,17 @@ Static CMS runs new functionality in an open beta format from time to time. That
|
||||
|
||||
## Folder Collections Path
|
||||
|
||||
See [Folder Collections Path](/docs/collection-types#folder-collections-path).
|
||||
By default Static CMS stores folder collection content under the folder specified in the collection setting. You can now specify an additional `path` template (similar to the `slug` template) to control the content destination.
|
||||
|
||||
This allows saving content in subfolders, e.g. configuring `path: '{{year}}/{{slug}}'` will save the content under `posts/2019/post-title.md`.
|
||||
|
||||
See [Folder Collections Path](/docs/collection-types#folder-collections-path) for more information.
|
||||
|
||||
## Nested Collections
|
||||
|
||||
Seed [Nested Collections](/docs/collection-types#nested-collections).
|
||||
Nested collections is a beta feature that allows a folder collection to show a nested structure of entries and edit the locations of the entries. This feature is useful when you have a complex folder structure and may not want to create separate collections for every directory.
|
||||
|
||||
See [Nested Collections](/docs/collection-types#nested-collections) for more information.
|
||||
|
||||
## Commit Message Templates
|
||||
|
||||
@ -162,7 +171,31 @@ Supported events are `prePublish`, `postPublish`, `preSave` and `postSave`. The
|
||||
CMS.registerEventListener({
|
||||
name: 'preSave',
|
||||
handler: ({ entry }) => {
|
||||
return entry.data.set('title', 'new title');
|
||||
return {
|
||||
...entry,
|
||||
data: {
|
||||
...entry.data,
|
||||
title: 'new title',
|
||||
},
|
||||
};
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## i18n Support
|
||||
|
||||
Static CMS can provide a side by side interface for authoring content in multiple languages. Configuring Static CMS for i18n support requires top level configuration, collection level configuration and field level configuration.
|
||||
|
||||
## Gitea Backend
|
||||
|
||||
For repositories stored on Gitea, the gitea backend allows CMS users to log in directly with their Gitea account. Note that all users must have push access to your content repository for this to work.
|
||||
|
||||
See [Gitea Backend](/docs/gitea-backend) for more information.
|
||||
|
||||
## External Media Library
|
||||
|
||||
Using an external media library allows you to store your media files outside of your git backend. This is helpful if you are trying to store large media files. There are three external media libraries available in beta:
|
||||
|
||||
- [Cloudinary](/docs/cloudinary)
|
||||
- [Netlify Large Media](/docs/netlify-large-media)
|
||||
- [Uploadcare](/docs/uploadcare)
|
||||
|
||||
@ -74,7 +74,7 @@ The following options are used to configure the media library. All options are l
|
||||
|
||||
## Image transformations
|
||||
|
||||
The Cloudinary integration allows images to be transformed in two ways: directly within Static CMS via [Cloudinary's Media Library](#transforming-images-via-media-library), and separately from the CMS via Cloudinary's [dynamic URL's](https://cloudinary.com/documentation/image_transformations#delivering_media_assets_using_dynamic_urls) by [inserting cloudinary urls](#inserting-cloudinary-url-in-page-templates).
|
||||
The Cloudinary integration allows images to be transformed in two ways: directly within Static CMS via [Cloudinary's Media Library](#transforming-images-via-media-library), and separately from Static CMS via Cloudinary's [dynamic URL's](https://cloudinary.com/documentation/image_transformations#delivering_media_assets_using_dynamic_urls) by [inserting cloudinary urls](#inserting-cloudinary-url-in-page-templates).
|
||||
|
||||
### Transforming Images
|
||||
|
||||
|
||||
@ -17,7 +17,7 @@ weight: 9
|
||||
| files or folder | [Collection Files](/docs/collection-types#file-collections)<br />\| [Collection Folder](/docs/collection-types#folder-collections) | | **Requires one of these**: Specifies the collection type and location; details in [Collection Types](/docs/collection-types) |
|
||||
| filter | FilterRule | | _Optional_. Filter for [Folder Collections](/docs/collection-types#folder-collections) |
|
||||
| create | boolean | `false` | _Optional_. **For [Folder Collections](/docs/collection-types#folder-collections) only**<br />`true` - Allows users to create new items in the collection |
|
||||
| hide | boolean | `false` | _Optional_. `true` hides a collection in the CMS UI. Useful when using the relation widget to hide referenced collections |
|
||||
| hide | boolean | `false` | _Optional_. `true` hides a collection in the Static CMS UI. Useful when using the relation widget to hide referenced collections |
|
||||
| delete | boolean | `true` | _Optional_. `false` prevents users from deleting items in a collection |
|
||||
| extension | string | | _Optional_. See [extension](#extension-and-format) below |
|
||||
| format | 'yaml'<br />\| 'yml'<br />\| 'json'<br />\| 'frontmatter'<br />\| 'json-frontmatter'<br />\| 'yaml-frontmatter' | | _Optional_. See [format](#extension-and-format) below |
|
||||
|
||||
@ -188,7 +188,7 @@ collections: [
|
||||
|
||||
### Folder Collections Path <BetaImage />
|
||||
|
||||
By default the CMS stores folder collection content under the folder specified in the collection setting.
|
||||
By default Static CMS stores folder collection content under the folder specified in the collection setting.
|
||||
|
||||
For example configuring `folder: posts` for a collection will save the content under `posts/post-title.md`.
|
||||
|
||||
@ -198,7 +198,7 @@ This allows saving content in subfolders, e.g. configuring `path: '{{year}}/{{sl
|
||||
|
||||
#### Media and Public Folder
|
||||
|
||||
By default the CMS stores media files for all collections under a global `media_folder` directory as specified in the configuration.
|
||||
By default Static CMS stores media files for all collections under a global `media_folder` directory as specified in the configuration.
|
||||
|
||||
When using the global `media_folder` directory any entry field that points to a media file will use the absolute path to the published file as designated by the `public_folder` configuration.
|
||||
|
||||
@ -294,7 +294,7 @@ Supports all of the [`slug` templates](/docs/configuration-options#slug) and:
|
||||
|
||||
### Nested Collections <BetaImage />
|
||||
|
||||
Nested collections is a beta feature that allows a folder collection to show a nested structure of entries and edit the locations of the entries. This feature is useful when you have a complex folder structure and may not want to create separate collections for every directory. As it is in beta, please use with discretion.
|
||||
Nested collections is a beta feature that allows a folder collection to show a nested structure of entries and edit the locations of the entries. This feature is useful when you have a complex folder structure and may not want to create separate collections for every directory.
|
||||
|
||||
Example configuration:
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ Alternatively, you can specify a custom config file using a link tag:
|
||||
|
||||
If you prefer, you can use a javascript file (`admin/config.js`) instead of a yaml file. Simply import the javascript config and pass it into your `CMS.init({ config })` call.
|
||||
|
||||
To see working configuration examples, you can [start from a template](/docs/start-with-a-template) or check out the [CMS demo site](https://demo-staticcms.org/). (No login required: click the login button and the CMS will open.) You can refer to the demo [configuration code](https://github.com/StaticJsCMS/static-cms/blob/main/core/dev-test/config.yml) to see how each option was configured.
|
||||
To see working configuration examples, you can [start from a template](/docs/start-with-a-template) or check out the [CMS demo site](https://demo-staticcms.org/). (No login required: click the login button and Static CMS will open.) You can refer to the demo [configuration code](https://github.com/StaticJsCMS/static-cms/blob/main/core/dev-test/config.yml) to see how each option was configured.
|
||||
|
||||
You can find details about all configuration options below. Note that [YAML syntax](https://en.wikipedia.org/wiki/YAML#Basic_components) allows lists and objects to be written in block or inline style, and the code samples below include a mix of both.
|
||||
|
||||
@ -94,7 +94,7 @@ media_library: {
|
||||
|
||||
## Site URL
|
||||
|
||||
The `site_url` setting should provide a URL to your published site. May be used by the CMS for various functionality. Used together with a collection's `preview_path` to create links to live content.
|
||||
The `site_url` setting should provide a URL to your published site. May be used by Static CMS for various functionality. Used together with a collection's `preview_path` to create links to live content.
|
||||
|
||||
**Example:**
|
||||
|
||||
@ -111,7 +111,7 @@ site_url: 'https://your-site.com',
|
||||
|
||||
## Display URL
|
||||
|
||||
When the `display_url` setting is specified, the CMS UI will include a link in the fixed area at the top of the page, allowing content authors to easily return to your main site. The text of the link consists of the URL with the protocol portion (e.g., `https://your-site.com`).
|
||||
When the `display_url` setting is specified, the Static CMS UI will include a link in the fixed area at the top of the page, allowing content authors to easily return to your main site. The text of the link consists of the URL with the protocol portion (e.g., `https://your-site.com`).
|
||||
|
||||
Defaults to `site_url`.
|
||||
|
||||
@ -130,7 +130,7 @@ display_url: 'https://your-site.com',
|
||||
|
||||
## Custom Logo
|
||||
|
||||
When the `logo_url` setting is specified, the CMS UI will change the logo displayed at the top of the login page, allowing you to brand the CMS with your own logo. `logo_url` is assumed to be a URL to an image file.
|
||||
When the `logo_url` setting is specified, the Static CMS UI will change the logo displayed at the top of the login page, allowing you to brand Static CMS with your own logo. `logo_url` is assumed to be a URL to an image file.
|
||||
|
||||
**Example:**
|
||||
|
||||
@ -147,7 +147,7 @@ logo_url: 'https://your-site.com/images/logo.svg',
|
||||
|
||||
## Locale
|
||||
|
||||
The CMS locale. Defaults to `en`.
|
||||
Static CMS locale. Defaults to `en`.
|
||||
|
||||
Other languages than English must be registered manually.
|
||||
|
||||
|
||||
@ -58,11 +58,11 @@ The react component that renders the control. It receives the following props:
|
||||
| duplicate | function | Specifies if that field is an i18n duplicate |
|
||||
| hidden | function | Specifies if that field should be hidden |
|
||||
| locale | string<br />\| undefined | The current locale of the editor |
|
||||
| mediaPaths | object | Key/value object of control IDs (passed to the media library) mapping to media paths |
|
||||
| clearMediaControl | function | Clears a control ID's value from the internal store |
|
||||
| openMediaLibrary | function | Opens the media library popup. See [Open Media Library](#open-media-library) |
|
||||
| removeInsertedMedia | function | Removes draft media for a give control ID |
|
||||
| removeMediaControl | function | Clears a control ID completely from the internal store |
|
||||
| mediaPaths | object | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead. Will be removed in v3.0.0.</Deprecated> Key/value object of control IDs (passed to the media library) mapping to media paths |
|
||||
| clearMediaControl | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead. Will be removed in v3.0.0.</Deprecated> Clears a control ID's value from the internal store |
|
||||
| openMediaLibrary | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead. Will be removed in v3.0.0.</Deprecated> Opens the media library popup. See [Open Media Library](#open-media-library) |
|
||||
| removeInsertedMedia | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead. Will be removed in v3.0.0.</Deprecated> Removes draft media for a give control ID |
|
||||
| removeMediaControl | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead. Will be removed in v3.0.0.</Deprecated> Clears a control ID completely from the internal store |
|
||||
| query | function | Runs a search on another collection. See [Query](#query) |
|
||||
| i18n | object | The current i18n settings |
|
||||
| t | function | Translates a given key to the current locale |
|
||||
@ -70,6 +70,8 @@ The react component that renders the control. It receives the following props:
|
||||
|
||||
#### Open Media Library
|
||||
|
||||
<Alert severity="error">Deprecated. Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead. Will be removed in v3.0.0.</Alert>
|
||||
|
||||
`openMediaLibrary` allows you to open up the media library popup. It accepts the following props:
|
||||
|
||||
| Param | Type | Default | Description |
|
||||
@ -397,7 +399,11 @@ const FileControl = ({ collection, field, value, entry, onChange }) => {
|
||||
onChange(path);
|
||||
};
|
||||
|
||||
const handleOpenMediaLibrary = useMediaInsert(value, { collection, field, controlID }, handleChange);
|
||||
const handleOpenMediaLibrary = useMediaInsert(
|
||||
value,
|
||||
{ collection, field, controlID },
|
||||
handleChange,
|
||||
);
|
||||
|
||||
const assetSource = useMediaAsset(value, collection, field, entry);
|
||||
|
||||
@ -430,7 +436,11 @@ const FileControl: FC<WidgetControlProps<string, MyField>> = ({
|
||||
onChange(path);
|
||||
};
|
||||
|
||||
const handleOpenMediaLibrary = useMediaInsert(internalValue, { collection, field, controlID }, onChange);
|
||||
const handleOpenMediaLibrary = useMediaInsert(
|
||||
internalValue,
|
||||
{ collection, field, controlID },
|
||||
onChange,
|
||||
);
|
||||
|
||||
const assetSource = useMediaAsset(value, collection, field, entry);
|
||||
|
||||
|
||||
@ -4,9 +4,9 @@ title: Examples
|
||||
weight: 110
|
||||
---
|
||||
|
||||
Do you have a great, open source example? Submit a pull request to this page!
|
||||
Do you have a great, open source example? Submit a pull request to [this page](https://github.com/StaticJsCMS/static-cms/blob/main/packages/docs/content/docs/examples.mdx)!
|
||||
|
||||
<div class="non-props-table" />
|
||||
<div className="non-props-table" />
|
||||
|
||||
| Example | Tools | Type | Source | More info |
|
||||
| ---------------------------------------------------------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
|
||||
@ -29,7 +29,6 @@ backend:
|
||||
api_root: https://gitea.example.com/api/v1 # API url of your Gitea instance
|
||||
# optional, defaults to main
|
||||
# branch: main
|
||||
|
||||
```
|
||||
|
||||
```js
|
||||
|
||||
@ -5,8 +5,8 @@ beta: true
|
||||
weight: 30
|
||||
---
|
||||
|
||||
The CMS can provide a side by side interface for authoring content in multiple languages.
|
||||
Configuring the CMS for i18n support requires top level configuration, collection level configuration and field level configuration.
|
||||
Static CMS can provide a side by side interface for authoring content in multiple languages.
|
||||
Configuring Static CMS for i18n support requires top level configuration, collection level configuration and field level configuration.
|
||||
|
||||
### Top level configuration
|
||||
|
||||
|
||||
@ -17,7 +17,7 @@ At its core, Static CMS is an open-source React app that acts as a wrapper for t
|
||||
|
||||
## Find out more
|
||||
|
||||
- Get a feel for the UI in the [demo site](https://demo.staticcms.org/). (No login required. Click the login button to go straight to the CMS editor UI.)
|
||||
- Get a feel for the UI in the [demo site](https://demo.staticcms.org/). (No login required. Click the login button to go straight to the Static CMS editor UI.)
|
||||
- [Start with a template](/docs/start-with-a-template/) to make a Static CMS-enabled site of your own.
|
||||
- Configure your existing site by following a [tutorial](/docs/add-to-your-site/) or checking [configuration options](/docs/configuration-options).
|
||||
- Ask questions and share ideas in the Static CMS [community chat](/chat).
|
||||
|
||||
@ -4,7 +4,9 @@ title: How to Upgrade to v2
|
||||
weight: 101
|
||||
---
|
||||
|
||||
<Alert severity="warning">This guide is a work in progress and subject to change before the final `v2.0.0` release.</Alert>
|
||||
<Alert severity="warning">
|
||||
This guide is a work in progress and subject to change before the final `v2.0.0` release.
|
||||
</Alert>
|
||||
|
||||
Static CMS v2 introduces a brand new UI and an updated media library. In this guide, we will walk you through the steps for upgrading to Static CMS v2.
|
||||
|
||||
@ -198,3 +200,15 @@ collections:
|
||||
|
||||
- `summary_fields` property added to [collection configuration](/docs/collection-overview) to allow customization of the table view. This works with the new [field preview](/docs/custom-previews).
|
||||
- New widget control property: `forSingleList`. It specifies if the widget is within a singleton `list` widget (string array, number array, etc)
|
||||
|
||||
## Deprecations
|
||||
|
||||
In the Widget Control component property, the following properties have been deprecated. They will be removed in `v3.0.0`.
|
||||
|
||||
| Param | Type | Description |
|
||||
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| mediaPaths | object | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Key/value object of control IDs (passed to the media library) mapping to media paths |
|
||||
| clearMediaControl | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Clears a control ID's value from the internal store |
|
||||
| openMediaLibrary | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Opens the media library popup. See [Open Media Library](#open-media-library) |
|
||||
| removeInsertedMedia | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Removes draft media for a give control ID |
|
||||
| removeMediaControl | function | <Deprecated>Use [useMediaInsert](/docs/custom-widgets#interacting-with-the-media-library) instead.</Deprecated> Clears a control ID completely from the internal store |
|
||||
|
||||
@ -1,125 +0,0 @@
|
||||
---
|
||||
group: Migration
|
||||
title: Netlify CMS Migration Guide
|
||||
weight: 190
|
||||
---
|
||||
|
||||
Static CMS is a fork of Netlify CMS. Many changes have been made, some big, some small. If you are coming from Netlify CMS, here is the list items to watch out for while migrating.
|
||||
|
||||
## How to Migrate
|
||||
|
||||
To migrate, simply replace Netlify CMS with Static CMS, then address the changes below.
|
||||
|
||||
### CDN
|
||||
|
||||
Netlify CMS:
|
||||
|
||||
```html
|
||||
<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
|
||||
```
|
||||
|
||||
Static CMS:
|
||||
|
||||
```html
|
||||
<script src="https://unpkg.com/@staticcms/app@^1.0.0/dist/static-cms-app.js"></script>
|
||||
```
|
||||
|
||||
### Bundling
|
||||
|
||||
```bash
|
||||
# Uninstall Netlify CMS
|
||||
npm uninstall netlify-cms-app
|
||||
npm uninstall netlify-cms-core
|
||||
|
||||
# Install Static CMS
|
||||
npm install @staticcms/core
|
||||
```
|
||||
|
||||
#### Change your imports
|
||||
|
||||
Netlify CMS:
|
||||
|
||||
```js
|
||||
import CMS from 'netlify-cms-app'
|
||||
```
|
||||
|
||||
Static CMS:
|
||||
|
||||
```js
|
||||
import CMS from '@staticcms/core';
|
||||
```
|
||||
|
||||
## Changes
|
||||
- React `18.2.0` is now the minimum supported React version. If you are using Static CMS through a CDN, this comes bundled.
|
||||
- [Moment](https://momentjs.com/) has been dropped as the date library used. Instead we are now using [date-fns](https://date-fns.org/). Date formats in your configuration will need to be updated. See [format docs](https://date-fns.org/v2.29.3/docs/format).
|
||||
- CMS must be explicitly initiated now by calling `CMS.init()`
|
||||
- Passing a config to `CMS.init()` will now completely override `config.yml` (they are now exclusive), instead of being merged with `config.yml`
|
||||
- A [new markdown editor](/docs/widget-markdown) has been added. It comes with a new [shortcode](/docs/widget-markdown#shortcodes) system, old editor components no longer work.
|
||||
- The `sortable_fields` configuration option has been slightly changed, as we now allow a [default sorting option](/docs/collection-overview#sortable_fields).
|
||||
<br /><br />Netlify CMS:
|
||||
```yaml
|
||||
sortable_fields:
|
||||
- field1
|
||||
- field2
|
||||
```
|
||||
<br />Static CMS:
|
||||
```yaml
|
||||
sortable_fields:
|
||||
fields:
|
||||
- field1
|
||||
- field2
|
||||
```
|
||||
<br />
|
||||
- Support in the List Widget for the `field` property has been dropped. A single field in the `fields` property [achieves the same behavior](/docs/widget-list).
|
||||
- Custom widget creation has changed slightly. React class components have been deprecated. Widgets should all be [functional components](https://reactjs.org/docs/components-and-props.html#function-and-class-components) now. There have also been changes to how custom widgets are registered and the properties passed to the controls and previews. See [custom widgets](/docs/custom-widgets) for full details.
|
||||
|
||||
## Deprecated and Removed Features
|
||||
- Dropped the following beta features from Netlify CMS.
|
||||
- GraphQL support for GitHub and GitLab
|
||||
- Remark plugins (new markdown editor has its own plugin system)
|
||||
- Dynamic Default Values
|
||||
- Custom Mount Element
|
||||
- Dropped support for AssetStore integration
|
||||
- Dropped support for Azure backend
|
||||
- All deprecated features were removed
|
||||
- `date` widget has been removed
|
||||
- `datetime` widget
|
||||
- `dateFormat` has been removed (Use `date_format` instead)
|
||||
- `timeFormat` has been removed (Use `time_format` instead)
|
||||
- Gitlab, Client-Side Implicit Grant has been removed
|
||||
- `createClass` is deprecated, [functional components](https://reactjs.org/docs/components-and-props.html#function-and-class-components) should be used instead. Basic react hooks are provided as globals now.
|
||||
- `getAsset` is deprecated, the new `useMediaAsset` hook should be used instead. See [Interacting With The Media Library](/docs/custom-widgets#interacting-with-the-media-library).
|
||||
|
||||
## Beta Features
|
||||
|
||||
All beta features from Netlify CMS that were kept, remain in beta and may not fully function in their current state. Please [submit an issue](https://github.com/StaticJsCMS/static-cms/issues) for any bugs you find.
|
||||
|
||||
## Platform Changes
|
||||
|
||||
### Gatsby
|
||||
|
||||
If you are using Gatsby you will need to change out your CMS plugin.
|
||||
|
||||
```bash
|
||||
# Uninstall Netlify CMS plugin
|
||||
npm uninstall gatsby-plugin-netlify-cms
|
||||
|
||||
# Install Static CMS plugin
|
||||
npm install gatsby-plugin-static-cms
|
||||
```
|
||||
|
||||
## Local Development Changes
|
||||
|
||||
If you are using the local backend you will need to switch the proxy server package you are using.
|
||||
|
||||
Netlify CMS:
|
||||
|
||||
```bash
|
||||
npx netlify-cms-proxy-server
|
||||
```
|
||||
|
||||
Static CMS:
|
||||
|
||||
```bash
|
||||
npx @staticcms/proxy-server
|
||||
```
|
||||
@ -49,7 +49,7 @@ After clicking one of those buttons, authenticate with GitHub and choose a repos
|
||||
|
||||
2. Wait for the deployment to complete, then click the link to accept the invite. Your site will open with a prompt to create a password.
|
||||
|
||||
3. Enter a password, sign in, and you'll go to the CMS. (For future visits, you can go straight to `<yoursiteaddress.com>/admin/`.)
|
||||
3. Enter a password, sign in, and you'll go to Static CMS. (For future visits, you can go straight to `<yoursiteaddress.com>/admin/`.)
|
||||
|
||||
Try adding and editing posts, or changing the content of the Products page. When you save, the changes are pushed immediately to your Git repository, triggering a build on Netlify, and updating the content on your site. Check out the configuration code by visiting your site repo.
|
||||
|
||||
|
||||
@ -58,8 +58,6 @@ const EditorControl: FC<WidgetControlProps<string, HtmlField>> = ({
|
||||
field, // Typed as a HtmlField
|
||||
value, // Typed as string | null | undefined
|
||||
onChange, // Typed to accept string | null | undefined
|
||||
openMediaLibrary,
|
||||
mediaPaths
|
||||
}) => {
|
||||
...
|
||||
};
|
||||
|
||||
@ -12,14 +12,14 @@ If you are using a package manager like Yarn or NPM, use their standard procedur
|
||||
|
||||
## CDN
|
||||
|
||||
If you are using the CMS through a CDN like Unpkg, then that depends on the version tag you are using. You can find the version tag in the `/admin/index.html` file of your site.
|
||||
If you are using Static CMS through a CDN like Unpkg, then that depends on the version tag you are using. You can find the version tag in the `/admin/index.html` file of your site.
|
||||
|
||||
- (Recommended) If you use `^1.0.0`, the CMS does all updates except major versions automatically.
|
||||
- It upgrades to `1.0.1`, `1.1.0`, `1.1.1`.
|
||||
- (Recommended) If you use `^2.0.0`, Static CMS does all updates except major versions automatically.
|
||||
- It upgrades to `2.0.1`, `2.1.0`, `2.1.1`.
|
||||
- It does not upgrade to `2.0.0` or higher.
|
||||
- It does not upgrade to beta versions.
|
||||
|
||||
- If you use `~1.0.0`, the CMS will do only patch updates automatically.
|
||||
- It upgrades `1.0.1`, `1.0.2`.
|
||||
- It does not upgrade to `1.1.0` or higher.
|
||||
- If you use `~2.0.0`, Static CMS will do only patch updates automatically.
|
||||
- It upgrades `2.0.1`, `2.0.2`.
|
||||
- It does not upgrade to `2.1.0` or higher.
|
||||
- It does not upgrade beta versions.
|
||||
|
||||
@ -7,7 +7,7 @@ beta: true
|
||||
|
||||
Uploadcare is a sleek service that allows you to upload files without worrying about maintaining a growing collection — more of an asset store than a library. Just upload when you need to, and the files are hosted on their CDN. They provide image processing controls from simple cropping and rotation to filters and face detection, and a lot more. You can check out Uploadcare's full feature set on their [website](https://uploadcare.com/).
|
||||
|
||||
The Uploadcare media library integration for Static CMS allows you to use Uploadcare as your media handler within the CMS itself. It's available by default as of our 2.1.0 release, and works in tandem with the existing file and image widgets, so using it only requires creating an Uploadcare account and updating your Static CMS configuration.
|
||||
The Uploadcare media library integration for Static CMS allows you to use Uploadcare as your media handler within Static CMS itself. It's available by default as of our 2.1.0 release, and works in tandem with the existing file and image widgets, so using it only requires creating an Uploadcare account and updating your Static CMS configuration.
|
||||
|
||||
**Please make sure that Static CMS is updated to 2.1.0 or greater before proceeding.**
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ weight: 19
|
||||
|
||||
The markdown widget provides a full fledged text editor allowing users to format text with features such as headings and blockquotes. Users can change their editing view with a handy toggle button.
|
||||
|
||||
_Please note:_ If you want to use your markdown editor to fill a markdown file contents after its frontmatter, you'll have to name the field `body` so the CMS recognizes it and saves the file accordingly.
|
||||
_Please note:_ If you want to use your markdown editor to fill a markdown file contents after its frontmatter, you'll have to name the field `body` so Static CMS recognizes it and saves the file accordingly.
|
||||
|
||||
## Widget Options
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ Widgets define the data type and interface for entry fields. Static CMS comes wi
|
||||
|
||||
Widgets are specified as collection fields in the Static CMS `config` file. Note that [YAML syntax](https://en.wikipedia.org/wiki/YAML#Basic_components) allows lists and objects to be written in block or inline style, and the code samples below include a mix of both.
|
||||
|
||||
To see working examples of all of the built-in widgets, try making a 'Kitchen Sink' collection item on the [CMS demo site](https://demo.staticcms.org/). (No login required: click the login button and the CMS will open.) You can refer to the demo [configuration code](https://github.com/StaticJsCMS/static-cms/blob/main/dev-test/config.yml) to see how each field was configured.
|
||||
To see working examples of all of the built-in widgets, try making a 'Kitchen Sink' collection item on the [CMS demo site](https://demo.staticcms.org/). (No login required: click the login button and Static CMS will open.) You can refer to the demo [configuration code](https://github.com/StaticJsCMS/static-cms/blob/main/dev-test/config.yml) to see how each field was configured.
|
||||
|
||||
## Available Widgets
|
||||
|
||||
|
||||
27
packages/docs/src/components/docs/components/Alert.tsx
Normal file
27
packages/docs/src/components/docs/components/Alert.tsx
Normal file
@ -0,0 +1,27 @@
|
||||
import MuiAlert from '@mui/material/Alert';
|
||||
|
||||
import type { AlertProps } from '@mui/material/Alert';
|
||||
|
||||
const Alert = ({ children, ...props }: AlertProps) => {
|
||||
return (
|
||||
<MuiAlert
|
||||
{...props}
|
||||
sx={{
|
||||
borderRadius: '12px',
|
||||
lineHeight: '1.5rem',
|
||||
fontSize: '16px',
|
||||
wordBreak: 'break-word',
|
||||
'& p': {
|
||||
marginBottom: 0,
|
||||
lineHeight: '1.5rem',
|
||||
fontSize: '16px',
|
||||
wordBreak: 'break-word',
|
||||
},
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</MuiAlert>
|
||||
);
|
||||
};
|
||||
|
||||
export default Alert;
|
||||
29
packages/docs/src/components/docs/components/Deprecated.tsx
Normal file
29
packages/docs/src/components/docs/components/Deprecated.tsx
Normal file
@ -0,0 +1,29 @@
|
||||
import Typography from '@mui/material/Typography';
|
||||
|
||||
import type { FC, ReactNode } from 'react';
|
||||
|
||||
interface DeprecatedProps {
|
||||
children?: ReactNode;
|
||||
}
|
||||
|
||||
const Deprecated: FC<DeprecatedProps> = ({ children }) => {
|
||||
return (
|
||||
<Typography
|
||||
variant="body2"
|
||||
color="error.main"
|
||||
component="div"
|
||||
sx={{
|
||||
display: 'block',
|
||||
lineHeight: 1.5,
|
||||
fontFamily: 'Consolas,Menlo,Monaco,Andale Mono,Ubuntu Mono,monospace',
|
||||
fontSize: '13px',
|
||||
fontWeight: 700,
|
||||
fontStyle: 'italic',
|
||||
}}
|
||||
>
|
||||
Deprecated.{children ? <> {children}</> : null}
|
||||
</Typography>
|
||||
);
|
||||
};
|
||||
|
||||
export default Deprecated;
|
||||
@ -1,13 +1,19 @@
|
||||
import Alert from '@mui/material/Alert';
|
||||
import { styled, useTheme } from '@mui/material/styles';
|
||||
import { MDXRemote } from 'next-mdx-remote';
|
||||
import { serialize } from 'next-mdx-remote/serialize';
|
||||
import remarkGfm from 'remark-gfm';
|
||||
|
||||
import BetaImage from '../../components/docs/BetaImage';
|
||||
import DocsContent from '../../components/docs/DocsContent';
|
||||
import DocsLeftNav from '../../components/docs/DocsLeftNav';
|
||||
import DocsRightNav from '../../components/docs/DocsRightNav';
|
||||
import Alert from '../../components/docs/components/Alert';
|
||||
import Anchor from '../../components/docs/components/Anchor';
|
||||
import Blockquote from '../../components/docs/components/Blockquote';
|
||||
import CodeTabs from '../../components/docs/components/CodeTabs';
|
||||
import Deprecated from '../../components/docs/components/Deprecated';
|
||||
import Template from '../../components/docs/components/Template';
|
||||
import Templates from '../../components/docs/components/Templates';
|
||||
import Header1 from '../../components/docs/components/headers/Header1';
|
||||
import Header2 from '../../components/docs/components/headers/Header2';
|
||||
import Header3 from '../../components/docs/components/headers/Header3';
|
||||
@ -19,11 +25,6 @@ import TableBody from '../../components/docs/components/table/TableBody';
|
||||
import TableBodyCell from '../../components/docs/components/table/TableBodyCell';
|
||||
import TableHead from '../../components/docs/components/table/TableHead';
|
||||
import TableHeaderCell from '../../components/docs/components/table/TableHeaderCell';
|
||||
import Template from '../../components/docs/components/Template';
|
||||
import Templates from '../../components/docs/components/Templates';
|
||||
import DocsContent from '../../components/docs/DocsContent';
|
||||
import DocsLeftNav from '../../components/docs/DocsLeftNav';
|
||||
import DocsRightNav from '../../components/docs/DocsRightNav';
|
||||
import Page from '../../components/layout/Page';
|
||||
import { fetchDocsContent, getSearchablePages } from '../../lib/docs';
|
||||
|
||||
@ -133,6 +134,7 @@ const Docs = ({
|
||||
Template,
|
||||
Templates,
|
||||
BetaImage,
|
||||
Deprecated,
|
||||
}}
|
||||
/>
|
||||
</DocsContent>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user