diff --git a/website/content/docs/beta-features.md b/website/content/docs/beta-features.md index 46ac0e657660..22dfb736f296 100644 --- a/website/content/docs/beta-features.md +++ b/website/content/docs/beta-features.md @@ -110,85 +110,7 @@ Decap CMS always creates its own DOM element for mounting the application, which You can now provide your own element for Decap CMS to mount in by setting the target element's ID as `nc-root`. If Decap CMS finds an element with this ID during initialization, it will mount within that element instead of creating its own. -## Manual Initialization -Decap CMS can now be manually initialized, rather than automatically loading up the moment you import it. The whole point of this at the moment is to inject configuration into Decap CMS before it loads, bypassing need for an actual Decap CMS `config.yml`. This is important, for example, when creating tight integrations with static site generators. - -Assuming you have the decap-cms package installed to your project, manual initialization works by setting `window.CMS_MANUAL_INIT = true` **before importing the CMS**: - -```js -// This global flag enables manual initialization. -window.CMS_MANUAL_INIT = true -// Usage with import from npm package -import CMS, { init } from 'decap-cms-app' -// Usage with script tag -const { CMS, initCMS: init } = window -/** - * Initialize without passing in config - equivalent to just importing - * Decap CMS the old way. - */ -init() -/** - * Optionally pass in a config object. This object will be merged into - * `config.yml` if it exists, and any portion that conflicts with - * `config.yml` will be overwritten. Arrays will be replaced during merge, - * not concatenated. - * - * For example, the code below contains an incomplete config, but using it, - * your `config.yml` can be missing its backend property, allowing you - * to set this property at runtime. - */ -init({ - config: { - backend: { - name: 'git-gateway', - }, - }, -}) -/** - * Optionally pass in a complete config object and set a flag - * (`load_config_file: false`) to ignore the `config.yml`. - * - * For example, the code below contains a complete config. The - * `config.yml` will be ignored when setting `load_config_file` to false. - * It is not required if the `config.yml` file is missing to set - * `load_config_file`, but will improve performance and avoid a load error. - */ -init({ - config: { - backend: { - name: 'git-gateway', - }, - load_config_file: false, - media_folder: "static/images/uploads", - public_folder: "/images/uploads", - collections: [ - { label: "Blog", name: "blog", folder: "_posts/blog", create: true, fields: [ - { label: "Title", name: "title", widget: "string" }, - { label: "Publish Date", name: "date", widget: "datetime" }, - { label: "Featured Image", name: "thumbnail", widget: "image" }, - { label: "Body", name: "body", widget: "markdown" }, - ]}, - ], - }, -}) -// The registry works as expected, and can be used before or after init. -CMS.registerPreviewTemplate(...); -``` - -## Raw CSS in `registerPreviewStyle` - -`registerPreviewStyle` can now accept a CSS string, in addition to accepting a url. The feature is activated by passing in an object as the second argument, with `raw` set to a truthy value. This is critical for integrating with modern build tooling. Here's an example using webpack: - -```js -/** - * Assumes a webpack project with `sass-loader` and `css-loader` installed. - * Takes advantage of the `toString` method in the return value of `css-loader`. - */ -import CMS from 'decap-cms-app'; -import styles from '!css-loader!sass-loader!../main.scss'; -CMS.registerPreviewStyle(styles.toString(), { raw: true }); -``` ## Squash merge GitHub pull requests @@ -203,44 +125,6 @@ backend: squash_merges: true ``` -## Commit Message Templates - -You can customize the templates used by Decap CMS to generate commit messages by setting the `commit_messages` option under `backend` in your Decap CMS `config.yml`. - -Template tags wrapped in curly braces will be expanded to include information about the file changed by the commit. For example, `{{path}}` will include the full path to the file changed. - -Setting up your Decap CMS `config.yml` to recreate the default values would look like this: - -```yaml -backend: - commit_messages: - create: Create {{collection}} “{{slug}}” - update: Update {{collection}} “{{slug}}” - delete: Delete {{collection}} “{{slug}}” - uploadMedia: Upload “{{path}}” - deleteMedia: Delete “{{path}}” - openAuthoring: '{{message}}' -``` - -Decap CMS generates the following commit types: - -| Commit type | When is it triggered? | Available template tags | -| --------------- | ---------------------------------------- | ----------------------------------------------------------- | -| `create` | A new entry is created | `slug`, `path`, `collection`, `author-login`, `author-name` | -| `update` | An existing entry is changed | `slug`, `path`, `collection`, `author-login`, `author-name` | -| `delete` | An existing entry is deleted | `slug`, `path`, `collection`, `author-login`, `author-name` | -| `uploadMedia` | A media file is uploaded | `path`, `author-login`, `author-name` | -| `deleteMedia` | A media file is deleted | `path`, `author-login`, `author-name` | -| `openAuthoring` | A commit is made via a forked repository | `message`, `author-login`, `author-name` | - -Template tags produce the following output: - -* `{{slug}}`: the url-safe filename of the entry changed -* `{{collection}}`: the name of the collection containing the entry changed -* `{{path}}`: the full path to the file changed -* `{{message}}`: the relevant message based on the current change (e.g. the `create` message when an entry is created) -* `{{author-login}}`: the login/username of the author -* `{{author-name}}`: the full name of the author (might be empty based on the user's profile) ## Image widget file size limit @@ -352,4 +236,3 @@ CMS.registerRemarkPlugin({ settings: { bullet: '-' } }); ``` Note that `netlify-widget-markdown` currently uses `remark@10`, so you should check a plugin's compatibility first. - diff --git a/website/content/docs/configuration-options.md b/website/content/docs/configuration-options.md index 35782c960809..ba629b5812bf 100644 --- a/website/content/docs/configuration-options.md +++ b/website/content/docs/configuration-options.md @@ -26,6 +26,46 @@ The `backend` option specifies how to access the content for your site, includin **Note**: no matter where you access Decap CMS — whether running locally, in a staging environment, or in your published site — it will always fetch and commit files in your hosted repository (for example, on GitHub), on the branch you configured in your Decap CMS config.yml file. This means that content fetched in the admin UI will match the content in the repository, which may be different from your locally running site. It also means that content saved using the admin UI will save directly to the hosted repository, even if you're running the UI locally or in staging. If you want to have your local CMS write to a local repository, try the `local_backend` setting, [currently in beta](/docs/beta-features/#working-with-a-local-git-repository). +### Commit Message Templates + +You can customize the templates used by Decap CMS to generate commit messages by setting the `commit_messages` option under `backend` in your Decap CMS `config.yml`. + +Template tags wrapped in curly braces will be expanded to include information about the file changed by the commit. For example, `{{path}}` will include the full path to the file changed. + +Setting up your Decap CMS `config.yml` to recreate the default values would look like this: + +```yaml +backend: + commit_messages: + create: Create {{collection}} “{{slug}}” + update: Update {{collection}} “{{slug}}” + delete: Delete {{collection}} “{{slug}}” + uploadMedia: Upload “{{path}}” + deleteMedia: Delete “{{path}}” + openAuthoring: '{{message}}' +``` + +Decap CMS generates the following commit types: + +| Commit type | When is it triggered? | Available template tags | +| --------------- | ---------------------------------------- | ----------------------------------------------------------- | +| `create` | A new entry is created | `slug`, `path`, `collection`, `author-login`, `author-name` | +| `update` | An existing entry is changed | `slug`, `path`, `collection`, `author-login`, `author-name` | +| `delete` | An existing entry is deleted | `slug`, `path`, `collection`, `author-login`, `author-name` | +| `uploadMedia` | A media file is uploaded | `path`, `author-login`, `author-name` | +| `deleteMedia` | A media file is deleted | `path`, `author-login`, `author-name` | +| `openAuthoring` | A commit is made via a forked repository | `message`, `author-login`, `author-name` | + +Template tags produce the following output: + +* `{{slug}}`: the url-safe filename of the entry changed +* `{{collection}}`: the name of the collection containing the entry changed +* `{{path}}`: the full path to the file changed +* `{{message}}`: the relevant message based on the current change (e.g. the `create` message when an entry is created) +* `{{author-login}}`: the login/username of the author +* `{{author-name}}`: the full name of the author (might be empty based on the user's profile) + + ## Publish Mode By default, all entries created or edited in the Decap CMS are committed directly into the main repository branch. diff --git a/website/content/docs/customization.md b/website/content/docs/customization.md index 829340fd64d3..446cf380baf1 100644 --- a/website/content/docs/customization.md +++ b/website/content/docs/customization.md @@ -50,6 +50,21 @@ body { } ``` +## Raw CSS in `registerPreviewStyle` + +`registerPreviewStyle` can now accept a CSS string, in addition to accepting a url. The feature is activated by passing in an object as the second argument, with `raw` set to a truthy value. This is critical for integrating with modern build tooling. Here's an example using webpack: + +```js +/** + * Assumes a webpack project with `sass-loader` and `css-loader` installed. + * Takes advantage of the `toString` method in the return value of `css-loader`. + */ +import CMS from 'decap-cms-app'; +import styles from '!css-loader!sass-loader!../main.scss'; +CMS.registerPreviewStyle(styles.toString(), { raw: true }); +``` + + ## `registerPreviewTemplate` Registers a template for a folder collection or an individual file in a file collection. diff --git a/website/content/docs/manual-initialization.md b/website/content/docs/manual-initialization.md new file mode 100644 index 000000000000..7d5c7973034e --- /dev/null +++ b/website/content/docs/manual-initialization.md @@ -0,0 +1,69 @@ +--- +title: Manual Initialization +weight: 70 +group: Customization +--- + +Decap CMS can now be manually initialized, rather than automatically loading up the moment you import it. The whole point of this at the moment is to inject configuration into Decap CMS before it loads, bypassing need for an actual Decap CMS `config.yml`. This is important, for example, when creating tight integrations with static site generators. + +Assuming you have the decap-cms package installed to your project, manual initialization works by setting `window.CMS_MANUAL_INIT = true` **before importing the CMS**: + +```js +// This global flag enables manual initialization. +window.CMS_MANUAL_INIT = true +// Usage with import from npm package +import CMS, { init } from 'decap-cms-app' +// Usage with script tag +const { CMS, initCMS: init } = window +/** + * Initialize without passing in config - equivalent to just importing + * Decap CMS the old way. + */ +init() +/** + * Optionally pass in a config object. This object will be merged into + * `config.yml` if it exists, and any portion that conflicts with + * `config.yml` will be overwritten. Arrays will be replaced during merge, + * not concatenated. + * + * For example, the code below contains an incomplete config, but using it, + * your `config.yml` can be missing its backend property, allowing you + * to set this property at runtime. + */ +init({ + config: { + backend: { + name: 'git-gateway', + }, + }, +}) +/** + * Optionally pass in a complete config object and set a flag + * (`load_config_file: false`) to ignore the `config.yml`. + * + * For example, the code below contains a complete config. The + * `config.yml` will be ignored when setting `load_config_file` to false. + * It is not required if the `config.yml` file is missing to set + * `load_config_file`, but will improve performance and avoid a load error. + */ +init({ + config: { + backend: { + name: 'git-gateway', + }, + load_config_file: false, + media_folder: "static/images/uploads", + public_folder: "/images/uploads", + collections: [ + { label: "Blog", name: "blog", folder: "_posts/blog", create: true, fields: [ + { label: "Title", name: "title", widget: "string" }, + { label: "Publish Date", name: "date", widget: "datetime" }, + { label: "Featured Image", name: "thumbnail", widget: "image" }, + { label: "Body", name: "body", widget: "markdown" }, + ]}, + ], + }, +}) +// The registry works as expected, and can be used before or after init. +CMS.registerPreviewTemplate(...); +```