Editing GitHub Pages on Windows

GitHub Pages can be maintained and edited in place on the GitHub site. But why not clone the repository with your Page to your working computer. That way you are able to make and test your changes. And push them back up to the site when you are satisfied with them.

This article will cover doing just that on a Windows laptop which is what I am using. Those of you on Linux or Apple boxes can still follow around and work from a terminal on your system. There will be a few more steps for Windows users.

 I love Linux, have never spent much time with Apple devices, but would like to set up a development system for GitHub Page. GitHub Pages utilize Markdown to write page content which  is much easier to read than formatted out HTML. And when publishing you can output the Markdown to HTML, using something like Jekyll, to be posted on your site.

Jekyll is what GitHub uses to convert your Markdown to HTML. Good time to learn Jekyll then is it not? So let us get started.

Getting Started with Jekyll

For your own system you will need Ruby, the programming language. Then an installation of Jekyll. For Windows users this is an issue. It is possible to run Jekyll with a Windows Ruby installation, but it is not officially supported.

The answer is to add a Linux installation to Windows. And the simplest way to go about this is to use the Windows Subsystem for Linux. This will allow you to load a Linux distribution of your choice for development purposes. The WSL does not support a GUI so you will be limited to a CLI. But that is all that is needed for this Linux installation.

There are a number of distributions to choose from. So pick your favorite and enjoy. If you are not sure about which distribution to go with, Ubuntu is a common distribution.

There may be more than one Ubuntu distribution to choose from. I chose the 18.x.x version. It was the latter of the two to choose from. The earlier version may be better if you have a slightly older machine.

You can follow the detailed installation guide, Windows Subsystem for Linux Installation Guide for Windows 10. Once installed you will need to initialize your distro and go through the new user setup. Also,you need to perform an update/upgrade of your Linux Distribution.

Install and Setup Jekyll

Open a terminal screen and login. For Windows, I am assuming you are starting up your WSL Linux distro. Jekyll is a Ruby Gem. So you will need Ruby and RubyGem along with standard Linux development utilities. Check for them and their version with (ruby -v), (gem -v), (gcc -v), (g++ -v), and (make -v).

If you don’t have them, you will need to install them. See the Jekyll Installation page for instructions for your OS. We will cover the Windows installation through your WSL Linux shell.

If you have the Ubuntu distro installed, follow the Ubuntu installation guide. Else, choose the guide for your OS. Install Ruby and the required dependencies. Add the Gem installation and environment variables to your  bashrc file, per the instructions. Then install Jekyll. Pat yourself on the back, it is finished.

It is not required but you might want to install the gem Bundler. The instructions are available on the Ruby 101 page. Don’t worry though, the Bundler installation is included in the tutorial. Here is where I suggest you follow the tutorial, and where the fun begins: the Jekyll Step-By-Step tutorial.

So enjoy and study up on the capabilities of Jekyll, YAML Front Matter, Liquid templates, adding Data, asset and static files, and so much more. Have fun, I know I will.

Addition:

Setup your directory structure (folders) as you see fit. Please feel free to use your favorite Linux editor. Nano is quick and easy. And if you are not familiar with the Linux command line interface (CLI) take the time to work through a Linux CLI tutorial. You can find one easy enough.

On Windows, you can edit files in your WSL Linux system with VS Code. My article on Coding on Windows with Linux will help you set up for using Code to edit files on your Linux system. This is a good way to manage your projects and track your changes with Git.

It is possible to access files on your Linux file system from Windows but only if you have Windows 10 Build 18836 or newer. I’m not so lucky. Besides, you need to start Explorer from inside your Linux system. Probably wouldn’t work for what I wanted if I had the newer Windows build.

I would like to be able to access the /site builds from a Jekyll run. It is easy enough to do that by copying the /site folder from a Jekyll project to a Windows mounted hard drive. Yes, the Windows file system can be accessed from your WSL Linux system through the /mnt/c (for hard drive C).

So why not create a folder on the C drive for your Linux files system to use as a work space and then you can access it from your Windows file system with ease. That is what I did. Created a Home folder with “mkdir /mnt/c/Home” from my Linux system command line.

And this is where I run into a problem. From inside my Linux distro’s shell I can run Jekyll new, build, and serve commands on the Linux file system just fine. But errors are generated running the same commands on the Windows file system.

These errors appear to be permission errors but I am unable to pin them down and find a fix. I will keep working on this. May have to wait for an update to the Windows Subsystem for Linux from Microsoft. All of this is from the command line.

My hope was to be able to run Jekyll under Linux with WSL and access the input files for Jekyll and placing the output files on the Windows file system. This is currently undoable at this time, at least from the Linux command line. But the idea was to develop web sites with Jekyll in Windows.

Jekyll projects can be set up and initiated from the Windows side utilizing VS Code. Make sure you have WSL up and running. Check the lower left corner of your Code screen for the WSL indicator. Then open the terminal into your Linux system.

Have Fun. There is more. Look for the blog on using VS Code to run Jekyll and post to GitHub. And maybe throw in a bit on GitHub Desktop.