cat

Step 1: Create a website hosted by GitHub Pages

If you haven’t, follow the official GitHub Pages to create a website. If you have a custom domain (like me), you can configure the custum domain to link to the GitHub hosted site, by following this tutorial.

Step 2: Blogging with Jekyll

I recommend you to first learn the basics about Jekyll here. In the default set up, GitHub will automatically build the HTML pages with Jekyll as well as host the blog for you. However, this set up requires Jekyll related files to be under the root folder of the repo, which prevents us from hosting both the personal website and the blog.

Fortunately, a workaround was proposed in this article. Instead of letting GitHub auto build the site for us, we can build the site offline and directly use the genearted HTML files for our website. To prevent the GitHub Pages from throwing a Jekyll build error, we need to create a .nojekyll file in the root folder as described here.

I recommend you to start the blog with an existing template/theme. There are many blog themes available on the Internet for free (for example here and here). For me, I chose to reuse the theme built by Andrej Karpathy, as I love Andrej’s blogging. You can checkout my GitHub repo to see the details about how I organize the files.

Step 3: Write your first blog!

Once you finish the first two steps, you are now ready to write your first blog.

To write a blog, it is as simple as adding a Markdown file to the _posts folder. For example:

cd <path>/<username>.github.io/jekyll/_posts

Then use your favorite Markdown editor to create the blog .md file and add/save it to this folder.

To locally test the site, follow this official tutorial to install the needed tools and then run the following commands Testing your GitHub Pages site locally with Jekyll.

cd <path>/<username>.github.io/jekyll/
bundle exec jekyll build
bundle exec jekyll serve

Then you can view the site locally e.g. by going to http://127.0.0.1:4000/blog. Note that the the build step is mandatory as we will use its offline generated HTML pages for the blog site.

To let GitHub co-host your personal site and the blog, We will not let GitHub build the Jekyll online but rather directly use the Jekyll generated static HTML pages. To do that we create a virtual link from the blog folder to the _site folder, such that when we go to blog/index.html it will call the _site/index.html where the later is generated by the Jekyll.

ln -sv jekyll/_site blog

Finally, we add all the files in _site to our repo. After commiting and pushing the code, your first blog will be online.

Happy blogging!