How to Blog in Markdown Using GitHub and Jekyll Now

John John (304)
10 minutes

I've wanted to start blogging again after a few years off. I was thrilled to find that I can blog using markdown in Vim and publish using git. This guide will show you how to use Github pages to set up a blog and how to publish your first post.

github×1
git×1

Howchoo is reader-supported. As an Amazon Associate, we may earn a small affiliate commission at no cost to you when you buy through our links.

Sign up for a GitHub account

If you don't already have a GitHub account, go ahead and sign up on GitHub.

Fork Jekyll Now and rename the repository yourgithubusername.github.io

Go ahead and fork the Jekyll Now repository. To fork simply click the link, and find the button that says "Fork". If necessary, choose where you want to fork the repository. Then rename the repository to: yourgithubusername.github.io

This step is only required if you want to manage your blog from your local machine. Otherwise you can post directly from Github's site.

To clone the repository (unix), first go to the directory that you want to hold the repo. I usually put things like this in a folder in my home directory called Developer.

cd ~/Developer

Now type the following, replacing the variable with your Github username:

git clone git@github.com:{your github username}/{your github username}.github.io.git

For clarity, mine is:

git clone git@github.com:josephtyler/josephtyler.github.io.git

With the repository forked and renamed, now it's time to customize the details. To do this simply open up the file in the root level of the repo called _config.yml. You can edit this file right in Github or on your local machine if you've cloned the repository. Read through the file and change out all of the necessary settings. This file lets you customize things like your name, site description, social media links, etc. Here's an example:

#
# This file contains configuration flags to customize your site
#

# Name of your site (displayed in the header)
name: Your Name

# Short bio or description (displayed in the header)
description: Web Developer from Somewhere

# URL of your avatar or profile pic (you could use your GitHub profile pic)
avatar: https://raw.githubusercontent.com/barryclark/jekyll-now/master/images/jekyll-logo.png

At this point you can customize or remove the About page. To customize edit the file:

about.md

If you want to add other pages, you'll need to edit the navigation menu in:

_layouts/default.html

and add a link to the page you want to create. Following the example of the about page, and make your link point to:

{{ site.baseurl }}/page-name

and name the file:

page-name.md

You can simply copy the about.md file and change the name. At this point you'll need to commit your changes (and push).

You'll notice that the home page of your blog shows a post that you didn't write. The easiest way to write your first post is to edit this one.

You can find this post in:

_posts/2014-3-3-Hello-World.md

The construction of the filename is important. You'll first want to change to date to todays date using the format:

yyyy-mm-dd

And then you'll want to change the text "Hello-World" to whatever you are going to call your first post. You'll see that the "Hello-World" portion of the file name is what will be used as the permalink. When you open this file to edit you'll notice a configuration at the top:

---
layout: post
title: You're up and running!
---

Keep the layout as post, but you can edit the title of the blog post. Below this is the body of the post written in markdown. You can edit this as you please.

In order to publish, you'll need to commit (and push).

Future posts can be added by creating a new file using the same format as the previous step.

_posts/yyyy-mm-dd-Permalink-Title.md

After you finish your post, remember to commit to master.

If you're managing the blog from you computer, you'll need to commit and push.

git add .
git commit -am "Added a blog post."
git push origin master

Now that you've got your blog set up and understand the basics, you can start blogging, but make sure to take full advantage of all the features of markdown by mastering markdown.

We can't help you write one, but we can help you lay it out!
Michael Michael (175)
3 hours

So you've written that book and want to self-publish it using InDesign? Maybe you're starting a small press and looking to layout your first book?