Thursday, 16 August, 2018 UTC
Summary
We’ve previously explored the philosophy behind Gatsby as well as some of its major features, so it’s about time we jump in and start building websites with it. We’ll explore here how to get started with Gatsby v2.
Gatsby v2 is still in beta at the time of this writing, so tread carefully.
Gatsby CLI The very first step to get started will be to install the Gatsby CLI globally:
$ yarn global add gatsby-cli # or, using npm: $ npm install gatsby-cli -g And now we can use the
gatsby new utility to initiate a new project:$ gatsby new my-site This will create a
my-site directory with the following starting file structure:├── /.cache ├── .gitignore ├── .prettierrc ├── LICENSE ├── README.md ├── gatsby-browser.js ├── gatsby-config.js ├── gatsby-node.js ├── gatsby-ssr.js ├── /node_modules ├── package-lock.json ├── package.json ├── /src └── yarn.lock Now you can
cd into your new site’s directory and start working on it by running gatsby develop:$ cd my-site $ gatsby develop And now you can visit your site at
http://localhost:8000/:The default Gatsby starter site is used when using the
gatsby new command without extra arguments, but we can also use a number of other officially supported or community starters. There currently is 3 official starters: gatsby-starter-default, gatsby-starter-hello-world and gatsby-starter-blog.You can also have a look at the different community starters here.
Our ultimate goal starting with this post will be to build a fully-featured blog using Gatsby, so instead of using the default starter like we did in the previous step, let’s use the gatsby-starter-blog. We’ll call our blog Alligator Chronicles:
gatsby new alligator-chronicles https://github.com/gatsbyjs/gatsby-starter-blog#v2 The configuration for a Gatsby site is specified in the
gatsby-config.js file. Our starter already populates that file with a default config, but now we can change it up a bit:gatsby-config.js
module.exports = { siteMetadata: { title: 'Alligator Chronicles', description: 'The chronicles of a somewhat lonely Alligator.', siteUrl: 'https://alligator-chronicles.com/', }, plugins: [ ... ], } We’ve changed the site’s metadata to suit our needs and also removed the
pathPrefix, which is useful only if our blog was not meant to live at the root of the domain. We’ve kept the plugin configuration the same, as this is something we’ll explore in future posts. Note that you'll want to restart your local server after making changes to the gatsby-config.js file or creating new pages.
Adding a New Post With the way in which the official blog starter is setup, we can add posts by creating a new directory for each post in the project’s /src/page directory and then an
index.md file with the content of the post.For example, add a new post to our site:
/src/pages/lonely-gator/index.md
--- title: Lonely Gator date: '2018-08-16' --- I'm just a lonely gator, going about my life. **Croc croc**! For the most part our blog posts are just simple mardown files. The only difference is the addition of some frontmatter metadata at the top of the file wrapped with — which provides data that will be available to query against using GraphQL.
Building Later, when our blog is really to go live, we’ll make use of the
gatsby build command to compile all of the assets and build the static files:$ gatsby build This adds the ready-to-be-deployed assets to a
public directory in the root of our project. The content of that folder can simply be uploaded to a static hosting provider for our blog to be live.Once your site is built, you can also use
gatsby serve to serve the built and optimized version of your site at http://localhost:9000/:$ gatsby serve This can be useful to test out your site just as it will be on a live host.
Wrapping Up Now that we’ve scratched the surface and initiated a new Gatsby site, we’ve set the stage to start digging deeper in future posts and start with the nuts and bolts of building our blog.
In the meantime, I encourage you to give a read to the official v2 documentation.