diff --git a/docs/docs/deploy-gatsby.md b/docs/docs/deploy-gatsby.md index 654511fea83c3..5450b2c8c7c16 100644 --- a/docs/docs/deploy-gatsby.md +++ b/docs/docs/deploy-gatsby.md @@ -4,11 +4,30 @@ title: "Deploying Gatsby" ## Tutorials for deploying on different static site hosts +* [Netlify](/docs/deploy-gatsby/#netlify) * [S3/Cloudfront](/docs/deploy-gatsby/#amazon-s3-and-cloudfront) * [GitHub Pages](/docs/deploy-gatsby/#github-pages) * [GitLab Pages](/docs/deploy-gatsby/#gitlab-pages) * [Heroku](/docs/deploy-gatsby/#heroku) +## Netlify + +Netlify is an excellent option for deploying Gatsby sites. Netlify is a unified +platform that automates your code to create high-performant, easily maintainable +sites and web apps. They provide continuous deployment (Git-triggered builds), +an intelligent, global CDN, full DNS (including custom domains), automated +HTTPS, asset acceleration, and a lot more. + +Their free tier includes unlimited personal and commercial projects, HTTPS, +continuous deployment from public or private repos and more. + +### Deploying to Netlify + +To deploy your Gatsby site to Netlify, go to the [create a new +site](https://app.netlify.com/start) page, select your project repo from GitHub, +GitLab, or Bitbucket, and follow the prompts. + + ## Amazon S3 and Cloudfront If you decide to host your Gatsby site on S3 with Cloudfront as CDN, you should diff --git a/docs/docs/netlify-cms.md b/docs/docs/netlify-cms.md new file mode 100644 index 0000000000000..33e904bbb298c --- /dev/null +++ b/docs/docs/netlify-cms.md @@ -0,0 +1,189 @@ +--- +title: Netlify CMS +--- + +In this guide, we'll walk through setting up a site with content management using [Netlify +CMS](https://github.com/netlify/netlify-cms). + +Netlify CMS is an open source, single page app written in React that lets you edit content and data +files in your Git repository. Storing raw content right in the static site repository is an ideal +approach, allowing both code and content to be versioned together, but that requires +non-technical editors to interact with a service like GitHub. Netlify CMS was created specifically +to bridge this gap, providing a solid interface that works well for technical and non-technical +users alike, and interacts with your static site repository via API so that every change results in +a commit. + +A primary focus of Netlify CMS is to work well with static site generators like Gatsby. Installation +typically requires just an index.html file and a YAML configuration file, but we're going to +leverage the Gatsby plugin for Netlify CMS to automatically install and build the CMS along with a +static site. + +_Note: this guide uses the Gatsby Hello World starter to provide a very basic understanding of how +Netlify CMS can work with your Gatsby site. If you get stuck, compare your code to the [example +project](https://github.com/erquhart/gatsby-netlify-cms-example). If you'd like to start with a full +blown template, check out +[gatsby-starter-netlify-cms](https://github.com/AustinGreen/gatsby-starter-netlify-cms)._ + +### Setup + +First, open a new terminal window and run the following to create a new site. This will create a new +directory called `netlify-cms-tutorial` that contains the starter site, but you can change +"netlify-cms-tutorial" in the command below to be whatever you like. + +```shell +gatsby new netlify-cms-tutorial https://github.com/gatsbyjs/gatsby-starter-hello-world +``` + +Now move into the newly created directory and install the Gatsby plugin for Netlify CMS: + +```shell +cd netlify-cms-tutorial && npm install --save gatsby-plugin-netlify-cms +``` + +Gatsby plugins are registered in a file called `gatsby-config.js` in the site root. Create that file +if it's not already there, and add the following to register the Netlify CMS plugin: + +```javascript +module.exports = { + plugins: [ + `gatsby-plugin-netlify-cms`, + ], +} +``` + +Finally, you'll need to add a configuration file for the CMS itself. The plugin you just installed +will take care of creating the Netlify CMS app and outputting it to "/admin/index.html", so you'll +want to put the configuration file in that same directory. + +Still in the root directory, add a "static" folder. Gatsby will copy everything in the static folder +into the output, so we'll want to place the Netlify CMS configuration file as +"static/admin/config.yml". Let's create a test configuration now - add this to your new +`config.yml`: + +```yaml +backend: + name: test-repo + +media_folder: static/assets + +collections: + - name: blog + label: Blog + folder: blog + create: true + fields: + - { name: path, label: Path } + - { name: date, label: Date, widget: date } + - { name: title, label: Title } +``` + +Then in your terminal run `gatsby develop` to start the Gatsby development server. Once the server +is running, it will print the address to open for viewing. Its typically `localhost:8000`. Open that +in a browser and you should see the text "Hello World" in the top left corner. Now navigate to +`/admin/` - so if your site is at `localhost:8000`, go to `localhost:8000/admin/`. The trailing +slash is required! + +You should now be viewing your Netlify CMS instance. You defined a "blog" collection in the +configuration above, so you can create new blogs, but Netlify CMS will only store them in memory - +if you refresh, your changes won't be there. + +### Saving to a Git Repo + +To save your content in a Git repo, the repo will need to be hosted on a service like GitHub, and +you'll need a way to authenticate with that service so Netlify CMS can make changes through the +service's API. For most services, including GitHub, authentication will require a server. +[Netlify](https://www.netlify.com), the web platform company that started Netlify CMS, provides a +very simple (and free) solution for this. + +This is also a good time to consider that Netlify CMS is meant to work in production, as a part of +your static site, and that the site would ideally be running on continuous deployment (every time +the repo changes, the website is rebuilt and redeployed automatically). When used in production, +Netlify CMS and your Gatsby site will stay synced, since your site will be rebuilt after each +change, whereas running Netlify CMS locally requires you to pull changes from your remote each time +to see them in the locally served site. + +#### Pushing to GitHub + +We can resolve all of the above handily by pushing our test site to GitHub and deploying it to +Netlify. First, initialize your Gatsby project as a Git repo, and push it up to GitHub. If you need +help on this part, check out GitHub's +[guide](https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/). + +#### Deploying to Netlify + +Now you can publish your Gatsby site straight from GitHub to Netlify from the [create site +page](https://app.netlify.com/start) - the proper build command for Gatsby will be provided +automatically, just select your GitHub repo and go with the default options. Once you connect your +GitHub repo to Netlify, deployment will begin. Note that the first deployment could take a few +minutes since a lot of things aren't cached yet. Subsequent deploys will be faster. + +Once deployment is complete you'll be able to view your live site, which should look the same as it +did locally. + +#### Authenticating with GitHub + +Netlify CMS will need to authenticate with GitHub to save your content changes to your repo. As +mentioned above, this requires a server, and Netlify handles that aspect for you. First you'll need +to add your deployed site as an OAuth application in your GitHub settings - just follow the steps in +the [Netlify +docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider). This +will allow scripts running on your deployed site, such as Netlify CMS, to access your GitHub +account via API. + +Lastly, we'll need to change your Netlify CMS config file with your GitHub repo information so that +changes are saved there. Replace the `backend` value in your `static/admin/config.yml` to match the +example below. Note that the `repo` value must be your GitHub username followed immediately by a +forward slash, and then your repository name. If your username is "test-user" and your repo name is +"test-repo", you would put "test-user/test-repo". + +```yaml +backend: + name: github + repo: your-username/your-repo-name +``` + +Now you can save the config.yml file, commit the change, and push it to your GitHub repo. + +#### Making Changes + +Alright - you're all set to make changes in Netlify CMS and see them as commits in your GitHub repo! +Open Netlify CMS on your deployed site at `/admin/`, allow access to GitHub when the permissions +window pops up (check for blocked pop ups if you don't see it), and try creating and publishing a +new blog post. Once you've done that, you'll find a new "blog" directory in your GitHub repo +containing a Markdown file with your blog post content! + +This is the basic function of Netlify CMS - providing a comfortable editing experience and +outputting raw content files to a Git repository. You've probably noticed that, even though the file +was created in your repo, it's not anywhere on your site. That's because Netlify CMS doesn't go +beyond creating the raw content - its able to work with almost any static site generator because it +allows the generator to determine how to build the raw content into something useful, whether for a +website, mobile app, or something else entirely. + +Right now, Gatsby doesn't know the new blog post is there, and it isn't set up to process Markdown. +Let's fix that. + +### Processing Netlify CMS Output with Gatsby + +Gatsby can be configured to process Markdown by following the [Adding Markdown +Pages](https://www.gatsbyjs.org/docs/adding-markdown-pages/) guide in the docs. Our `config.yml` +file for Netlify CMS is set up to use the same fields used in the guide, so you can follow the +instructions to the letter and should work fine. **Note:** When configuring the +`gatsby-source-filesystem` plugin in the Adding Markdown Pages Guide, the path to your markdown +files should be `${__dirname}/blog`. + +Once this is complete, get your changes committed and pushed up to your GitHub repo and check your +site! The new blog post will be at whatever you entered in the path field when creating your blog +entry in Netlify CMS. If you followed the example in Gatsby's Adding Markdown Pages guide and used +"/blog/my-first-blog", then your blog post would be at +"your-site-name.netlify.com/blog/my-first-blog". + +### Wrapping Up + +This was a very basic example meant to help you understand how Netlify CMS works with Gatsby. As +mentioned in the beginning of this guide, if you got stuck, you can compare your code to the +[example repo](https://github.com/erquhart/gatsby-netlify-cms-example), which is a working example +created by following this guide. You can also reach out to the Netlify CMS community on +[Gitter](https://gitter.im/netlify/netlifycms). Lastly, if you'd like to move into a more complete +boilerplate to get going with Gatsby and Netlify CMS, you can clone and deploy the [official Gatsby +Netlify CMS starter](https://github.com/AustinGreen/gatsby-starter-netlify-cms) to Netlify with [one +click](https://app.netlify.com/start/deploy?repository=https://github.com/AustinGreen/gatsby-starter-netlify-cms&stack=cms). diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md index 0b875b2b4c552..5eadda3b40154 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -87,6 +87,7 @@ root. * [gatsby-plugin-jss](/packages/gatsby-plugin-jss/) * [gatsby-plugin-manifest](/packages/gatsby-plugin-manifest/) * [gatsby-plugin-netlify](/packages/gatsby-plugin-netlify/) +* [gatsby-plugin-netlify-cms](/packages/gatsby-plugin-netlify-cms/) * [gatsby-plugin-nprogress](/packages/gatsby-plugin-nprogress/) * [gatsby-plugin-offline](/packages/gatsby-plugin-offline/) * [gatsby-plugin-preact](/packages/gatsby-plugin-preact/) diff --git a/packages/gatsby-plugin-netlify-cms/.gitignore b/packages/gatsby-plugin-netlify-cms/.gitignore new file mode 100644 index 0000000000000..8c9686624a187 --- /dev/null +++ b/packages/gatsby-plugin-netlify-cms/.gitignore @@ -0,0 +1,3 @@ +/*.js +!index.js +yarn.lock diff --git a/packages/gatsby-plugin-netlify-cms/.npmignore b/packages/gatsby-plugin-netlify-cms/.npmignore new file mode 100644 index 0000000000000..e771d2c9fa299 --- /dev/null +++ b/packages/gatsby-plugin-netlify-cms/.npmignore @@ -0,0 +1,34 @@ +# Logs +logs +*.log + +# Runtime data +pids +*.pid +*.seed + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage + +# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (http://nodejs.org/api/addons.html) +build/Release + +# Dependency directory +# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git +node_modules +*.un~ +yarn.lock +src +flow-typed +coverage +decls +examples diff --git a/packages/gatsby-plugin-netlify-cms/README.md b/packages/gatsby-plugin-netlify-cms/README.md new file mode 100644 index 0000000000000..399612830411b --- /dev/null +++ b/packages/gatsby-plugin-netlify-cms/README.md @@ -0,0 +1,71 @@ +# gatsby-plugin-netlify-cms + +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](https://netlifycms.org). + +## Install + +`npm install --save gatsby-plugin-netlify-cms` + +## How to use + +Add the Netlify CMS plugin in your `gatsby-config.js`: + +```javascript +plugins: [ + `gatsby-plugin-netlify-cms`, +]; +``` + +Then add your Netlify CMS [configuration +file](https://www.netlifycms.org/docs/add-to-your-site/#configuration) in +`static/admin/config.yml`. + +## Configuration + +If you need to customize Netlify CMS, e.g. registering [custom +widgets](https://www.netlifycms.org/docs/custom-widgets/#registerwidget) or +styling the [preview +pane](https://www.netlifycms.org/docs/customization/#registerpreviewstyle), +you'll need to do so in a js module and provide Gatsby with the path to your +module. In `gatsby-config.js`, instead of simply adding the name of the plugin +to the `plugins` array, you'll need to use an object: + +```javascript +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: + +```javascript +// Your module must at least include these three imports +import React from 'react' +import CMS from 'netlify-cms' +import 'netlify-cms/dist/cms.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) +``` + +## Support + +For help with integrating Netlify CMS with Gatsby, check out the community +[Gitter](https://gitter.im/netlify/netlifycms). diff --git a/packages/gatsby-plugin-netlify-cms/index.js b/packages/gatsby-plugin-netlify-cms/index.js new file mode 100644 index 0000000000000..172f1ae6a468c --- /dev/null +++ b/packages/gatsby-plugin-netlify-cms/index.js @@ -0,0 +1 @@ +// noop diff --git a/packages/gatsby-plugin-netlify-cms/package.json b/packages/gatsby-plugin-netlify-cms/package.json new file mode 100644 index 0000000000000..0e28ac9f840c9 --- /dev/null +++ b/packages/gatsby-plugin-netlify-cms/package.json @@ -0,0 +1,28 @@ +{ + "name": "gatsby-plugin-netlify-cms", + "version": "1.0.0", + "description": "A Gatsby plugin which generates the Netlify CMS single page app", + "main": "index.js", + "author": "Shawn Erquhart ", + "scripts": { + "build": "babel src --out-dir . --ignore __tests__", + "watch": "babel -w src --out-dir . --ignore __tests__", + "prepublish": "cross-env NODE_ENV=production npm run build" + }, + "keywords": [ + "gatsby", + "gatsby-plugin", + "netlify", + "netlify-cms" + ], + "license": "MIT", + "dependencies": { + "html-webpack-include-assets-plugin": "^1.0.2", + "html-webpack-plugin": "^2.30.1", + "netlify-cms": "^1.0.1" + }, + "devDependencies": { + "babel-cli": "^6.26.0", + "cross-env": "^5.1.3" + } +} diff --git a/packages/gatsby-plugin-netlify-cms/src/cms.js b/packages/gatsby-plugin-netlify-cms/src/cms.js new file mode 100644 index 0000000000000..4c2687d4208b5 --- /dev/null +++ b/packages/gatsby-plugin-netlify-cms/src/cms.js @@ -0,0 +1,4 @@ +/* eslint-disable no-unused-vars */ +import React from "react" +import CMS from "netlify-cms" +import "netlify-cms/dist/cms.css" diff --git a/packages/gatsby-plugin-netlify-cms/src/gatsby-node.js b/packages/gatsby-plugin-netlify-cms/src/gatsby-node.js new file mode 100644 index 0000000000000..17f79b63f0c71 --- /dev/null +++ b/packages/gatsby-plugin-netlify-cms/src/gatsby-node.js @@ -0,0 +1,34 @@ +const HtmlWebpackPlugin = require(`html-webpack-plugin`) +const HtmlWebpackIncludeAssetsPlugin = require(`html-webpack-include-assets-plugin`) + +exports.modifyWebpackConfig = ( + { config, stage }, + { modulePath = `${__dirname}/cms.js` } +) => { + switch (stage) { + case `develop`: + case `build-javascript`: + config.merge({ + entry: { + cms: modulePath, + }, + plugins: [ + new HtmlWebpackPlugin({ + title: `Content Manager`, + filename: `admin/index.html`, + chunks: [`cms`], + }), + new HtmlWebpackIncludeAssetsPlugin({ + assets: [ + `https://identity.netlify.com/v1/netlify-identity-widget.js`, + ], + append: false, + publicPath: false, + }), + ], + }) + return config + default: + return config + } +} diff --git a/www/src/pages/docs/doc-links.yaml b/www/src/pages/docs/doc-links.yaml index 84bb552e56171..791ec81d23f7c 100644 --- a/www/src/pages/docs/doc-links.yaml +++ b/www/src/pages/docs/doc-links.yaml @@ -44,6 +44,8 @@ link: /docs/environment-variables/ - title: Gatsby on Windows link: /docs/gatsby-on-windows/ + - title: Managing Content with Netlify CMS + link: /docs/netlify-cms/ - title: How Gatsby Works with GitHub Pages link: /docs/how-gatsby-works-with-github-pages/ - title: Migrating from v0 to v1