Migrating my blog to Gatsby (Part 2 of Gatsby migration)

Migrating a blog to Gatsby

• Preparing an existing blog for migration

• Configuring Gatsby to handle markdown

• Querying your markdown files using GraphQL

• Adding custom data to the generated GraphQL schema

• Turning all your markdown files into static pages

Preparing your existing blog for migration

Clean up your source repo

.
├── content
│   ├── _drafts
│   │   └── [ Draft markdown files ... ]
│   └── _posts
│       └── [ Post markdown files ... ]
└── hexo.bak
    └── [ All my old hexo related files ... ]

Set up Gatsby

npm install -g gatsby-cli   # Install gatsby CLI
gatsby new temp-gatsby-files # Initialize gatsby in a temp directory
cp -R temp-gatsby-files/* ./ # Copy all the files into your root directory
rm -rf temp-gatsby-files     # Remove the temp directory

.
├── content
│   └── [ Markdown files ... ]
├── public
│   └── index.html
├── src
│   ├── layouts
│   │   ├── index.css
│   │   └── index.js
│   └── pages
│       ├── 404.js
│       ├── index.js
│       └── page-2.js
├── gatsby-config.js
└── package.json

npm run develop

Rendering a list of posts

Customizing the layout

src/layouts/index.js

Customizing the landing page

src/pages/index.js

Querying data with GraphQL

Querying the file system

yarn add gatsby-source-filesystem

{
  resolve: 'gatsby-source-filesystem',
  options: {
    name: 'posts', // Name this source
    path: path.resolve('./content/_posts'), // Tell it where to find the files
  },
}

query {
  allFile {
    edges {
      node {
        ext
        name
      }
    }
  }
}

Handling Markdown

yarn add gatsby-transformer-remark

{
  resolve: 'gatsby-transformer-remark',
  options: {
    plugins: [],
  },
}

query {
  allMarkdownRemark {
    edges {
      node {
        html
      }
    }
  }
}

query {
  allMarkdownRemark {
    edges {
      node {
        frontmatter {
          title
        }
        html
      }
    }
  }
}

Getting GraphQL data into your components

// src/pages/index.js
import React from 'react';

export default class BlogIndex extends React.Component {
  render() {
    // Handle graphql errors
    if (this.props.errors && this.props.errors.length) {
      this.props.errors.forEach(({ message }) => {
        console.error(`BlogIndex render errr: ${message}`);
      });
      return <h1>Errors found: Check the console for details</h1>;
    }

    return (
      <div>
        <h2>Some things I wrote</h2>
        {this.props.data.allMarkdownRemark.edges.map(({ node }, i) => (
          <a key={i}>{node.frontmatter.title}</a>
        ))}
      </div>
    );
  }
}

export const pageQuery = graphql`
  query {
    allMarkdownRemark {
      edges {
        node {
          frontmatter { title }
        }
      }
    }
  }
`;

• In the render method we first check for errors, and return early if any are found

• If no error are found we render a link for each item in the array: this.props.data.allMarkdownRemark.edges

• We export a pageQuery variable that is constructed using the magic graphql global

{this.props.data.allMarkdownRemark.edges.map(({ node }, i) => (
  <a key={i}>{node.frontmatter.title}</a>
))}

export const pageQuery = graphql`
  query {
    allMarkdownRemark {
      edges {
        node {
          frontmatter { title }
        }
      }
    }
  }
`;

Linking to blog posts

But the links don't link anywhere... where's that href?

import React from 'react';
import Link from 'gatsby-link';

export default class BlogIndex extends React.Component {
  render() {
    // Handle graphql errors
    if (this.props.errors && this.props.errors.length) {
      this.props.errors.forEach(({ message }) => {
        console.error(`BlogIndex render errr: ${message}`);
      });
      return <h1>Errors found: Check the console for details</h1>;
    }

    return (
      <div>
        <h2>Some things I wrote</h2>
        {this.props.data.allMarkdownRemark.edges.map(({ node }, i) => (
          <Link to={/* ??? */} key={i}>{node.frontmatter.title}</Link>
        ))}
      </div>
    );
  }
}

But what does it link to? What is the URL of each blog post?

export const pageQuery = graphql`
  query {
    allMarkdownRemark {
      edges {
        node {
          frontmatter {
            title
            url # <-------------  New!
          }
        }
      }
    }
  }
`;

{this.props.data.allMarkdownRemark.edges.map(({ node }, i) => (
  <Link to={node.frontmatter.url} key={i}>{node.frontmatter.title}</Link>
))}

---
title: My Post
path: my-post
---

# My post

But what if the URL for each post is NOT in the frontmatter?

Adding custom data to the GraphQL schema

// gatsby-node.js
const { GraphQLString } = require('graphql');

const getURL = (node) => {
  /* See the source link below for implementation */
};

exports.setFieldsOnGraphQLNodeType = ({ type }) => {
  if (type.name !== 'MarkdownRemark') {
    return {};
  }

  return Promise.resolve({
    url: {
      type: GraphQLString,
      resolve: node => getURL(node),
    },
  });
};

Source code for gatsby-node.js here.

Generating pages from markdown files

Generating custom pages

// gatsby-node.js

// .. other stuff from before...

exports.createPages = ({ boundActionCreators }) => {
  const { createPage } = boundActionCreators;
  const postTemplate = path.resolve('./src/templates/custom-page.js');

  // Create a custom page!
  createPage({
    path: `/my-custom-page/`,
    component: postTemplate,
    context: {} // Context will be passed in to the page query as graphql variables
  });
};

• path is required. This is the path that your page will have as a generated HTML file. It's the URL of your final page.

• component is also required. It's the file containing the react component that will be used to render this particular page.

• context is optional but I've included it here because it will be important soon. This lets you pass data down to the react component specified in the component option as well as the pageQuery (if any).

// Get all markdown files
// Call create page for each one
markdownFiles.forEach(post => {
  createPage({
    path: post.url,
    component: './src/templates/post.js',
    context: {
      id: post.id,
    },
  });
});

// NOTE: I'm using async/await to simplify the code since it's now natively supported
// in Node 8.x. This means that our function will return a promise
exports.createPages = async ({ graphql, boundActionCreators }) => {
  const { createPage } = boundActionCreators;
  const postTemplate = path.resolve('./src/templates/post.js');

  // Using async await. Query will likely be very similar to your pageQuery in index.js
  const result = await graphql(`
    query {
      allMarkdownRemark {
        edges {
          node { id url }
        }
      }
    }
  `);

  if (result.errors) {
    console.log(result.errors);
    throw new Error('Things broke, see console output above');
  }

  // Create blog posts pages.
  result.data.allMarkdownRemark.edges.forEach(({ node }) => {
    createPage({
      path: node.url,
      component: postTemplate,
      context: { // Context will be passed in to the page query as graphql vars
        id: node.id,
      },
    });
  });
};

Rendering individual posts

• Create the postTemplate file referenced in createPages above

• Export your template component as the default export

• Add a pageQuery that will fetch the blog post to render

// src/templates/post.js
import React from 'react';

export default class BlogPost extends React.Component {
  render() {
    const post = this.props.data.markdownRemark;

    return (
      <div className='Post'>
        <h1>{post.frontmatter.title}</h1>
        <div dangerouslySetInnerHTML={{ __html: post.html }} className='content' />
      </div>
    );
  }
}

// NOTE: The $id var is passed in via context when calling createPage in gatsby-node.js
export const pageQuery = graphql`
  query PostById($id: String!) {
  	markdownRemark(id: { eq: $id }) {
      frontmatter {
        title
      }
      html
  	}
  }
`;

Where to go from here

• Add previous and next buttons to each post

• Create a remark plugin to add custom block types

• Aggregate tags from your frontmatter and generate pages for all posts of a specific tag

Closing thoughts

• Extensible through a powerful plugin API.

• Supports arbitrary data sources that can be easily queried using GraphQL.

• Splits your code automatically so you don't have to worry about bundle size increasing as a function of the number of pages you render.