gh-pages-blog was designed to be a simple and quick solution to creating a responsive blog and website using the GitHub Pages functionality available to all GitHub accounts and hosted projects.
Start with forking the gh-pages-blog project, then take a gander at the _config.yml file. The config file has lots of comments that make an effort at making the configuration easier. But to start with, just focus on the first group of options. You’ll definitely need to set these to get your site to work correctly. After making the changes you feel are appropriate for your site, upload it to your GitHub Page and see how it looks. Tweek from there.
If you want to change the Bootstrap theme, you can download some from the Bootswatch website. You may need to play around a bit with the gh-pages-blog.css file though to get things just right. But chances are it will work just fine, or well enough.
Now, let’s talk about posts. You can find the example Hello World post in the _posts directory. You’ll need to put all of your posts there. Posts can be either in HTML (.html) or Markdown (.md). Use whatever you are most comfortable with.
The post file names is also the permalink. The GitHub:Page Jekyll backend will parse the name of the post file to figure out the date for ordering of posts. Most recent posts are shown first.
At the top of the post file is something known as front-matter. Here information about the post is contained in what is known as yml format. For the Hello World post, the front matter looks like:
layout : post
title : Hello, world!
subtitle : Plus some rambling musings about the origin and current state of gh-pages-blog
Any information between the top and bottom three dashes will be treated as post settings, and will not display in the body of the post. The body of the post will be everything below the bottom three dashes of the front-matter.
The three front-matter settings in our example are:
Not represented in the Hello World sample are three other front-matter settings you should be aware of:
Just for fun, let’s expand the front-matter of the Hello, World example to show all the available elements mentioned here.
layout : post
title : Hello, world!
subtitle : Plus some rambling musings about the origin and current state of gh-pages-blog
description : An introductory message about gh-pages-blog.
category : Status Update
tags :
- Bootstrap
- Jekyll
Assuming your _config.yml file has either the categories or tags navlist or navbar dropdown enabled, the first post that has either a category or tag should cause the either the navlist or the dropdown list to appear. If no posts contain categories or tags, then the navlist and dropdownlist won’t be rendered to save some screen real estate.
You can also add pages to your gh-pages-blog site. Simply create a new file in the gh-pages-blog parent directory with either an HTML (.html) or Markdown (.md) extension.
Created pages are listed on the right side in the navbar at the at the top of the site.
The page you create will also need some front-matter. Here’s a good example:
layout : page
title : Getting Started
subtitle : So you want to learn more about using gh-pages-blog? Well, you've come to the right place.
exclude : true
Let’s break down the front-matter for the page, but it’s very similar to the front-matter for a post described above.
Like posts, the body of the page is contained after the three bottom dashes in the front-matter.
Well that’s it in a nutshell. If you run into a bug or have a request for a new feature, please submit an issue.
Happy blogging.
Dereck
ABOUT GH-PAGES-BLOG
gh-pages-blog is the simple way to set up a fully responsive blog on github in just a matter of minutes.
FOLLOW DERECK CURRY FOR UPDATES ABOUT GH-PAGES-BLOG
FORK ME!