Exhaustive Static Site Guide (A Work in Progress)

What is a Static Site?

This is a Static Site! A static site is a flat collection of files. HTML, CSS, Client Side Javascript. If there is any serverside stuff, it’s usually done with embedded JavaScript plugins or iframes. It makes a site simple to edit, easy to deploy.

What is a Static Site Generator?

A static site generator takes a collections of files and makes them into something a webserver can serve. Usually applying some sort of theme to Markdown.

Pros and Cons

Static sites are flat, so everthing is simpiler and can be delivered via a CDN (content delivery network)

Some themes rely on external JavaScript. If you want to preserve users privacy you should try to delivery all of your websites content yourself without relying on external services. You can avoid security concerns with external resources by using Subresource Integrity but try serving them with your own webserver or CDN.

Isn’t Markdown limiting?

It’s as easy as typing ![image](url) to embed an image!

with shortcodes, like those in hugo, I can easily embed a tweet in my site from my markdown file with a shortcode!

{{< tweet 1090149199146975232 >}}

Static Sites Rock!

— Thomas (@tfolbrecht) January 29, 2019

You can even make custom ones, here’s one I made for changing the colors of individual pages.

{{< theme "#4fc1f4" "#600030" >}}

Sometimes you may want to embed a raw html page with custom css and js, think portfolio projects. Just drop it into your content folder!

Making a Static Site

If you’re unfamiliar with the web or how websites work, don’t fret! Web pages are just files and directories, each directory has what’s called an index index.html that tells the browser where all the images, style sheets, and JavaScript are.

./                             # This is the directory
./index.html                   # This is the index file
./coolimage.jpg                # this is a cool image
./anotherpage/                 # another directory inside the first
./anotherpage/index.html       # This is the index file
./anotherpage/anotherimage.jpg # this is another cool image
./assets/style.css             # this can be linked to add style
./assets/script.js             # this can be embeded to add js

You can stick anything in here, but web browsers only support some file types and formats. For example a pdf must be loaded

index.html would be your sort of homepage


Markdown is a sort of typesetting language, html is markdown (hypertext markup language).


You need a theme! It’s a series of templates for rendering pages. Making your own doesn’t have to be too hard, you just need to be familiar with web technologies like html, css, and javascript! Then learn the templating language for your static site generator. For example, hugo is basically a wrapper for the Golang html template library where Go variables {{ $likeSo }} are substituted into html.

Static Site Workflow

Writing content

True WYSIWYG editing

Static Site generators usualyl have an interactive mode. It lets you edit a markdown file, and with each save to file, it updates the locally served webpage in the browser.

Making Templates/ themes

Convert it with a tool

Read the docs and build it from scratch, review some inspirational themes from theme repos like themes.gohugo.io

Static Site Hosting

Managed vs Self Hosted: Managed site hosting configuration be complex, but it’s inexpensive and super scalable. You may end up paying more than you’d like, you have to keep tabs on it.

You don’t expose yourself to security issues, like patching nginx, apache, etc

You can serve a static site locally! Most static site generators have built in web servers (as do most programming languages)

Content Delivery Networks improve delivery by decreasing latency

The webserver is a host, or origin of your content.

Managed Hosting:

Managed CMS

Self hosted:

You can’t easily selfhost a delivery network. It requires you to have lots of servers in a lot of places, but with new projects like WEBTORRENT and DAT, your users host it!

Content Managment

Source Of Truth


All my links are broken when I preview my page

Try using relative links, and keeping your canonical url blank, look at these example configs.

Things aren't reloading fast enough

hugo server -v


Ways to skin a cat

Pick your poison when it comes to that actual generator

Simple and Single User

Bash based deployment

Copy files from public to some place to store them using the commandline, for example, Dropbox, etc


# check for aws commandline
aws s3 cp ~/website/public s3://coolsite.com --recursive
M$ Azure
Nginx or Apache

Event driven

I use AWS Push to git master event is detected by CloudWatch -> CloudWatch tells Codebuild to build the site, Codebuild deposits the build artifacts public/ to an S3 Bucket and sends a signal to invalidate the CloudFront Cache.

There are a handful of popular ones that the moment.

Based on the Go language html templating module. It’s a single binary that looks for content, combines it with your template and serves the completed site.

Jekyll is a Ruby gem (Ruby is a programming language)

Uses React templates

Bash Scripts

Deploy AWS:

Deploy Azure: