Jamstack

You might say “I don’t know how to build a website” or “I don’t know HTML, CSS, or JavaScript”. The great news is, in modern day web development, if you have static content, you can use a static site generator (SSG) to build your website without needing to know how to code.

How Do Static Site Generators Work?

The idea is that you use something like VS Code to write your content in Markdown, and you can preview your website by simply running a command like npm run dev, hugo server, or jekyll serve. Then, when you’re happy with your changes, you commit your changes to Git (still within VS Code), and then you push your changes to GitHub. That kicks off a build process that generates your static site. It typically takes like :45 seconds to a minute, and then your site is live.

What about SSL Certificates?

If you host in GitHub Pages or Cloudflare Pages (both, free), then those platforms automatically get and stay up-to-date with SSL certificates for your domain. They use Let’s Encrypt to provide free SSL certificates. There is literally nothing you need to do.

Popular Static Site Generators

Below is a table of some popular static site generators (SSGs) that you can use to build your website. Each has its own strengths and weaknesses, so you can choose one based on your needs and preferences.

Even though there are more popular options, I have marked the ones that I personally recommend with a star (⭐). These are the ones I have used and found to be effective for building static sites.

Recommended Generators

Why Jekyll?

Jekyll is good because that is the default for GitHub Pages (although it works on Cloudflare Pages too), but because there is such wide adoption of Jekyll, there is lots of documentation and community support available.

• Windows
• macOS
• Linux

# Install Git (via https://chocolatey.org/)
choco install git -y

# Install VS Code (via Chocolatey)
choco install vscode -y

# Install Ruby and DevKit (via https://chocolatey.org/)
choco install ruby -y
choco install ruby2.devkit -y

# --OR--

# Install Git (via winget)
winget install Git.Git

# Install VS Code (via winget)
winget install Microsoft.VisualStudioCode

# Install Ruby (via winget: https://learn.microsoft.com/en-us/windows/package-manager/winget/)
winget install RubyInstallerTeam.Ruby

# Refresh environment variables
refreshenv


# Install Jekyll and Bundler gems through RubyGems
gem install jekyll bundler

# Create a new Jekyll site at ./my-site
jekyll new my-site

# Change into your new directory
cd my-site

# Build the site and make it available on a local server
bundle exec jekyll serve

# Install Git (via Homebrew)
brew install git

# Install VS Code
# VS Code is not available via Homebrew, download from:
# https://code.visualstudio.com/download
# Or install via command line:
brew install --cask visual-studio-code

# Install Ruby (via Homebrew)
brew install ruby


# Install Jekyll and Bundler gems through RubyGems
gem install jekyll bundler

# Create a new Jekyll site at ./my-site
jekyll new my-site

# Change into your new directory
cd my-site

# Build the site and make it available on a local server
bundle exec jekyll serve

# Install Git and other pre-requisites (Debian/Ubuntu)
sudo apt-get update
sudo apt-get install git ruby-full build-essential zlib1g-dev -y

# --OR-- (Fedora/RHEL/CentOS)
sudo dnf install git ruby ruby-devel gcc make zlib-devel -y

# Install VS Code
# For Debian/Ubuntu - use the .deb package or snap
# https://code.visualstudio.com/download
# Or via snap:
sudo snap install code --classic

# For Fedora/RHEL - use the .rpm package
# https://code.visualstudio.com/download
# Or via dnf (if repo is configured):
# sudo dnf install code


# Install Jekyll and Bundler gems through RubyGems
gem install jekyll bundler

# Create a new Jekyll site at ./my-site
jekyll new my-site

# Change into your new directory
cd my-site

# Build the site and make it available on a local server
bundle exec jekyll serve

Why Hugo?

Hugo is written in the Go programming language and is known for its ridiculous speed and flexibility. It can generate a site in milliseconds, making it one of the fastest static site generators available. Hugo also has a robust templating system and a wide range of themes, allowing for easy customization. The main reason I recommend Hugo though is that it’s been around for a long time (since 2013) and has a large community, which means you’ll find plenty of resources and support.

• Windows
• macOS
• Linux

# Install prerequisites: Git and Node.js
# Install Git if not already installed
choco install git -y

# Install Node.js and npm
choco install nodejs-lts -y

# Install Hugo (via Chocolatey)
# For standard version:
choco install hugo -confirm

# For extended version (recommended for themes with SCSS/SASS):
choco install hugo-extended -confirm

# --OR--

# Install Hugo via winget
winget install Hugo.Hugo

# Create a new site
hugo new site my-site

# Add a theme
cd my-site
git init
git submodule add https://github.com/google/docsy themes/docsy
git submodule update --init --recursive

# Install theme dependencies
npm install

# Start the server
hugo server

# Install prerequisites
brew install git
brew install node

# Install VS Code
# For VS Code, download from:
#   https://code.visualstudio.com/download
# Or install via command line:
brew install --cask visual-studio-code

# Install Hugo (via Homebrew)
# For standard version:
brew install hugo

# For extended version (recommended for themes with SCSS/SASS):
brew install hugo-extended

# Create a new site
hugo new site my-site

# Add a theme
cd my-site
git init
git submodule add https://github.com/google/docsy themes/docsy
git submodule update --init --recursive

# Install theme dependencies
npm install

# Start the server
hugo server

# Install prerequisites (Debian/Ubuntu)
sudo apt-get update
sudo apt-get install git nodejs npm -y

# --OR-- (Fedora)
sudo dnf install git nodejs npm -y

# --OR-- (Arch Linux)
sudo pacman -S git nodejs npm

# Install VS Code
# For Debian/Ubuntu - use the .deb package or snap
# https://code.visualstudio.com/download
# Or via snap:
sudo snap install code --classic

# For Fedora/RHEL - use the .rpm package
# https://code.visualstudio.com/download
# Or via dnf (if repo is configured):
# sudo dnf install code

# Install Hugo (Debian/Ubuntu)
sudo apt-get install hugo

# --OR-- (Fedora)
sudo dnf install hugo

# --OR-- (Arch Linux)
sudo pacman -S hugo

# Note: For the extended version (with SCSS support),
# you may need to download from the Hugo GitHub releases page

# Create a new site
hugo new site my-site

# Add a theme
cd my-site
git init
git submodule add https://github.com/google/docsy themes/docsy
git submodule update --init --recursive

# Install theme dependencies
npm install

# Start the server
hugo server

Quick Crash Course

If you want to jump in, I’d recommend starting with Jekyll. You can follow the Jekyll Quickstart Guide or the notes above. Basically, you just need to install Ruby, VS Code, and Git.

The general steps are:

1. Create new GitHub repository for your site. If you are planning to use GitHub Pages, you name the repository <username>.github.io (where <username> is your GitHub username).
2. Navigate into the Settings > Pages section of your repository and select the branch you want to use for GitHub Pages (usually main or gh-pages).
3. Clone your repository to your local machine using Git. For example, create a new directory that matches the hierarchy, like: ~/gitlocal/jdoe/jdoe.github.io, if jdoe was your GitHub username. Meaning the path is: ~/{local git directory}/{username}/{repository name}.
4. Open the directory in VS Code.
5. Make changes to your site using Markdown and config files.
6. Preview your site locally by running bundle exec jekyll serve in the terminal (CTRL + ~ in VS Code).
7. Commit your changes to Git using VS Code’s source control panel in the top-left.
8. Push your changes to GitHub using the terminal or VS Code’s source control panel.
9. Check the Build by navigating to the “Actions” tab in your GitHub repository. If there are any errors, you can fix them and push again.
10. Visit your site at https://<username>.github.io to see your changes live.