@talves/gatsby-plugin-netlify-cms
v2.5.0
Published
A plugin to use NetlifyCMS with React as peer dep
Downloads
40
Maintainers
Readme
Gatsby Plugin for Netlify CMS
A Gatsby plugin to setup Netlify CMS without having to make a static route.
Note: This version requires the use of netlify-cms-app
as a dependency rather than netlify-cms
. Replace gatsby-plugin-netlify-cms
with @talves/gatsby-plugin-netlify-cms
.
Overview
Automatically generates an admin/index.html
with a default Netlify CMS implementation.
Netlify CMS is a React single page app for editing git based content via API. Its built for non-technical and technical editors alike, and its super easy to install and configure. For more details, check out the docs site.
Install
npm install --save netlify-cms gatsby-plugin-netlify-cms
How to use
Add the Netlify CMS plugin in your gatsby-config.js
:
plugins: [`gatsby-plugin-netlify-cms`]
Then add your Netlify CMS configuration
file in
static/admin/config.yml
.
Options
Netlify CMS can be configured via the plugin options below. You can learn about how to pass options to plugins in the Gatsby docs.
buildCMS
(optional, default: true
)
Set this to false
If you want to bypass the build of Netlify CMS. The plugin will build the cms by default to the modulePath
, otherwise you will need to submit the built code to static/${modulePath}
and push to your repository. This will cut down on your Gatsby build time and you would build local when you make changes that affect the CMS build. Examples are; changing preview components, making data changes to config schema, registering a new widget or updating the CMS to a new version.
modulePath
(optional, default: undefined
)
If you need to customize Netlify CMS, e.g. registering custom
widgets or
styling the preview
pane,
you'll need to do so in a JavaScript module and provide Gatsby with the path to
your module via the modulePath
option. Any styles imported by this module (or
by the modules that it imports, all the way down the chain) are automatically
applied to the editor preview pane by the plugin.
plugins: [
{
resolve: `gatsby-plugin-netlify-cms`,
options: {
/**
* One convention is to place your Netlify CMS customization code in a
* `src/cms` directory.
*/
modulePath: `${__dirname}/src/cms/cms.js`,
},
},
]
The js module might look like this:
/**
* The default export of `netlify-cms` is an object with all of the Netlify CMS
* extension registration methods, such as `registerWidget` and
* `registerPreviewTemplate`.
*/
import CMS from "netlify-cms"
/**
* Any imported styles will automatically be applied to the editor preview
* pane, there is no need to use `registerPreviewStyle` for imported styles.
* All of the example imports below would result in styles being applied to the
* preview pane.
*/
import "module-that-imports-styles.js"
import "styles.scss"
import "../other-styles.css"
/**
* Let's say you've created widget and preview components for a custom image
* gallery widget in separate files:
*/
import ImageGalleryWidget from "./image-gallery-widget.js"
import ImageGalleryPreview from "./image-gallery-preview.js"
/**
* Register the imported widget:
*/
CMS.registerWidget(`image-gallery`, ImageGalleryWidget, ImageGalleryPreview)
manualInit
(optional, default: false
)
Set this to true
If you need to manually initialize Netlify CMS. The plugin will take care of setting window.CMS_MANUAL_INIT
to true
:
plugins: [
{
resolve: `gatsby-plugin-netlify-cms`,
options: {
manualInit: true,
},
},
]
The js module might look like this:
import CMS, { init } from "netlify-cms"
/**
* Optionally pass in a config object. This object will be merged into `config.yml` if it exists
*/
init({
config: {
backend: {
name: "git-gateway",
},
},
})
enableIdentityWidget
(optional, default: true
)
enableIdentityWidget
is true
by default, allowing Netlify
Identity to be used without
configuration, but you may need to disable it in some cases, such as when using
a Netlify CMS backend that conflicts. This is currently known to be the case
when using the GitLab backend, but only when using implicit OAuth.
plugins: [
{
resolve: `gatsby-plugin-netlify-cms`,
options: {
enableIdentityWidget: true,
},
},
]
publicPath
(optional, default: "admin"
)
Customize the path to Netlify CMS on your Gatsby site.
htmlTitle
(optional, default: Content Manager
)
Customize the value of the title
tag in your CMS HTML (shows in the browser
bar).
Example
Here is the plugin with example values for all options (note that no option is required):
plugins: [
{
resolve: `gatsby-plugin-netlify-cms`,
options: {
modulePath: `path/to/custom/script.js`, // default: undefined
enableIdentityWidget: true,
publicPath: `admin`,
htmlTitle: `Content Manager`,
},
},
]