|
| 1 | +--- |
| 2 | +title: Netlify CMS |
| 3 | +--- |
| 4 | + |
| 5 | +In this guide, we'll walk through setting up a site with content management using [Netlify |
| 6 | +CMS](https://github.com/netlify/netlify-cms). |
| 7 | + |
| 8 | +Netlify CMS is an open source, single page app written in React that lets you edit content and data |
| 9 | +files in your Git repository. Storing raw content right in the static site repository is an ideal |
| 10 | +approach, allowing both code and content to be versioned together, but that requires |
| 11 | +non-technical editors to interact with a service like GitHub. Netlify CMS was created specifically |
| 12 | +to bridge this gap, providing a solid interface that works well for technical and non-technical |
| 13 | +users alike, and interacts with your static site repository via API so that every change results in |
| 14 | +a commit. |
| 15 | + |
| 16 | +A primary focus of Netlify CMS is to work well with static site generators like Gatsby. Installation |
| 17 | +typically requires just an index.html file and a YAML configuration file, but we're going to |
| 18 | +leverage the Gatsby plugin for Netlify CMS to automatically install and build the CMS along with a |
| 19 | +static site. |
| 20 | + |
| 21 | +_Note: this guide uses the Gatsby Hello World starter to provide a very basic understanding of how |
| 22 | +Netlify CMS can work with your Gatsby site. If you get stuck, compare your code to the [example |
| 23 | +project](https://github.com/erquhart/gatsby-netlify-cms-example). If you'd like to start with a full |
| 24 | +blown template, check out |
| 25 | +[gatsby-starter-netlify-cms](https://github.com/AustinGreen/gatsby-starter-netlify-cms)._ |
| 26 | + |
| 27 | +### Setup |
| 28 | + |
| 29 | +First, open a new terminal window and run the following to create a new site. This will create a new |
| 30 | +directory called `netlify-cms-tutorial` that contains the starter site, but you can change |
| 31 | +"netlify-cms-tutorial" in the command below to be whatever you like. |
| 32 | + |
| 33 | +```shell |
| 34 | +gatsby new netlify-cms-tutorial https://github.com/gatsbyjs/gatsby-starter-hello-world |
| 35 | +``` |
| 36 | + |
| 37 | +Now move into the newly created directory and install the Gatsby plugin for Netlify CMS: |
| 38 | + |
| 39 | +```shell |
| 40 | +cd netlify-cms-tutorial && npm install --save gatsby-plugin-netlify-cms |
| 41 | +``` |
| 42 | + |
| 43 | +Gatsby plugins are registered in a file called `gatsby-config.js` in the site root. Create that file |
| 44 | +if it's not already there, and add the following to register the Netlify CMS plugin: |
| 45 | + |
| 46 | +```javascript |
| 47 | +module.exports = { |
| 48 | + plugins: [ |
| 49 | + `gatsby-plugin-netlify-cms`, |
| 50 | + ], |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +Finally, you'll need to add a configuration file for the CMS itself. The plugin you just installed |
| 55 | +will take care of creating the Netlify CMS app and outputting it to "/admin/index.html", so you'll |
| 56 | +want to put the configuration file in that same directory. |
| 57 | + |
| 58 | +Still in the root directory, add a "static" folder. Gatsby will copy everything in the static folder |
| 59 | +into the output, so we'll want to place the Netlify CMS configuration file as |
| 60 | +"static/admin/config.yml". Let's create a test configuration now - add this to your new |
| 61 | +`config.yml`: |
| 62 | + |
| 63 | +```yaml |
| 64 | +backend: |
| 65 | + name: test-repo |
| 66 | + |
| 67 | +media_folder: static/assets |
| 68 | + |
| 69 | +collections: |
| 70 | + - name: blog |
| 71 | + label: Blog |
| 72 | + folder: blog |
| 73 | + create: true |
| 74 | + fields: |
| 75 | + - { name: path, label: Path } |
| 76 | + - { name: date, label: Date, widget: date } |
| 77 | + - { name: title, label: Title } |
| 78 | +``` |
| 79 | +
|
| 80 | +Then in your terminal run `gatsby develop` to start the Gatsby development server. Once the server |
| 81 | +is running, it will print the address to open for viewing. Its typically `localhost:8000`. Open that |
| 82 | +in a browser and you should see the text "Hello World" in the top left corner. Now navigate to |
| 83 | +`/admin/` - so if your site is at `localhost:8000`, go to `localhost:8000/admin/`. The trailing |
| 84 | +slash is required! |
| 85 | + |
| 86 | +You should now be viewing your Netlify CMS instance. You defined a "blog" collection in the |
| 87 | +configuration above, so you can create new blogs, but Netlify CMS will only store them in memory - |
| 88 | +if you refresh, your changes won't be there. |
| 89 | + |
| 90 | +### Saving to a Git Repo |
| 91 | + |
| 92 | +To save your content in a Git repo, the repo will need to be hosted on a service like GitHub, and |
| 93 | +you'll need a way to authenticate with that service so Netlify CMS can make changes through the |
| 94 | +service's API. For most services, including GitHub, authentication will require a server. |
| 95 | +[Netlify](https://www.netlify.com), the web platform company that started Netlify CMS, provides a |
| 96 | +very simple (and free) solution for this. |
| 97 | + |
| 98 | +This is also a good time to consider that Netlify CMS is meant to work in production, as a part of |
| 99 | +your static site, and that the site would ideally be running on continuous deployment (every time |
| 100 | +the repo changes, the website is rebuilt and redeployed automatically). When used in production, |
| 101 | +Netlify CMS and your Gatsby site will stay synced, since your site will be rebuilt after each |
| 102 | +change, whereas running Netlify CMS locally requires you to pull changes from your remote each time |
| 103 | +to see them in the locally served site. |
| 104 | + |
| 105 | +#### Pushing to GitHub |
| 106 | + |
| 107 | +We can resolve all of the above handily by pushing our test site to GitHub and deploying it to |
| 108 | +Netlify. First, initialize your Gatsby project as a Git repo, and push it up to GitHub. If you need |
| 109 | +help on this part, check out GitHub's |
| 110 | +[guide](https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/). |
| 111 | + |
| 112 | +#### Deploying to Netlify |
| 113 | + |
| 114 | +Now you can publish your Gatsby site straight from GitHub to Netlify from the [create site |
| 115 | +page](https://app.netlify.com/start) - the proper build command for Gatsby will be provided |
| 116 | +automatically, just select your GitHub repo and go with the default options. Once you connect your |
| 117 | +GitHub repo to Netlify, deployment will begin. Note that the first deployment could take a few |
| 118 | +minutes since a lot of things aren't cached yet. Subsequent deploys will be faster. |
| 119 | + |
| 120 | +Once deployment is complete you'll be able to view your live site, which should look the same as it |
| 121 | +did locally. |
| 122 | + |
| 123 | +#### Authenticating with GitHub |
| 124 | + |
| 125 | +Netlify CMS will need to authenticate with GitHub to save your content changes to your repo. As |
| 126 | +mentioned above, this requires a server, and Netlify handles that aspect for you. First you'll need |
| 127 | +to add your deployed site as an OAuth application in your GitHub settings - just follow the steps in |
| 128 | +the [Netlify |
| 129 | +docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider). This |
| 130 | +will allow scripts running on your deployed site, such as Netlify CMS, to access your GitHub |
| 131 | +account via API. |
| 132 | + |
| 133 | +Lastly, we'll need to change your Netlify CMS config file with your GitHub repo information so that |
| 134 | +changes are saved there. Replace the `backend` value in your `static/admin/config.yml` to match the |
| 135 | +example below. Note that the `repo` value must be your GitHub username followed immediately by a |
| 136 | +forward slash, and then your repository name. If your username is "test-user" and your repo name is |
| 137 | +"test-repo", you would put "test-user/test-repo". |
| 138 | + |
| 139 | +```yaml |
| 140 | +backend: |
| 141 | + name: github |
| 142 | + repo: your-username/your-repo-name |
| 143 | +``` |
| 144 | + |
| 145 | +Now you can save the config.yml file, commit the change, and push it to your GitHub repo. |
| 146 | + |
| 147 | +#### Making Changes |
| 148 | + |
| 149 | +Alright - you're all set to make changes in Netlify CMS and see them as commits in your GitHub repo! |
| 150 | +Open Netlify CMS on your deployed site at `/admin/`, allow access to GitHub when the permissions |
| 151 | +window pops up (check for blocked pop ups if you don't see it), and try creating and publishing a |
| 152 | +new blog post. Once you've done that, you'll find a new "blog" directory in your GitHub repo |
| 153 | +containing a Markdown file with your blog post content! |
| 154 | + |
| 155 | +This is the basic function of Netlify CMS - providing a comfortable editing experience and |
| 156 | +outputting raw content files to a Git repository. You've probably noticed that, even though the file |
| 157 | +was created in your repo, it's not anywhere on your site. That's because Netlify CMS doesn't go |
| 158 | +beyond creating the raw content - its able to work with almost any static site generator because it |
| 159 | +allows the generator to determine how to build the raw content into something useful, whether for a |
| 160 | +website, mobile app, or something else entirely. |
| 161 | + |
| 162 | +Right now, Gatsby doesn't know the new blog post is there, and it isn't set up to process Markdown. |
| 163 | +Let's fix that. |
| 164 | + |
| 165 | +### Processing Netlify CMS Output with Gatsby |
| 166 | + |
| 167 | +Gatsby can be configured to process Markdown by following the [Adding Markdown |
| 168 | +Pages](https://www.gatsbyjs.org/docs/adding-markdown-pages/) guide in the docs. Our `config.yml` |
| 169 | +file for Netlify CMS is set up to use the same fields used in the guide, so you can follow the |
| 170 | +instructions to the letter and should work fine. **Note:** When configuring the |
| 171 | +`gatsby-source-filesystem` plugin in the Adding Markdown Pages Guide, the path to your markdown |
| 172 | +files should be `${__dirname}/blog`. |
| 173 | + |
| 174 | +Once this is complete, get your changes committed and pushed up to your GitHub repo and check your |
| 175 | +site! The new blog post will be at whatever you entered in the path field when creating your blog |
| 176 | +entry in Netlify CMS. If you followed the example in Gatsby's Adding Markdown Pages guide and used |
| 177 | +"/blog/my-first-blog", then your blog post would be at |
| 178 | +"your-site-name.netlify.com/blog/my-first-blog". |
| 179 | + |
| 180 | +### Wrapping Up |
| 181 | + |
| 182 | +This was a very basic example meant to help you understand how Netlify CMS works with Gatsby. As |
| 183 | +mentioned in the beginning of this guide, if you got stuck, you can compare your code to the |
| 184 | +[example repo](https://github.com/erquhart/gatsby-netlify-cms-example), which is a working example |
| 185 | +created by following this guide. You can also reach out to the Netlify CMS community on |
| 186 | +[Gitter](https://gitter.im/netlify/netlifycms). Lastly, if you'd like to move into a more complete |
| 187 | +boilerplate to get going with Gatsby and Netlify CMS, you can clone and deploy the [official Gatsby |
| 188 | +Netlify CMS starter](https://github.com/AustinGreen/gatsby-starter-netlify-cms) to Netlify with [one |
| 189 | +click](https://app.netlify.com/start/deploy?repository=https://github.com/AustinGreen/gatsby-starter-netlify-cms&stack=cms). |
0 commit comments