Build a Blog with GitHub - Part 2

- 16 mins

Here’s Part 1 of this post http://artiannaswamy.com/build-a-github-blog-part-1

We left off at the point where your site is live, but the theme inhabiting it doesn’t have your information.

Let’s fix that first, then try a few customizations.

Index

1. Personalize your site

With a GitHub theme, the first place you start is with the _config.yml file.

The developer will have provided some documentation to go with the theme - read that first to see if there are any special quirks to the config file. Then open up the config file, and browse through the various variables.

This is the control center of your site. Updates you make here will get reflected in multiple areas of the site, not necessarily just the home page.

Let’s go through some of the config settings in the Indigo theme I am using on my site. Here is the original _config.yml file from the source theme. Let’s take these one at a time.

name: John Doe
bio: 'A Man who travels the world eating noodles'

# main text of home
picture: 'assets/images/profile.jpg'

url: http://sergiokopplin.github.io/indigo
# your url: http://USERNAME.github.io

permalink: /:title/

markdown: kramdown
highlighter: rouge

analytics-google: 'UA-MYANALYTICS'

# if you don't want comments in your posts, set to false
disqus: mydisqus

# if you don't have any of social below, comment the line
facebook: myfacebook
twitter: mytwitter
# google: mygoogle
# instagram: myinstagram
# pinterest: mypinterest
linkedin: mylinkedin
youtube: myyoutube
spotify: myspotify
github: mygithub
email: myemail@gmail.com

# if you don't need pagination, comment the *paginate* configs below
# paginate: 5
# paginate_path: "blog/:num/"

# if you don't need projects, comment the *projects* configs below
projects: true

# if you don't need "about" or "blog", comment them out below
about: true
blog: true

# do you want to show the "read time" of the posts?
read-time: true

# do you want to show the "tags" inside the posts?
show-tags: true

# related posts inside a post?
related: true

# do you want some animations?
animation: true

gems:
  - jemoji
  - jekyll-mentions
  - jekyll-seo-tag
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-gist
  - jekyll-paginate

jekyll-mentions:
    base_url: https://github.com

exclude: [README.md, Gemfile, Gemfile.lock, node_modules, gulpfile.js, package.json, _site, src, vendor, CNAME, indigo-gh-pages.zip, Rakefile, screen-shot.png, travis.sh]

Name & Bio

name: John Doe
bio: 'A Man who travels the world eating noodles'

The first thing you want to replace is, of course, the name and bio with your own name and a short description of who you are / what you do. Follow the syntax of the original file when changing the information. That is, for example, replace John Doe with your name, but don’t put it in quotes, just like in the original file. However, in the Bio, the author has used single quotes on either side of the phrase, so you should do the same.

Profile Picture

picture: 'assets/images/profile.jpg'

URLs

url: http://sergiokopplin.github.io/indigo
# your url: http://USERNAME.github.io

If you were sticking with the yourusername.github.io naming for your website, you’d change this URL to the github.io address. But since you have your personal domain mapped to this, you want to change this field to http://yourdomain.com.

Google Analytics

You can leave the permalink, markdown and highlighter fields alone for now.

analytics-google: 'UA-MYANALYTICS'

Google Analytics is definitely something you want to set up now so you can keep an eye on the stats for your site.

Note: Make sure you set up filters in the Google Analytics Admin panel to exclude your own IP address. This excellent tutorial will help you through the steps: How to exclude internal traffic from Google Analytics.

Disqus

disqus: mydisqus

To set up Disqus commenting on your blog:

facebook: myfacebook
twitter: mytwitter
# google: mygoogle
# instagram: myinstagram
# pinterest: mypinterest
linkedin: mylinkedin
youtube: myyoutube
spotify: myspotify
github: mygithub
email: myemail@gmail.com

Blog features setup

# if you don't need pagination, comment the *paginate* configs below
# paginate: 5
# paginate_path: "blog/:num/"

# if you don't need projects, comment the *projects* configs below
projects: true

# if you don't need "about" or "blog", comment them out below
about: true
blog: true

# do you want to show the "read time" of the posts?
read-time: true

# do you want to show the "tags" inside the posts?
show-tags: true

# related posts inside a post?
related: true

# do you want some animations?
animation: true

The sections here are all self-explanatory. If you want to see exactly what they affect, turn off and on each of the features, and see what happens.

To summarize the settings:

2. Add New Pages

I liked the way this theme was organized, because I found it pretty intuitive to follow along on the various references to other files till I found the one I wanted to change. For example, if you start at index.html (Right Click > Open With … TextWrangler), you’ll see references to header.html and footer.html. If you open up header.html in the _includes folder, you will see the code that controls which pages the header applies to.

Here’s that code in the original theme:

From that first line, it looks like the header defined in lines 3 - 14 will show only if the page title is Home or Blog or About.

Which means, if you add any new pages, it won’t include the Header, unless you add a reference to that new page here. So, let’s do that.

if page.title == "Home" or page.title == "Blog" or page.title == "Projects" or page.title == "Consulting"
---
title: About
layout: page
permalink: /about/index.html
---
---
title: Consulting
layout: page
permalink: /consulting/index.html
---

3. Set Custom URLs for Posts

For this one, I refer you to another excellent post by Joshua Lande http://joshualande.com/short-urls-jekyll/. I followed this exactly, and it’s worked great for me.

4. Setup Hidden Drafts

This feature’s something I’m still testing, and I may end up making edits to this section down the road. At this point, I set this up as described in this thread https://gist.github.com/carlo/2870636.

A few pros and cons on how this works out practically:

Pros:

Cons:

Jekyll Feed documentation seems to suggest this is already a feature, but only if it’s implemented as a _drafts folder, which you will need to run some git code on to build and serve on your desktop.

Here’s how you include a drafts feature with the Indigo theme we are using.

5. Different headers for different pages

At some point, I realized, I didn’t want to see my face at the top of every single page - Blog, About, Project, Consulting, in addition to Home.

The place you can change this is a familiar one - the header.html file we modified in section 2 above. Add the two sections below (line 4, and lines 20 - 25) to the header.html file, and you should now have a more minimal header on all pages except the Home page.

6. Tags and Tag Indexes

This one’s a little involved, but still not too hard. Let’s look at the various phases of this:

  1. Add the ruby script in the plugins folder
  2. Update the tag links inside blog posts to be clickable links
  3. Create a tag index page, just like a blog post page. Also create dummy folders and index.html pages (this is a GitHub quirk) to get the individual tag pages to show
  4. Edit the blog post page to also show the tags
  5. Add a custom header and navigation to the top

The instructions on this came from this excellent post http://erjjones.github.io/blog/Part-two-how-I-built-my-blog by Eric Jones.

Step 1. Add the ruby script in the plugins folder

For the next three steps, note that your tags can be displayed in three places:

This will change the non-hyperlinked tags displayed in your post to clickable links. Your final result may not look like this, but play with the appropriate CSS to get it looking that way.

Step 3. Create a tag index page and folder structure

Here’s the code for creating tag index pages:

That’s it - you now have a working tag feature on your blog!

Step 4. Edit the blog post page to also show the tags (OPTIONAL)

This one is optional - only if you want the blog home page containing the list of all your blog posts to also show the tags associated with each post. Currently these tag links aren’t clickable from the home page - when you click on that row, it’ll lead to the blog post you just clicked.

You might find that look too busy, or not very useful since the tags aren’t clickable from the main page, so consider this feature optional.

Recall that your _includes/blog-post.html file currently looks like this:

We are going to add one more section of code between lines 5 and 6 to display the list of tags on the main page.

Here’s the updated file with the new code from line 6 to line 14:

The tags should now show up on your blog post home page. Your final result may not look like this, but play with the appropriate CSS to get it looking that way.

Step 5. Add a custom header and navigation to the top

The top of this tag index page probably looks a little bare right now.

If you recall, in section 5 of this post, we created custom minimal headers for the pages other than the Home page. We would want those minimal headers with the navigation to be visible at the top of the tag index pages too.

The minimal header should now show for your tag index pages as well.

And that’s it folks! I’ll continue updating this series as I add more features, but thanks for following along and comment on this post or message me if you have any questions / suggestions.

Arti Annaswamy

Arti Annaswamy

Data analytics, process improvement, project management, coffee drinking

comments powered by Disqus
rss facebook twitter github youtube mail spotify instagram linkedin google pinterest medium vimeo