_drafts

Using Jekyll on Windows

Install on Windows 7

Jekyll does not officially support Windows, however it is cross platform (they just don’t officially write windows documentation or check for bugs). There is a Jekyll on Windows page, but it is out of date. Not everything mentioned is required any more.

For more complete install info, and other platforms see go-go gh-pages.

Here are the steps I took to get it running on Windows 7 or 10:

  1. Get Ruby installed:
    • Download the suggested stable version of RubyInstaller (Ruby 2.4.X (x64)+).
    • Run RubyInstaller, all the defaults should be fine. On the final step, ensure the box to start the MSYS2 DevKit is checked.
    • The installer will open a terminal window with options to install MSYS2 DevKit components. Choose option 3, “MSYS2 and MINGW development toolchain”, or simply press ENTER to install all the necessary dependencies. (This installer can be restarted by typing ridk install into a command prompt)
  2. Install Jekyll:
    • Open a command prompt, then type gem install jekyll bundler (gem is Ruby’s installer, similar to Python’s pip)
    • Done!
  3. Use Jekyll:
    • To create a new demo project, open a command prompt, type jekyll new testsite. Jekyll will create a new directory with the given name that includes all the files necessary for a basic project. Once you understand the basics, this step is unnecessary.
    • Move to the new directory, type cd testsite
    • To start working with it, type jekyll serve. (note: for larger sites you will want to activate incremental build, use the short command jekyll s -i)
    • Open web browser and visit http://localhost:4000
    • To stop the server, type Ctrl+C in the command prompt.
    • While jekyll serve is active, Jekyll watches the project directory and builds a static html site in the directory _site which it serves locally.
    • Jekyll watches for any changes you made to the project files and rebuilds the _site as necessary.
    • Don’t make changes to the _site directory. It is generated by Jekyll from all the other files.
    • Jekyll bundles together a bunch of other helpful development tools, such as SASS for CSS and Liquid for templating pages.
    • When you are done developing, the contents of the _site directory will be copied to your host location (for example testweb or github).
    • Use a good text editor, since files should be UTF-8, and there can be issues with line endings. I use Visual Studio Code which is handy for navigating the directory structure.

A tour of the project directory

  • testsite (the top level contains pages that will become top level pages. Edit the overall site settings in _config.yml. Changes to _config.yml are not automatically refreshed during jekyll serve, you have to stop the server and restart.)
    • _includes These are modular chunks of your pages which can be called into a page layout by Liquid. For example {% include head.html %}{% end raw %} in a page layout would add the include head.html from the _includes directory.
    • _layouts These are basic templates for complete web pages. They are constructed out of includes. The layouts are called by files that have content to add the template structure.
    • _posts This directory contains blog posts. We are more likely to use a _collections directory for similar automated treatment of standardized content pages.
    • _sass This contains the modular .scss files that will be pulled into your main css for the site. All normal CSS is valid SCSS, but Sass adds many helpful functions and programatic features which are compiled into regular CSS automatically.
    • _site This is the built out version of your new static site.
    • css Contains the base SCSS file that will be compiled into a single CSS file for the site. You can set all your Sass varibles in one place (if you are using them) and call in your scss partials from _sass by using @import "base";
    • You can add other directories as needed for site assets such as images. They will be copied directly to the _site directory.

Example Themes with demos

On gh-pages

Contrary to popular belief, GitHub Pages does allow/support a few plugins. Here is the list: https://pages.github.com/versions/

Add them to your _config.yml, under gems:, not in the the gemfile (since gh-pages ignores that). They can be installed as a bundle using the github-pages gem. Of interest are:

  • jekyll-seo-tag (GitHub info, usage, basically add {% raw %}{% seo %} to the <head> of your pages, and make sure you have all the metadata in your _config.yml).
  • jekyll-sitemap (GitHub info, repo).