For my blog I’m using Github pages to host the static content generated by Hugo. Hugo is a static site generator which creates web pages from markdown files you write. That way, when you don’t want to be bothered with styling your blog, you can just choose a theme from a vast collection, and you’re done. Just write some posts in markdown run the hugo command, and you will find all the static content in the public directory, ready to deploy to a web server, or, in my case, Github pages.

First of all I created two repositories, one that holds the Hugo content, the posts in markdown, the configuration files etc. You can name this repo whatever you like, the name of your blog is a good choice, like I have done, but the second repo has to be named <USERNAME>.github.io for Github pages to work. This repo will hold the static content generated by Hugo, the public directory of the Hugo directory structure basically.

Once you have done this, clone the first repository, the Hugo content, somewhere on your computer:

git clone git@github.com:<USERNAME>/<REPO_NAME>.git

I use git over SSH but you can also use HTTPS.

Then go inside the newly created repo:

cd <REPO_NAME>

Once you have done this, you can paste the Hugo content in the repo folder, or create a new site inside the repo folder with:

hugo new site

The second thing I did was replace the public directory with a submodule, so first I remove the public directory:

rm -rf public

And then I added it back as a git submodule:

git submodule add -b master git@github.com:<USERNAME>/<USERNAME>.github.io.git public

For my blog I use the ezhil theme. I also add this theme as a submodule to my blog’s repository:

git submodule add -b master https://github.com/vividvilla/ezhil.git themes/ezhil

This is a step specific for my site, or also for your site, if you choose to also use the ezhil theme. But when you use a different theme, you should change the git url, and change the directory from theme/ezhil to theme/<YOUR_THEME_NAME>.

Once you have done this, you can start to create articles. When you have done:

hugo new posts/my-first-post.md

And wrote a nice post you are happy with. You can push this post to your blog’s repo:

git add content/posts/my-first-post.md
git commit -m 'Add my first post'
git push

Once you have done this, and you go to <USERNAME>.github.io, you will not see your first post appear. This is because we only pushed the Hugo content, but not the static content Hugo generated. We will do this now:

hugo
cd public
git commit -am 'Add my first post'
git push

These commands will first of all build your static content, and put them in the public directory, the hugo command does this. Then we change inside the public directory, there we will stage and commit all the newly created and/or changed static content. Normally it’s not really good practice to just stage every change with something like git add . or git commit -a, it’s better to think about what you commit. But this is static content that’s just generated, and we can trust Hugo to have done to have done this correctly.

Now, when you go to <USERNAME>.github.io, you should see your new post appear, congratulations!

The last thing I always do, is update the submodule in my main repo:

git add public
git commit -m 'Update public submodule'

This way, the submodule always points to the latest commit of the public repo.

This is how I run my blog, I also use a custom domain for my blog, but to this, you just have to click around a bit in the interfaces of you domain provider, and the Github settings page for your repo. If you want to do this, you can find more information here.