Merge branch 'master' into fix-typo-1

docs/docs/adding-a-list-of-markdown-blog-posts.md

@@ -2,7 +2,80 @@
 title: Adding a List of Markdown Blog Posts
 ---
 
-This is a stub. Help our community expand it.
+Once you have added Markdown pages to your site, you are just one step away from being able to list your posts on a dedicated index page.
 
-Please use the [Gatsby Style Guide](/docs/gatsby-style-guide/) to ensure your
-pull request gets accepted.
+### Creating posts
+
+As described [here](/docs/docs/adding-markdown-pages.md), you will have to create your posts in Markdown files which will look like this:
+
+```md
+---
+path: "/blog/my-first-post"
+date: "2017-11-07"
+title: "My first blog post"
+---
+
+Has anyone heard about GatsbyJS yet?
+```
+
+### Creating the page
+
+The first step will be to create the page which will display your posts, in `src/pages/`. You can for example use `index.js`.
+
+```js
+import React from 'react';
+import PostLink from '../components/post-link'
+
+const IndexPage = ({ data: { allMarkdownRemark: { edges } } }) => {
+ const Posts = edges
+ .filter(edge => !!edge.node.frontmatter.date) // You can filter your posts based on some criteria
+ .map(edge => (
+ <PostLink key={edge.node.id} post={edge.node} />
+ ));
+
+ return <div>{Posts}</div>;
+};
+
+export default IndexPage;
+```
+
+### Creating the GraphQL query
+
+The only thing left to do is to provide the data to your component with a GraphQL query.
+
+```js
+import React from 'react';
+import PostLink from '../components/post-link'
+
+const IndexPage = ({ data: { allMarkdownRemark: { edges } } }) => {
+ const Posts = edges
+ .filter(edge => !!edge.node.frontmatter.date) // You can filter your posts based on some criteria
+ .map(edge => (
+ <PostLink key={edge.node.id} post={edge.node} />
+ ));
+
+ return <div>{Posts}</div>;
+};
+
+export default IndexPage;
+
+export const pageQuery = graphql`
+ query IndexQuery {
+ allMarkdownRemark(sort: { order: DESC, fields: [frontmatter___date] }) {
+ edges {
+ node {
+ id
+ excerpt(pruneLength: 250)
+ frontmatter {
+ date(formatString: "MMMM DD, YYYY")
+ path
+ title
+ }
+ }
+ }
+ }
+ }
+`;
+```
+
+This should get you a page with your posts sorted by descending date. You can further customise the `frontmatter` and the page component to get desired effects!

docs/docs/adding-markdown-pages.md

@@ -141,13 +141,8 @@ exports.createPages = ({ boundActionCreators, graphql }) => {
  ) {
  edges {
  node {
- excerpt(pruneLength: 250)
- html
- id
  frontmatter {
- date
  path
- title
  }
  }
  }

docs/docs/adding-tags-and-categories-to-blog-posts.md

@@ -56,7 +56,7 @@ query IndexQuery {
 
 The query fetches the title and tags for every blog post.
 
-Using this query, we can create an component for a blog front page that lists all posts and their tags.
+Using this query, we can create a component for a blog front page that lists all posts and their tags.
 
 ```jsx
 const IndexPage = ({ data }) => (

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

docs/docs/gatsby-style-guide.md

@@ -65,9 +65,8 @@ two ways:
 If you prefer to write locally before submitting a PR, then follow these steps:
 
 1. Fork this repository
-2. Copy it to your local machine by running the command `git clone`
- `https:/YOUR-GITHUB-USERNAME/guides.git`
-3. Add a remote upstream so git knows where the official Gatsby Guides
+2. Copy your fork to your local machine.
+3. Add a remote upstream so git knows where the official Gatsby
  repository is located by running the command `git remote add upstream`
  _incomplete code here_
 4. Create a new branch for your work with the command `git checkout -b NEW-BRANCH-NAME`. Try to name your branch in a way that describes your
@@ -88,10 +87,9 @@ Finally, if you want to run a version of the guides repository locally, follow
 these steps:
 
 1. Ensure you have the yarn package manager installed `npm install -g yarn`
-2. Fork this repository 👇 `git clone https:/YOUR-GITHUB-USERNAME/guides.git` `cd guides` `yarn install` `yarn run dev`
-
-In this project we are using `yarn` because
-[`Netlify`](https://www.netlify.com/) builds our site with `yarn`.
+2. Install the Gatsby cli `yarn add --global gatsby-cli`
+3. Follow the steps above to fork and clone the Gatsby repo.
+4. Enter the `www` directory where gatsbyjs.org is and install its dependencies `yarn install` then run `gatsby develop`.
 
 ## Article style guide
 

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:/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:/erquhart/gatsby-netlify-cms-example). If you'd like to start with a full
+blown template, check out
+[gatsby-starter-netlify-cms](https:/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:/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:/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:/AustinGreen/gatsby-starter-netlify-cms) to Netlify with [one
+click](https://app.netlify.com/start/deploy?repository=https:/AustinGreen/gatsby-starter-netlify-cms&stack=cms).

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/)

packages/gatsby-plugin-netlify-cms/.gitignore

@@ -0,0 +1,3 @@
+/*.js
+!index.js
+yarn.lock