How to build your personal blog using GitHub Pages + Jekyll


Beginner level

My (your ?) aim

Build a personal blog with a URL.

My (your ?) current status

I searched on the web and heard of words like GitHub pages, Jekyll, but… well, I still don’t know what they are exactly & how to use them. I’m not experienced in website building, but it’s actually quite very easy.


  1. I’d like to know a bit more about GitHub Pages first: press here

  2. I just want to create my blog now: step-by-step tuto

  3. There is nothing I want here. I’m leaving.

About GitHub Pages

(It’s certainly not exhaustive, I just wrote about what I’ve looked at and selected the parts I found useful)

What’s GitHub Pages ?

I quote from GitHub Help:

[It] is a static site hosting service designed to host your […] pages directly from a GitHub repository.

There is a hard limit of 1GB:

The size of the published site should be < 1GB.

Can I have several GitHub pages ?

Just one with format.

But there can be project websites like,

How to build my blog step-by-step ?

Note: This is just one way to make things work.

1. Create a specific GitHub repo


  • You could actually use as repo name, I used and it also works.

  • If your GitHub account is:
    • Free: your repo of GitHub Pages should be public.
    • Pro/Team/Enterprise Cloud/Enterprise Server: your repo can be public or private. More info here.
  • If you want more info on: how to create a repo in GitHub.

2. Clone your repo to local folder

Using HTTPS:

git clone

3. Install Jekyll + choose a theme

  1. Install Jekyll + bundler

    gem install jekyll bundler

    If you don’t have Ruby yet, here’s a detailed instruction.

  2. Create the blog

    • If you want to create and use the basic template, you can: jekyll new myblogname

    • If you want to use a nice third-party template:

    1. Choose a template

      You can find plenty of nice free Jekyll templates by searching on GitHub, or you can have a look at Jekyll Themes website.

      Actually I found that the default template is quite simple, and the one I’m using is TeXt, so I’ll take this one as example :satisfied:

    2. Clone or download the theme repo.

    3. Copy the files that you need to your repo.

      The folder structure is like this:

      • Folders such as docs, screenshots, test are not needed for your blog to run.

      • _posts is where your posts will be stocked.

      • _layouts contain the template of different pages that you could directly use.

      If there is a license/notice to be included, please don’t forget to keep them :relaxed:

    4. Run bundle install to install the dependencies.

    It’s now OK for the basic setup.

  3. Write a new Post

    1. Create a new file with a name formatted like

      The template need a correctly formatted name to be able to recognize the infos.

    2. Start to write…

      An example of content:

         layout: article
         title: Explain how to build a personal blog to my Snorlax
         tags: pseudo-tutorial-random
         Hello world !
      • layout corresponds to the various layouts in the folder _layouts.

      • title is the title actually displayed.

    3. That’s all.

  4. Configure your profile

    Just modify the parts you want in ./_config.yml.

  5. (Optional) Add a new Page

    For instance, if I want a new Page named Gallery.

    1. Create a file name and save it in the main folder (or another one, you can change the configurations after if you want to).

      For instance, I can use the article layout for this page:

         layout: article
         My gallery.
    2. Open the YAML file ./_data/navigation.yml and just add the name of your page, for instance:

        - titles:
         en      : &EN       Gallery
         en-GB   : *EN
         en-US   : *EN
         en-CA   : *EN
         en-AU   : *EN
         zh-Hans : &ZH_HANS  相簿
         zh      : *ZH_HANS
         zh-CN   : *ZH_HANS
         zh-SG   : *ZH_HANS
         zh-Hant : &ZH_HANT  圖片集
         zh-TW   : *ZH_HANT
         zh-HK   : *ZH_HANT
       url: /gallery.html

      (Note: If you want to test, avoid calling your test page “test”.)

4. Test it in local

  1. In your terminal: jekyll serve

    If you have an error (like me) saying that:

    You have already activated addressable 2.6.0, but your Gemfile requires addressable 2.5.2. Prepending bundle exec to your command may solve this.


    bundle exec jekyll serve

  2. Open your browser and go to: http://localhost:4000

    Normally you should see your website built.

5. Just push it

If you want more info on how to push to a repo using the command line.

After some time (not very long) you should be able to see what you’ve seen in local at ! :sparkles:

Hope that it helped :smile: