Using GitHub Pages and Jekyll / Eagan Unconference 2014

Using GitHub Pages and Jekyll

Eagan Unconference 2014

Created by Drew Gerber / @DigitalZebra

Problem

How to create a demo or website for your open source project hosted on GitHub?

Pay for and manage hosting
Manually upload your changes

How to create a simple blog for either yourself, an organization, or project?

Pay for and manage hosting
Deal with updates, plugins, databases, security ect (if using something like Wordpress)
May be inconvenient or difficult to manage collaborators

Solution

GitHub's answer for projects and organizations needing websites

“Websites for you and your projects”

Outline

Tools overview
GitHub Pages
Creating websites for projects and accounts
Using Jekyll
Drawbacks
Questions?

Git

“Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.”

The Git ecosystem is what we'll be using to “publish” changes to our websites and blog.

GitHub

Popular website for managing open source projects
Uses Git as its foundation
Offers many tools for collaborating on open source projects. A social network for code
GitHub will be hosting our blog and websites

Jekyll

Static content generator - Generates static files from code Markdown, YAML, and Liquid
Has built in blog functionality
Write your blog using HTML and Markdown, without all the extras
Plugin infrastructure allows extendability
GitHub runs a Jekyll “build” command every time your changes are published


        ~ $ jekyll new site-name
        ~ $ cd site-name
        ~ $ jekyll serve

GitHub Pages

(author)
>
(publish)
>
(host)
=

Creating Pages for project

Complete command list:


        ~ $ git clone <repo_name>
        ~ $ cd <repo_name>
        ~ $ git checkout -b gh-pages
        ~ $ git push origin gh-pages
        ~ $ echo hello world > index.html
        ~ $ git add .
        ~ $ git commit -m "hello world!"
        ~ $ git push origin gh-pages

GitHub also provides a wizard which does many of these manual steps for you.

CNAME file tells GitHub which host routes to this project (you also need to configure a CNAME entry in your DNS record)

Using Jekyll

Jekyll consists of the following technologies:

YAML - for defining page metadata and variables
Liquid - simple templating language used to generate posts
Markdown - text-to-HTML conversion tool. Markdown syntax goes in, HTML comes out
Ruby - what Jekyll itself is written in

Using Jekyll

Creating and serving a new blog

Once Jekyll is installed, simply run the following to create a new site and serve it:


        ~ $ jekyll new site-name
        ~ $ cd site-name
        ~ $ jekyll serve

Using Jekyll

Directory Structure


        _drafts # Where draft posts go
        _includes # Include files (eg. footer, header) go here. Think partial files.
        _layouts # Layout files go here. These can include content or partials.
        _posts # Your blog posts will go in here as Markdown or HTML files
        _site # This is the folder where Jekyll outputs all of the HTML files
        _sass # Sass files for site
        _config.yml # YAML based configuration file for Jekyll

Using Jekyll

Creating a new post

Creating a new post is as simple as adding a file to the _posts directory:


        _posts
        - 2014-09-04-new-post.markdown

Sample Post:


        ---
        layout: post
        title: "This is my new post!"
        date: 2014-09-04 20:25:30
        categories: helloworld
        ---
        Hello world!

Drawbacks

Requires some technical know-how (coding, Git)
Jekyll is missing comments
- Can be added using Disqus or similar
Jekyll is missing analytics
- Can be added using Google Analytics or similar
Requires buy-in to GitHub for managing projects

Questions?

Useful Links

GitHub Pages: pages.github.com
Jeykll Homepage: jekyllrb.com
Guide for running Jekyll on Windows: jekyll-windows.juthilo.com

Contact Info

Twitter: @DigitalZebra
GitHub: github.com/DigitalZebra
Website: digitalzebra.net