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 installon the last step. Choose the
MSYS2 and MINGW development tool chainoption.
- Reboot (it says you can just close your terminal, but this didn’t work for me).
- Check to make sure
gemare registered with the
PATHenvironment 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 for
gem install jekyll bundler.
- Navigate to the folder where you want to set up your site.
jekyll new myNewSite, this will create a new folder (
- Navigate into that folder (
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 with
- Also in the
Gemfile, uncomment the line starting with
gem "github-pages", and replace with
gem "github-pages", "~> 227", group: :jekyll_pluginswhere 227 is the latest version of the
bundle installto install the
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!