Static Site Generators (SSGs) are a quick and easy way to get a simple blog up and running in just a few minutes.
I've been wanting to add some blogging functionality to my homepage, awwsmm.com, for a while now, but I've been dragging my feet because it seems like a lot of work...
- write blog posts in Markdown
- style everything, etc.
Fortunately, SSGs make things much simpler.
Here are my initial thoughts.
I followed this guide from the JetBrains team (who make IntelliJ and PyCharm) and was able to get the example app running in essentially a single command (after updating
$ npx create-next-app nextjs-mdx-blog
Here is the result
...okay, it's not too exciting, but it works!
Next.js had, in my opinion, the simplest and most straightforward setup of any of these four SSGs.
Gatsby claims to be able to give you super fast build times, but this is probably a non-issue for your static blog with a few dozen posts.
I followed Gatsby's own tutorial for getting a simple site set up] and was able to get this beauty up and running in just a few minutes
The only major difference here was that I had to first install the Gatsby CLI via npm. Certainly not a show-stopper, but it was an extra step relative to the Next.js setup.
Hugo is different from the previous two SSGs in that it's not React-based, but written in Go. Like Gatsby, Hugo plays nicely with Netlify and also claims to be "the fastest tool of its kind", able to build pages in < 1 ms.
Hugo also have a how-to guide on their website which was easy to follow and resulted in the following little blog in only a few commands
Hugo also requires installing a command-line tool (this time, via
brew on macOS rather than via
npm), and additionally requires you to select a theme (it doesn't provide a default one). That tiny extra step gave me some errors because my brain is fried by the Internet and I literally cannot read two sentences ahead
$ hugo server -D Start building sites … hugo v0.90.0+extended darwin/amd64 BuildDate=unknown WARN 2021/12/10 17:00:11 found no layout file for "HTML" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination. WARN 2021/12/10 17:00:11 found no layout file for "HTML" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination. WARN 2021/12/10 17:00:11 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination. WARN 2021/12/10 17:00:11 found no layout file for "HTML" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination. ...
After I read those instructions, though, everything worked as expected.
I had high hopes for Jekyll and started following their step-by-step tutorial here at the same time I was looking at the other SSGs above, in parallel. But Jekyll was the only SSG I had to google an error message for when getting started, and it took about 10 minutes longer than the others to get up and running (mostly because of Ruby).
If you want to use Jekyll, the first command you'll be given is a Ruby
$ gem install jekyll bundler
Before you do that, though, make sure you're using Ruby 2 and not Ruby 3
$ ruby -v # bad ruby 3.0.3p157 (2021-11-24 revision 3fb7d2cadc) [x86_64-darwin20]
$ ruby -v ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin20]
$ bundle exec jekyll serve Configuration file: none Source: /Users/andrew/Git/SSGs/jekyll Destination: /Users/andrew/Git/SSGs/jekyll/_site Incremental build: disabled. Enable with --incremental Generating... done in 0.041 seconds. Auto-regeneration: enabled for '/Users/andrew/Git/SSGs/jekyll' ------------------------------------------------ Jekyll 4.2.1 Please append `--trace` to the `serve` command for any additional information or backtrace. ------------------------------------------------ /usr/local/lib/ruby/gems/3.0.0/gems/jekyll-4.2.1/lib/jekyll/commands/serve/servlet.rb:3:in `require': cannot load such file -- webrick (LoadError) from /usr/local/lib/ruby/gems/3.0.0/gems/jekyll-4.2.1/lib/jekyll/commands/serve/servlet.rb:3:in `<top (required)>' from /usr/local/lib/ruby/gems/3.0.0/gems/jekyll-4.2.1/lib/jekyll/commands/serve.rb:179:in `require_relative' from /usr/local/lib/ruby/gems/3.0.0/gems/jekyll-4.2.1/lib/jekyll/commands/serve.rb:179:in `setup' ...
But suppose we're on the correct version of Ruby. Here's what I experienced next
$ ruby -v ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin20] $ bundle exec jekyll serve Traceback (most recent call last): 2: from /usr/bin/bundle:23:in `<main>' 1: from /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/rubygems.rb:302:in `activate_bin_path' /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/rubygems.rb:283:in `find_spec_for_exe': Could not find 'bundler' (2.2.33) required by your /Users/andrew/Git/SSGs/jekyll/Gemfile.lock. (Gem::GemNotFoundException) To update to the latest version installed on your system, run `bundle update --bundler`. To install the missing version, run `gem install bundler:2.2.33`
Okay, it looks like we need to update the
bundler, whatever that is
$ bundle update --bundler You must use Bundler 2 or greater with this lockfile.
Okay? Maybe it's missing?
$ gem install bundler:2.2.33 Fetching bundler-2.2.33.gem ERROR: While executing gem ... (Gem::FilePermissionError) You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.
$ sudo gem install bundler:2.2.33 Password: Fetching bundler-2.2.33.gem Successfully installed bundler-2.2.33 Parsing documentation for bundler-2.2.33 Installing ri documentation for bundler-2.2.33 Done installing documentation for bundler after 4 seconds 1 gem installed
Now can I update?
$ bundle update --bundler Fetching gem metadata from https://rubygems.org/......... Using bundler 2.2.33 Following files may not be writable, so sudo is needed: /Library/Ruby/Gems/2.6.0 /Library/Ruby/Gems/2.6.0/build_info /Library/Ruby/Gems/2.6.0/cache /Library/Ruby/Gems/2.6.0/doc /Library/Ruby/Gems/2.6.0/extensions /Library/Ruby/Gems/2.6.0/gems /Library/Ruby/Gems/2.6.0/specifications Fetching public_suffix 4.0.6 Fetching colorator 1.1.0 Fetching concurrent-ruby 1.1.9 Fetching eventmachine 1.2.7 Your user account isn't allowed to install to the system RubyGems. You can cancel this installation and run: bundle config set --local path 'vendor/bundle' bundle install to install the gems into ./vendor/bundle/, or you can enter your password and install the bundled gems to RubyGems using sudo. Password: Installing colorator 1.1.0 Installing public_suffix 4.0.6 Installing eventmachine 1.2.7 with native extensions Installing concurrent-ruby 1.1.9 Fetching http_parser.rb 0.8.0 Installing http_parser.rb 0.8.0 with native extensions Fetching ffi 1.15.4 Installing ffi 1.15.4 with native extensions Fetching forwardable-extended 2.6.0 Installing forwardable-extended 2.6.0 Fetching rb-fsevent 0.11.0 Installing rb-fsevent 0.11.0 Fetching rexml 3.2.5 Installing rexml 3.2.5 Fetching liquid 4.0.3 Installing liquid 4.0.3 Fetching mercenary 0.4.0 Installing mercenary 0.4.0 Fetching rouge 3.26.1 Installing rouge 3.26.1 Fetching safe_yaml 1.0.5 Installing safe_yaml 1.0.5 Fetching unicode-display_width 1.8.0 Installing unicode-display_width 1.8.0 Fetching addressable 2.8.0 Installing addressable 2.8.0 Fetching i18n 1.8.11 Installing i18n 1.8.11 Fetching pathutil 0.16.2 Installing pathutil 0.16.2 Fetching kramdown 2.3.1 Installing kramdown 2.3.1 Fetching terminal-table 2.0.0 Installing terminal-table 2.0.0 Fetching kramdown-parser-gfm 1.1.0 Installing kramdown-parser-gfm 1.1.0 Fetching sassc 2.4.0 Fetching rb-inotify 0.10.1 Installing rb-inotify 0.10.1 Installing sassc 2.4.0 with native extensions Fetching listen 3.7.0 Installing listen 3.7.0 Fetching jekyll-watch 2.2.1 Installing jekyll-watch 2.2.1 Fetching em-websocket 0.5.3 Installing em-websocket 0.5.3 Fetching jekyll-sass-converter 2.1.0 Installing jekyll-sass-converter 2.1.0 Fetching jekyll 4.2.1 Installing jekyll 4.2.1 Bundle updated!
Ten minutes later, I can finally start my Jekyll site
$ bundle exec jekyll serve Configuration file: none Source: /Users/andrew/Git/SSGs/jekyll Destination: /Users/andrew/Git/SSGs/jekyll/_site Incremental build: disabled. Enable with --incremental Generating... done in 0.029 seconds. Auto-regeneration: enabled for '/Users/andrew/Git/SSGs/jekyll' Server address: http://127.0.0.1:4000 Server running... press ctrl-c to stop.
And here it is
"Sad trumpet noise" doesn't really do this justice.
Oh, and also
[2021-12-10 17:10:39] ERROR `/favicon.ico' not found.
In about 15 minutes*, I was able to go from knowing absolutely nothing about these four static site generators to having four different "blogs" running on my local machine.
Of course, there's much more work to be done in incorporating one of these into my site (I'm leaning toward Hugo or Next.js at the moment) -- and actually, you know, writing blog posts -- but those are for another day.
* 2/3s of which was due to Jekyll alone
Note to the Jekyll team: make this process a bit less bumpy for newbies.