How I Got Jekyll + BlackDoc Theme Working in Windows
21 Jan 2016
What better blog post to start out with than notes on how I got Jekyll and BlackDoc working on Windows 10? If anything, this will be useful for my reference next time I wipe my workstation and need to start over.
Note that typically I would use a docker container and/or vagrant box to accomplish all this so I would never have to really reproduce it again in the future, but I really wanted to get it natively working on Windows.
What is BlackDoc?
BlackDoc is a Jekyll theme based on the parent theme Poole. I rather like it for its simplicity and color scheme. I'm sure I'll be making minor edits to it as I update this site, but I liked it as a starting point.
Why a Guide?
Modern installation on Windows is not terribly friendly and fraught with command line errors that lead to StackOverflow several times. This may be fixed in the future, but I imagine it's a result of the current state / mismatch of Ruby versions, RubyDevKit versions, and Jekyll versions in combination with BlackDoc/Poole's target environment. This coupled with Windows is a bit of a recipe for disaster.
Get Ruby for Windows. Your target download is the 2.0.0 variant. You want the architecture to be the same as your local Windows installation, so likely x64. Today, that download is Ruby 2.0.0-p647 (x64).
During the install, you want to check the "Add Ruby executables to your PATH" checkbox right before clicking the Install button.
Once again, go to the Ruby for Windows page. Get the DevKit that matches your current architecture. Today, that download is DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe.
Run that exe, which is a self-extracting 7z archive. Point it at "C:\RubyDevKit" and hit Install/Extract.
Once done, open a command line and perform the following commands:
Open a new command line and perform the following command:
If everything went well, you should be able to issue the command 'jeykll -v' to verify installation was fine (only differing in version number, depending on the date you're following this guide):
Make sure Git for Windows is installed. Make sure the "Use Git from the Windows Command Prompt" option is checked for the "Adjusting your PATH environment" section of the install. Other options can be left at their default.
You can check everything went fine by opening a command line and issuing the following
Open a command line and cd to the location you would like to start your Jekyll project. Then issue the following command:
Now rename the BlackDoc directory to .github.io and cd into it:
Things Go Wrong Part I
At this point, if everything was easy in the world of Jekyll in Windows, you should be able to begin serving and editing your Jekyll site immediately. Let's try jekyll serve:
First, edit the _config.yml file with your preferred text editor and add the following at the bottom:
And then install the jekyll-paginate gem using the command line:
Things Go Wrong Part II
Let's try jekyll serve again:
Disabling Relative Permalinks
Okay, open _config.yml again and delete the "relative_permalinks: true" line.
Things Go Wrong Part III
Another try at jekyll:
Issue the following at a command prompt:
Things Go Wrong Part IV
Edit the _config.yml file with your preferred text editor and change the "gems" line to the following:
And then install the jekyll-gist gem using the command line:
Things Go Wrong Part V
Things have to work by now, right? Wrong...
Install the pygments gem using the command line:
Things Go Wrong Part VI
Is jekyll working now? Well, mostly. But we don't want it manually polling, so we should install the 'wdm' gem.
Install the wdm gem using the command line:
Things Go Wrong Part VII
Okay, so it looks like Jekyll is serving (albeit with an error):
But when we visit http://127.0.0.1:4000/ we get a blank page. What gives?
Installing Python, Pip and Pygments
Well, it turns out that pygments also requires Python2.7, pip, and the pygments package.
During the install, make sure to enable "Add python.exe to Path".
The path option in the installer didn't work for me though, as evidenced by the following in a command line following the install:
So to manually add it to path, we open the start menu and search for "environment variable". On my system, the desired option looks like:
Click the "Environment Variables..." button. Double-click the first "Path" item in the "User variables" table. At the end, append ";C:\Python27"
Python should now be available in any future command line:
Now install pygments from the command-line:
Things Go Wrong Part VIII
Yep, we're still not quite there yet. This should be the last fix though. Here's the attempt at this stage:
Installing cacert.pem for Ruby
Get cacert.pem by saving this file, cacert.pem, to your Ruby directory (for me, that was C:\Ruby200-x64\cacert.pem).
Now, we need to add the SSL_CERT_FILE entry to your system environment variables. Once again, we open the start menu and search for "environment variable". On my system, the desired option looks like:
Click the "Environment Variables..." button. Then click the top-most "New..." button. For Variable name, enter SSL_CERT_FILE. For Variable value, enter your path to the cacert.pem file (for me, it was C:\Ruby200-x64\cacert.pem).
Finally, Jekyll serve is working
We made it!
Visiting http://127.0.0.1:4000/ now produces the following:
You can live edit your Jekyll pages and posts and Jekyll should automatically re-build and re-serve the site for as long as you keep the jekyll serve command running from your Jekyll site's working directory.