Edit 07/04/2016: I have now installed Jekyll in the root directory itself, but following tutorial still holds.
Jekyll is one clever way of having a blog which doesn’t require you to have any Database or Backend server. All it does is generate Static HTML pages from Markdown format which you can directly host on the Github Pages. Here I will step-by-step guide on how to host a website and blog all from GitHub pages.
- Estimated time: 15 Minutes
- Outcome: GitHub website and blog hosted similar to http://shahrajat.github.io and http://shahrajat.github.io/blog
Hosting a static website on GitHub (without Jekyll)
Note: You can do the following entirely from GitHub website without the need of having to create a repository locally and then pushing it through terminal.
- Create a new GiHub repository named
index.htmlin it in the root directory it self.
- Your website should now be accesible from
Or, if you prefer to have a project website, simply push the static HTML pages to a new gh-pages branch and it will be accessible from
Hosting Jekyll Blog in subdirectory
I have my Homepage of the website shahrajat.github.io hosted with some static HTML pages I wrote. However, I don’t want to have my blog hosted on the Homepage itself, instead I have it hosted at
shahrajat.github.io/blog. To achieve this, follow these steps:
- Install Ruby: Since Jekyll runs with Ruby, you will need to have Ruby. If you are Mac and have home-brew installed, simply run
brew install ruby.
- Install Jekyll: Jekyll is like any other gem in Ruby which you can install with
gem install jekyllor
sudo gem install jekyll.
- Create a new empty repository named
blogon GitHub through the website.
- Clone this repository locally with
git clone YOUR_REPOSITORY_LINK. For example
git clone https://github.com/shahrajat/blog.git.
- From the parent directory of
jekyll new blog. This will create a new blog in the
blogfolder. Now move to blog folder with
- Now, the key thing is, unlike other User/Organization sites (the ones hosted on
username.github.io) which are contained in
masterbranch, the Project Sites (like in the
blogsubdirectory) should be in a branch named
gh-pages. So you need to commit the entire website (the repository named
blogwhich you created) on this branch instead of the
- To do this, create and switch to a new branch with
git checkout -b gh-pages.
- You can test you website locally by first building the website
jekyll buildand running the server with
jekyll serve. Visit http://127.0.0.1:4000 to view it.
- Add, Commit and Push: run
git add -A,
git commit -m "Initial commit"and
git push origin gh-pages.
- Updating _config.yml: If you visit http://username.github.io/blog you will have the HTML any CSS. This is because the the configuration in default Jekyll setup doesn’t know that you expect the base folder to be in
/blog. You can achieve this with editing the
_config.ymlfile and adding these variable to it:
That’s it! Your new blog should now accessible from
Editing Markdown using GitHub is painful. A better approach is to use an online Markdown editors which are close to WYSIWYG editors. My favorite currently is http://prose.io/ which allows linking github account to it so that you can directly browse your repositories/source files, edit them and see a preview before committing.
For installing Ruby and Jekyll: https://scotch.io/tutorials/getting-started-with-jekyll-plus-a-free-bootstrap-3-starter-theme.
For installing Jekyll in a subdirectory: http://stackoverflow.com/questions/23417062/getting-jekyll-running-just-for-a-subdirectory-on-github?rq=1
Jekyll basics: http://jekyllrb.com/docs/usage/