GitHub Pages 101

An Introduction

What is GitHub?

GitHub is a Web-based Git repository hosting service. GitHub provides access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project. GitHub offers both plans for private repositories and free accounts, which are usually used to host open-source software projects. As of 2015, GitHub reports having over 9 million users and over 21.1 million repositories, making it the largest host of source code in the world. (Wikipedia - GitHub)

tl;dr: A website that stores source code for projects

Since storing and serving source code is their business, GitHub has become a very popular web-hosting platform.

These are commonly called gh-pages

As a GitHub user, you

Get 1 of these:

`{username}.github.io`

Any number of these:

`{username}.github.io/{repository-name}`

Websites

It's 2015

There are 100s of website tools out there:

Wordpress, Tumblr, Blogspot, Drupal, Ruby on Rails, Django

why use GitHub?

Browsers only know 3 things

HTML
CSS
Javascript

So why complicate it?

static-website-sample

.
├── index.html
└── main.css

0 directories, 2 files

index.html

<html>
	<head>
		Sample Website
		
	</head>
	<body>
		A title, written directly in the HTML document
		A witty subtitle, also in the original source code
		Some paragraph content that was written here in the document, not being called from the database and returned 'on-the-fly'
	</body>
</html>

main.css

h1{
	font-size: 36px;
	color: red;
	text-align: center;
}

p{
	border: 3px solid blue;
}

Static Websites

Simply put, a static website has no dynamic content, no moving parts.

The code sitting on the server is the HTML that the browser reads and displays, not a series of commands that access a database and generate HTML.

Easier on the Server = often cheaper & more reliable

So this is a static website: No moving parts behind the scenes

But it's 2015, not 1995: I want more from my Website.

Agreed

Simple

Static

You can have a very complex website, but do the 'work' ahead of time. What sits on the server is just HTML. No database connection, no special languages, just plain HTML. The cost of the content generation is handled upfront.

There are a handful of static website solutions, but

Github ♥ Jekyll

Jekyll was created by GitHub Co-Founder, Tom Preston-Werner

Jekyll

Ruby

gem install jekyll

$ jekyll new sample-jekyll-website
#New jekyll site installed in sample-jekyll-website

Jekyll Structure

├── _config.yml
├── _includes
│   ├── footer.html
│   ├── head.html
│   └── header.html
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── _posts
│   └── 2015-10-15-welcome-to-jekyll.markdown
├── _sass
│   ├── _base.scss
│   ├── _layout.scss
│   └── _syntax-highlighting.scss
├── about.md
├── css
│   └── main.scss
└── index.html

5 directories, 15 files

jekyll build

View Full Screen

Configuring Jekyll

`_config.yml`

# Site settings
title: My Sample Jekyll Site
description: This is a sample Jekyll Website
baseurl: "/github-101/gh-pages/assets/jekyll-website-sample/_site" # the subpath of your site, e.g. /blog/
url: "http://yourdomain.com" # the base hostname & protocol for your site
twitter_username: maptimeboulder

# Build settings
markdown: kramdown

`index.html`

---
layout: default
---

<div class="home">

  <h1 class="page-heading">Posts

  <ul class="post-list">
    {% for post in site.posts %}
      <li>
        <span class="post-meta">{{ post.date | date: "%b %-d, %Y" }}</span>

        <h2>
          <a class="post-link" href="{{ post.url | prepend: site.baseurl }}">{{ post.title }}</a>
        </h2>
      </li>
    {% endfor %}
  </ul>

  <p class="rss-subscribe">subscribe <a href="{{ "/feed.xml" | prepend: site.baseurl }}">via RSS</a></p>
</div>

`about.md`

---
layout: page
title: About
permalink: /about/
---

This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](http://jekyllrb.com/)

You can find the source code for the Jekyll new theme at: [github.com/jglovier/jekyll-new](https://github.com/jglovier/jekyll-new)

You can find the source code for Jekyll at [github.com/jekyll/jekyll](https://github.com/jekyll/jekyll)

`_posts`

---
layout: post
title:  "Welcome to Jekyll!"
date:   2015-10-15 11:17:11
categories: jekyll update
---
You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.

To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.

Jekyll also offers powerful support for code snippets:

{% highlight ruby %}
def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.
{% endhighlight %}

Check out the [Jekyll docs][jekyll] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll’s dedicated Help repository][jekyll-help].

[jekyll]:      http://jekyllrb.com
[jekyll-gh]:   https://github.com/jekyll/jekyll
[jekyll-help]: https://github.com/jekyll/jekyll-help

GitHub will automatically look for a jekyll-formatted directory and run the build command to generate your static website, every time you push a change to GitHub.

Resources

These Slides www.townsendjennings.com/github-101/gh-pages/

Official Jekyll Website: www.jekyllrb.com

Or Start with the simplest static website here:

www.townsendjennings.com/github-101/gh-pages/assets/static-website-sample/