---
# System prepended metadata

title: Project documentation template

---

---
title: 'Project documentation template'
disqus: hackmd
---

Building a Blog for Punterclash
===

## Table of Contents

[TOC]

## The Choice of tools

From my research, I came across a number of tools which can help simplify building a blog for Punterclash. I leveled them down to two(2) based on the fact that the two are built on top of the Reactjs framework. I see that as an added advantage owing to the fact that our current team structure already has very good comprehension of the framework. It is also going to ensure that using either of these two tools gives us a very easy learning curve.

The two frameworks are namely:
1. [GatsbyJS](https://www.gatsbyjs.org/)
2. [NextJS](https://nextjs.org/)

I personally have a personal preference for Gatsby because of some of it's feature which I will talk about in a moment.

### Why would I choose Gatsby over NextJS?

GatsbyJS is a static site generator for React. This means that Gatsby does nothing else other than generate static file. It is optimized for this purpose. However, NextJS on the other hand, in its new release now supports building static sites using the same optimization as Gatsby but it is pretty new in town. The support is not that much compared to the Gatsby ecosystem where a lot of work has been put into building plugins, connecting with CMS like wordpress, etc.

Also our current Punterclash clash PWA application is built on top of NextJS, so it wouldn't be a bad idea exploring another framework. A good thing of note is that Gatsby has a very similar **folder structure** to NextJS.


Why should I use Gatsby?
---

1. **The speed of Gatsby websites are phenomenal:** Gatsby is extremely super blazing fast because the pages are already built during the application build. So, it never goes back to fetch from the API. As soon as the page loads, everything is already available.

2. **The availability of plugins:** There are a lot of plugins that are available which we can use to do huge tasks easily. e.g, plugins for calculating a blog’s read time, SEO, analytics etc.

3. **It leverages on React:** There are already available components we can use and at the same time build our own custom components.

4. **Ease of use with markdown:** Yes, this excites me too. We can use markdown files to render our entire blog data.

5. **Starter kits:**  Gatsby has starter kits/boiler plate code for almost anything kind of website we may want to build. So, it is not a surprise that Gatsby has a blog starter kit that already has some contents and amazing [plugins](https://www.gatsbyjs.org/plugins/) pre-installed for our use.

6. **Styling:**  Changing Gatsby styling is all a matter of importing plugins which already solves the problem for us.Plugins like Gatsby-Prism for styling our code snippets in the markdown as we desire. We can also use css, sass, styled components etc. Basically anything we feel like using.

7. **Image optimization:** Gatsby ensure optimizations of images out of the box.

Gatsby has a specific use case which makes it to not be the best framework for any kind of application.

Why should I not use Gatsby?
---

1. **Do I have a lot of dynamic data?**
    If my data vary by the individual user that's logged in? This means I will have to do some dynamic rendering by fetching data from the API, etc. If that's it, then Gatsby is definitely not the go to guy.

2. **Are the data queries I'm running static? Do they only need to be run one time for all users of the site?**
    For most blogs, the user plays no part in the content that is rendered on the page and the data is the same for each user. Gatsby requires to normalize the data as it comes in so we can use GraphQL to query it and this all happens during the build time, when the site is actually generated. This makes the learning curve exceptionally steep for Gatsby compared to frameworks like React or NextJS.

Infrastructure setup
---

To start using Gatsby, there are certain pre-requisites

- Node has to be installed in order to have access to NPM
    - To install node, [click to visit the download page](https://nodejs.org/en/download/)
- Gatsby cli should be installed globally to use the gatsby command on the command line
```gherkin=
npm install -g gatsby-cli
```

Getting started
---
```gherkin=
# To create a new gatsby project, run on command line
gatsby new <name of the project>
```

## Deployment

Deploying a Gatsby blog on **[Netlify](https://www.netlify.com/)** is very straight-forward.

## Reading materials

To really get started with using gatsby, their documentation is one of the best place to look at. Besides that, there are other materials from many that I recommend.

- [Blog site example from Gatsby blog webinar](https://github.com/gatsby-inc/webinar-my-first-code-blog)
- [How to build your first Gatsby blog](https://www.youtube.com/watch?v=xJVHWhO9bJY)
- [The great Gatsby Bootcamp](https://www.youtube.com/watch?v=8t0vNu2fCCM)
- [Gatsby crash course by bradtraversy](https://www.youtube.com/watch?v=6YhqQ2ZW1sc)
