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.
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:
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.
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:
---
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.
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.
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.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!