Creating a static website with Jekyll
While working on the docs site for GeoBlazor, I was introduced to Jekyll. Now, I’ve heard of static site generators before, but this was just the perfect fit for a docs site. It also made me think of all the hoops I tend to jump through while creating static sites like this blog, that could be made simpler by using a generator and just writing good ol’ markdown.
There’s a lot to recommend about Jekyll. The main downside? I had to install Ruby 😜. No big deal. Jekyll Installation Docs are pretty easy to follow to get going. Here’s a short list of steps for Windows (different OSes will vary):
- Download the latest Ruby+Devkit from RubyInstaller for Windows.
- Run the installer, and select to run
ridk install
on the last step. Choose theMSYS2 and MINGW development tool chain
option. - Reboot (it says you can just close your terminal, but this didn’t work for me).
- Check to make sure
ruby
andgem
are registered with thePATH
environment variable for command line actions. I think I ran into an issue on at least one machine where I had to add the path manually (search in the windows start menu forenvironment variables
). - Run
gem install jekyll bundler
. - Navigate to the folder where you want to set up your site.
- Run
jekyll new myNewSite
, this will create a new folder (./myNewSite
). - Navigate into that folder (
cd myNewSite
). - Run
bundle exec jekyll serve --livereload
. - Open your browser and navigate to http://localhost:4000. You should see your new site rendered!
You don’t actually need the --livereload
flag to build your site, but I choose to always use this while developing, so that I can quickly see the changes I make to markdown and css sites rendered in the browser.
These steps got me up and running locally. However, when I went to publish to GitHub Pages, I found a few more things I needed to add.
- In your
Gemfile
, comment out the line starting withgem "jekyll"
- Also in the
Gemfile
, uncomment the line starting withgem "github-pages"
, and replace withgem "github-pages", "~> 227", group: :jekyll_plugins
where 227 is the latest version of thegithub-pages
gem available. - Run
bundle install
to install thegithub-pages
gem. - Run
bundle add webrick
(no idea, but you’ll get an error without it).
Once these steps are added, try pushing your code up to GitHub, and navigate to https://YOURNAME.github.io
to see the code in action!