Modern Web design with Jekyll and GitHub Pages

 

The setup:

From your terminal on your local machine, do a sudo gem install jekyll (this is assuming that you have Ruby installed and Ruby Gems installed as well.)

Go to your projects folder (or website folder or whatever it’s called.)
Do NOT make a new folder for this project; the gem will do that for you.

Type in “jekyll new projectname”

Change into your new project folder. It should have created a few folders.

The /_layouts folder contains the html templates.

The /_site folder contains your generated site.

The /_posts folder will contain your blog entries.

The /_config.yaml file can be left alone for the time being.

Creating the content:

Open the _posts folder inside of the project root folder.

Create a new document in the following format:

yyyy-mm-dd-title.md

Open this file in your text editor.

Start with


Layout: post
Title: Title of post

Three dashs then Enter.

Layout: post.   – This means to apply the post html template found in _layouts

Title: Title of article/blog post /whatever – This will be substituted in on the next section.

Three dashs then Enter.

Think of this section as the header section in html.

Next is the body section.

{{page.title}}

This will grab the Title out of the header section from above. It uses the Liquid layout template codebase, where most tags are in the form of {{page.tagname}}. These are completely customizable.

Your content will go below the {{page.title}}

Your content can be in pure html or in markdown format, which will be generated by the jekyll gem into html.

The advantage of using markdown is two-fold. First, there will be no missing closing tags in the html file. Second, it allows for a simpler method of having your subject matter experts write the blog posts and apply the formatting, without them knowing any html. One could argue that it is just as complicated initially to teach them one versus the other; however, worst case scenario, your publishing editor can go through and insert the markdown code where necessary, leaving the content creation up to the rest of the staff.

You can view your content in one of two ways.

Option 1:

  1. Typing in “jekyll serve -watch” (the -watch means the local jekyll server will watch for any changes to your code and regenerate on the fly.)
  2. Browse to localhost:4000/ and click on the link for your new post

OR

Option 2:
Go look at the index.html file in the _site folder. DO NOT EDIT this file, as it will be overwritten by Jekyll. Edit your site in _post.

Making it live

From your terminal window, do a “git push github master”. This will push your master branch to your github pages account (documented here at http://wicketbang.com/wordpress/github-pages-hosting/).

Leaving GitHub Pages but still want to use Jekyll?

If you don’t want to host it at Github Pages any longer, you can copy the contents of the _site folder to your other hosting provider.

Reasons you may want to do move it off of Github Pages:

Github Pages doesn’t allow for any server side scripting, such as PHP, ASP.net, Cold Fusion, Node.JS, Django/Python or Rails. If you want any of those capabilities, then you will need to shop elsewhere.

Github Pages hosting

    1. Create your Github account (need a unique email address per acct)
    2. Create the website on your local development machine
    3. Create your local git repo (for a short how-to on Git, look at vagnini.net/meetup_files.htm)
    4. Sign into your new Github.com account and create the remote repo

KEY STEP: It MUST be in the format username.github.io
The username portion IS case sensitive and MUST match the case of your github username

    1. On your local git repo, create a remote repo

git remote add github https://github.com/username/username.github.io.git

username MUST match case of the Github username created in step 1

    1. Push your site to the remote repo

git push github master

    1. Test your content by browsing to http://username.github.io
    2. KEY STEP: For DNS, add (or modify) the @ A record (for the domain itself) to point to the IP address of username.github.io (discovered by pinging that address)
      Add (or modify) the www CNAME record to point to username.github.io
    3. KEY STEP: Create the CNAME file in your project folder (NOTE: it is called CNAME, not CNAME.txt)

It should contain the following: www.yourdomain.com

  1. KEY STEP: Push the CNAME file to the project and test for both yourdomain.com, and www.yourdomain.com