It can be problematic to set up Windows to use Jekyll; in fact the Jekyll developers do not officially support Windows as a platform. This page documents a workaround for Windows users: the use of VirtualBox and Vagrant to run a virtual Unix environment within Windows with Python, Ruby, git, and Jekyll pre-installed.
Follow the QuickStart directions to set up Git and GitHub. Be sure to join GitHub, install git, and set up your SSH keys for communication with GitHub.
Note that on Windows, the GitHub for Windows application will install a command-line git that will be available from PowerShell. (Use PowerShell, rather than the command line, if available).
Download and install VirtualBox from the VirtualBox downloads page.
Note that you do not need to run VirtualBox, just install it. VirtualBox will be invoked and managed by Vagrant.
Download and install Vagrant from the Vagrant downloads page.
To verify that Vagrant is installed correctly, type
vagrant -v. For example:
% vagrant -v Vagrant 1.6.3
We have created a Vagrant "box" that contains a Unix environment with git, Python, Ruby, and Jekyll pre-installed. Download this large (500 MB) file from here.
In a shell window, cd to the directory containing the moreaframework.box file, and type the following:
% vagrant box add moreaframework.box --name morea-framework/basic-box
This will copy the moreaframework.box file into your
~/.vagrant.d directory and define a symbolic name for it that can be referred to in Vagrantfiles. If you want to save space, you can delete the downloaded version of moreaframework.box once this command executes successfully.
Follow the QuickStart instructions to create an empty repository in GitHub.
Follow the QuickStart instructions to set up a local development directory.
Download this Vagrantfile to your newly created local development directory. (Right-click on the displayed page and "Save as...")
In a shell window, cd to your local development directory and type
vagrant up. This command will process the contents of the Vagrantfile, which instructs Vagrant to use VirtualBox to begin running a virtual Unix environment whose image has been stored in the Morea Framework box.
You should see output similar to the following:
As the output shows, this command started up a virtual machine running Ubuntu Linux preconfigured with Morea Framework tools (Ruby, git, Jekyll, Python). It copied your git user.name and user.email from your local settings, and set up its port 4000 to be available from your host machine. (That's so that you can use your local browser to see the local version of your site).
In your shell, type
vagrant ssh to get into your newly instantiated virtual machine. To convince yourself that the environment is already configured, you can run commands to find out the installed versions of git, ruby, python, and jekyll. Here's an example:
If you have problems with this command, be sure to use a shell (such as PowerShell) which makes available the
Vagrant creates a mirror of your local directory structure starting from the directory where you invoked
vagrant up. This mirror is available in the
/vagrant directory. So, cd to that directory and notice that it contains the same contents as your local directory:
From within your virtual environment, follow the QuickStart instructions to run morea-vanilla-install. If you download the file using Windows, be sure to place it in your local development directory. If you download the file using your virtual Unix environment, be sure you download it into the
/vagrant directory (i.e. the mirror of your local development directory.)
You can now follow the remainder of the QuickStart starting with Develop course content.
Note that you can edit Morea files using a Windows editor if you prefer since the local directory is mirrored on the virtual machine.
See the Vagrant command line interface documentation for details. You will be interested in
vagrant halt if you don't want your virtual machine running all the time. You can always run
vagrant up to get it back up again.
Unfortunately, if you edit Morea files with a Windows editor, the Jekyll process running in the virtual environment does not "notice" the changed file and thus does not re-process the files.
Workaround 1: force-polling. One workaround for this is to edit your morea-run-local.sh script to add
--force_polling to the jekyll command:
This tells Jekyll to automatically re-process the files every five seconds (regardless of whether files have changed or not). Not a perfect solution, but acceptable for the short term.
Workaround 2: touch a Morea file within Vagrant to trigger re-processing. If you don't want to re-process all of the files every 5 seconds, a different workaround is to open a second Vagrant shell and
touch any Morea file when you want to regenerate the site. This works because the Jekyll process running inside Vagrant does notice file changes occurring inside the process.
The use of VirtualBox and Vagrant is intended to overcome issues with the installation of Ruby and Jekyll on Windows. Specifically, it enables you to run the
morea-run-local.sh command successfully.
If you prefer, you can use the
git-bash environment within Windows to run the scripts that invoke git (i.e.