Skip to content

Instantly share code, notes, and snippets.

@evanwill

evanwill/jekyllNotes.md

Last active October 4, 2016 06:49
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save evanwill/46641ffd6a254ca82280c9ba53925cb8 to your computer and use it in GitHub Desktop.
Save evanwill/46641ffd6a254ca82280c9ba53925cb8 to your computer and use it in GitHub Desktop.
Download ZIP
notes about static gen, Jekyll, and how to install
Raw
jekyllNotes.md

Using Jekyll on Windows

Static Gen background links:

Install on Windows 7

Jekyll does not official 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.

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

  1. Get Ruby installed:
  • Download RubyInstaller, a installer package for windows. I used the 32 bit version, since there are potential issues with the 64bit version.
  • Run RubyInstaller, all the defaults should be fine.
  • Download the Ruby Development Kit from the RubyInstaller page. If you installed Ruby 32 bit, get DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe. Documentation is on GitHub
  • Click on the Dev Kit to unzip (its a self extracting package), put it in a permanent location, such as C:\rubyDevKit\
  • Open a command prompt and cd to the Dev Kit directory, then type the commands ruby dk.rb init and ruby dk.rb install to connect to your Ruby instance.
  1. Install Jekyll:
  • Open a command prompt, then type gem install jekyll (gem is similar to Python's pip)
  • Done!
  1. 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
  • 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 %} 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment