docs: add netlify cms migration guide (#378)

Author: KaneFreeman

package.json

@@ -2,11 +2,11 @@
   "name": "static-cms",
   "private": true,
   "scripts": {
-    "build": "lerna run build",
-    "build:demo": "lerna run build --scope=@staticcms/demo",
-    "dev": "lerna run dev --scope=@staticcms/core",
-    "demo": "lerna run dev --scope=@staticcms/demo",
-    "docs": "lerna run dev --scope=docs",
+    "build": "lerna run build --scope @staticcms/core --scope @staticcms/app",
+    "build:demo": "lerna run build --scope @staticcms/demo",
+    "dev": "lerna run dev --scope @staticcms/core",
+    "demo": "lerna run dev --scope @staticcms/demo",
+    "docs": "lerna run dev --scope docs",
     "format": "lerna run format",
     "lint": "lerna run lint",
     "prepare": "husky install",

packages/docs/content/docs/custom-widgets.mdx

@@ -20,11 +20,11 @@ Register a custom widget.
 
 ```js
 // Using global window object
-CMS.registerWidget(name, control, [preview], [schema]);
+CMS.registerWidget(name, control, [preview], [{ schema }]);
 
 // Using npm module import
 import CMS from '@staticcms/core';
-CMS.registerWidget(name, control, [preview], [schema]);
+CMS.registerWidget(name, control, [preview], [{ schema }]);
 ```
 
 ### Params
@@ -159,7 +159,7 @@ Register widget takes an optional object of options. These options include:
     },
   };
 
-  CMS.registerWidget('categories', CategoriesControl, CategoriesPreview, options: { schema });
+  CMS.registerWidget('categories', CategoriesControl, CategoriesPreview, { schema });
 </script>
 ```
 
@@ -203,6 +203,7 @@ collections: [
   }
 ]
 ```
+
 </CodeTabs>
 
 ## Advanced field validation
@@ -260,3 +261,63 @@ const validator = () => {
   return this.existingPromise;
 };
 ```
+
+## Interacting With The Media Library
+
+If you want to use the media library in your custom widget you will need to use the `useMediaInsert` and `useMediaAsset` hooks.
+
+- `useMediaInsert` - Takes the current url to your media, details about your field (including a unique ID) and a callback method for when new media is uploaded.
+- `useMediaAsset` - Transforms your stored url into a usable url for displaying as a preview.
+
+<CodeTabs>
+
+```js
+import useMediaAsset from '@staticcms/core/lib/hooks/useMediaAsset';
+import useMediaInsert from '@staticcms/core/lib/hooks/useMediaInsert';
+
+const FileControl = ({ collection, field, value, entry, onChange }) => {
+  const handleOpenMediaLibrary = useMediaInsert(
+    value,
+    { field, controlID },
+    onChange,
+  );
+
+  const assetSource = useMediaAsset(value, collection, field, entry);
+
+  return (
+    <>
+      <button type="button" onClick={handleOpenMediaLibrary}>Upload</button>
+      <img role="presentation" src={assetSource} />
+    </>
+  );
+};
+```
+
+```ts
+import useMediaAsset from '@staticcms/core/lib/hooks/useMediaAsset';
+import useMediaInsert from '@staticcms/core/lib/hooks/useMediaInsert';
+
+import type { WidgetControlProps } from '@staticcms/core/interface';
+import type { FC } from 'react';
+
+const FileControl: FC<WidgetControlProps<string, MyField>> =
+  ({ collection, field, value, entry, onChange }) => {
+
+  const handleOpenMediaLibrary = useMediaInsert(
+    internalValue,
+    { field, controlID },
+    onChange,
+  );
+
+  const assetSource = useMediaAsset(value, collection, field, entry);
+
+  return (
+    <>
+      <button type="button" onClick={handleOpenMediaLibrary}>Upload</button>
+      <img role="presentation" src={assetSource} />
+    </>
+  );
+};
+```
+
+</CodeTabs>

packages/docs/content/docs/netlify-cms-migration-guide.mdx

@@ -4,4 +4,34 @@ title: Netlify CMS Migration Guide
 weight: 190
 ---
 
-Guide coming soon on how to migrate your site from Netlify CMS to Static CMS!
+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.
+
+## 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.
+- 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_foramt` 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.

packages/docs/src/components/docs/components/CodeTabs.tsx

@@ -60,6 +60,11 @@ const supportedLanguages: Record<string, CodeLanguage> = {
     grammar: Prism.languages.markdown,
     language: 'markdown',
   },
+  'language-ts': {
+    title: 'Typescript',
+    grammar: Prism.languages.typescript,
+    language: 'typescript',
+  },
 };
 
 interface TabData {