First Post!

December 3, 2019

This Post is #1!

Might as well start at the beginning.

I've been meaning to set up a blog for some time. There were always three things holding me back: What technology to use, a lack of time, and a name. The last two are still kind of a problem, but at least I have narrowed down the tech stack, so let's talk about that.

Gatsby: Or, How I Learned To Just Pick A Tech Stack Already

I've been working with Gatsby for a few years now, and really liked the concepts behind in. Essentially, it's a tool that makes building performant, statically built, React based applications easy, while providing a wealth of powerful addons for connecting data sources, processing files, and adding interactivity. It's not simply a static site generator (like Jekyll), and as a fullstack React/Node developer, I wanted something that could do more than just show static content. Still, I didn't have the time or inclination to set up a full-blown CMS. Also, I hate full-blown CMSs. A lot. Gatsby makes it easy to start small, and add on incrementally. And, since it's just React, adding interactivity and dynamic content is trivial.

Developer Style

Although I've been writing software professionally for nearly two decades, my actual bachelor's degree is in graphic design, a skill I've used exactly once since graduating. That is to say, my design skills are a bit rusty. Luckily, for me, there are plenty of options out there for the non-artistic developer. A relatively new feature of Gatsby is the introduction of themes. Themes in Gatsby allow nearly any aspect of the tool, including sourcing, transforming, and styling, to be encapsulated in a portable, composable way. In short, a Gatsby theme is like a miniature Gatsby site, including React components, GraphQL queries, CSS styles, plugins, custom types, etc., that can be added as a dependency to another Gatsby site, giving it all the features and capabilities of the theme.

Themes can be customized fairly easily through shadowing, which is just overriding any one part of any included theme by creating a file of the same name, in a directory matching the theme's package name. This makes it easy to start with a theme you like, and customize it over time as you see fit. The downside to this approach is that you need to dig into the theme's source code to fully understand how it works, so you know what to override. Reading the source of the tools you use, though, is hardly a bad thing (it's actually one of the best ways to learn, if you ask me.)

Step By Step

Let's walk through the steps it took to create this blog. I should note here that I tried and tested about half a dozen other themes/starters, and the whole thing still took less than an afternoon. I did already have the hosting set up, though, but I'll walk through that anyway, it's equally simple.

Prerequisites

Ideally, you should already have an account at GitHub
Make sure you have Node installed, preferably the current LTS release.
Next, install the Gatsby CLI globally
```
npm i -g gatsby-cli
```

Using a Starter

There are several hundred "starters" available for Gatsby. A starter is just a pre-configured Gatsby site, with curated plugins, settings, and themes. These are a great way to play around with different features, as well as get ideas on how to configure your own site. The theme I'm currently using has its own starter, so I just went with that for now.

To create your new site, run:
```
gatsby new your-site https://github.com/Ganevru/gatsby-starter-chronoblog
```
This will clone the starter, and install the dependencies.
Change into the new site's directory, and start up the development server:
```
cd your-site
npm run start
```
You may notice that the output from gatsby new instructed you to run gatsby develop instead of npm run dev - this is one of those customizations that starters can provide. Both commands would work, though.
Once the site is built, navigate a browser to http://localhost:8000/ and behold the glory of your shiny new, statically generated, React powered, Gatsby site!

Sample Content Is The WORST.

Here's where the fun(?) starts. Starters almost alawys come with some sample content, and themes may have features you don't want. I'm not going to cover all the features of this theme (you can read the docs for yourself, they do a much better job explaining it), but there are a few things to note when starting a Gatsby site in general. Whenever you edit content (in this case, anything under /content or /src/pages), Gatsby will automatically build and dynamically update your local development site. However, if you change something about the site's configuration, such as adding/removing plugins, or changing gatsby-config.js (or any of the other API files), you must restart the development server for the change to take effect. Since this is a starter, it's site metadata is preconfigured with someone else's name and description, so you'll want to edit gatsby-config.js first. [Note: You can use any text editor to edit these files, but my preference is for VSCode]

Taking a look at the siteMetadata field, there are obviously a number of items you'll want to change. The siteTitle, siteDescription, siteUrl, and the social object are all ripe for updating.

siteMetadata: {
    siteTitle: 'Chronoblog Starter',
    siteDescription: 'Starter for Gatsby Theme Chronoblog',
    siteImage: '/banner.png', // main image of the site for metadata
    siteUrl: 'https://chronoblog.netlify.com/',
    pathPrefix: '/',
    siteLanguage: 'en',
    ogLanguage: `en_US`,
    author: 'Site Author', // for example - 'Ivan Ganev'
    authorDescription: 'short author description', // short text about the author
    avatar: '/avatar.jpg',
    twitterSite: '', // website account on twitter
    twitterCreator: '', // creator account on twitter
    social: [
      {
        icon: `twitter`,
        url: `https://twitter.com/ganevru`
      },
      {
        icon: `github`,
        url: `https://github.com/Ganevru/gatsby-theme-chronoblog`
      },
      {
        icon: `node-js`,
        url: `https://www.npmjs.com/package/gatsby-theme-chronoblog`
      }
    ]
  }

You may want to change some of the plugins as well. For example, I commented out Google Analytics. You might want to replace the JPEGs in the /static folder as well. Once that's to your liking, start the dev server back up again.

Now you can edit the content to your liking. I started by removing everything (except /links/frontmatter-placeholder - that should be kept, especially if you haven't added any link content, due to a quirk with Gatsby and GraphQL. Every technology has quirks, the trick is deciding on whether you can live with them or not.) You should be able to add and edit pages, posts, notes, and links (see the docs for details) using Markdown, an easy to read, and style, syntax for content editing.

Look, Ma! No CMS!

If you're used to traditional CMSs, such as WordPress or Drupal, first off, my condolences. The setup I've described doesn't have one. Yet. I'll cover adding one in a future post. For now, content is written by hand, in a text editor, using Markdown, and committed with the rest of the site as a source file. This is a perfectly fine way to create and manage a personal site. In fact, several CMS options for Gatsby continue to bundle content with source, but it's important to note that one of the best things about Gatsby, is the fact that there are so many options for content. This theme, for example, provides four content types, Pages, Posts, Notes, and Links. Behind the scenes, each of these is a different 'source'. In fact, it's entirely possible to source each of these from a different place. Yes, even WordPress or Drupal.

Let's Do It Live!

What's the point of building a site about pizza and cats if you can't share it with the world? Nothing, that's what. Let's fix that. This assumes that you have an account with GitHub, as mentioned, but even if you don't, it's still quite easy to get your site online. Of course, you'll need a good domain name first. I'm not going to go too much into that, except to recommend NameCheap as a registrar, but needless to say, this step is what took me the longest, by far.

Anyway, once you've secured your snappy new .wtf domain name, you'll want to hook your site up to a repository at Github. I'm not going to go over how to use git here, there is plenty of good documentation available online.

Sign into your Github account
Create a new repository, give it a good name, don't create a README or .gitignore file, though
Copy the repository URL when prompted, then add it as a remote repository to your site, as directed
Commit your changes locally, then push them to Github

Now that that's all said and done, it's time to release your site into the wild! Head on over to Netlify and sign up for an account using your Github credentials. (Again, it's not necessary to use Github, it just makes things a lot easier.)

After signing up, click the New site from Git button, and choose Github as the provider. You'll need to authorize Netlify to access your repo, then select it, leave the default settings, and click Deploy. Congratulations! You're the proud owner of an honest-to-goodness, statically generated, React-powered, custom website! Now, whenever you make changes locally and push them to Github, your site will automatcially rebuild and redeploy, just like those fancy DevOps guys from IT!

Adding your custom domain is fairly easy, but I'll leave it to the reader to handle that step.

Hopefully this walkthrough was useful, or interesting, or at least not painfully boring. I promise to write more about pizza and cats in the future, assuming I can find the time.