From fed5dc892bf50451a3c6f9770eccea796af42d35 Mon Sep 17 00:00:00 2001 From: Private Maker Date: Tue, 23 Jan 2024 09:49:20 +0100 Subject: [PATCH 1/3] Update Docs migrate Beta Features - Raw CSS (#7054) --- website/content/docs/beta-features.md | 15 +-------------- website/content/docs/customization.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/website/content/docs/beta-features.md b/website/content/docs/beta-features.md index fea7a8919635..565daa8dc10c 100644 --- a/website/content/docs/beta-features.md +++ b/website/content/docs/beta-features.md @@ -176,19 +176,6 @@ 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 @@ -377,4 +364,4 @@ CMS.registerCustomFormat('yml', 'yml', { fromFile: text => jsYaml.load(text), toFile: value => jsYaml.dump(value), }); -``` \ No newline at end of file +``` 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. From 5623d812b5f8af355d6998c2074693c964eb945a Mon Sep 17 00:00:00 2001 From: Private Maker Date: Tue, 23 Jan 2024 09:50:52 +0100 Subject: [PATCH 2/3] Update Docs: migrate Beta Features - Commit Message Templates (#7055) --- website/content/docs/beta-features.md | 38 ------------------ website/content/docs/configuration-options.md | 40 +++++++++++++++++++ 2 files changed, 40 insertions(+), 38 deletions(-) diff --git a/website/content/docs/beta-features.md b/website/content/docs/beta-features.md index 565daa8dc10c..8fcd59725beb 100644 --- a/website/content/docs/beta-features.md +++ b/website/content/docs/beta-features.md @@ -190,44 +190,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 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. From b4026544279b2c9964068222dba89f5565359dc2 Mon Sep 17 00:00:00 2001 From: Private Maker Date: Tue, 23 Jan 2024 10:14:12 +0100 Subject: [PATCH 3/3] Update Docs migrate Beta Features - Manual Initialization (#7057) Co-authored-by: Martin Jagodic --- website/content/docs/beta-features.md | 65 ----------------- website/content/docs/manual-initialization.md | 69 +++++++++++++++++++ 2 files changed, 69 insertions(+), 65 deletions(-) create mode 100644 website/content/docs/manual-initialization.md diff --git a/website/content/docs/beta-features.md b/website/content/docs/beta-features.md index 8fcd59725beb..53e14f0e671c 100644 --- a/website/content/docs/beta-features.md +++ b/website/content/docs/beta-features.md @@ -110,71 +110,6 @@ 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(...); -``` ## Squash merge GitHub pull requests 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(...); +```