Host your own blog with Jekyll and Github Pages
Github allows you to host your own websites via Github Pages. With a tool called Jekyll you are able to create pages for your website written in Markdown. Let us explore how we can set up our own blog hosted on Github Pages. Additionally, let us configure a custom domain for our website! This very blog is hosted exactly that way!
- make sure that Jekyll is installed
- make sure that git is installed
- make sure that you have a Github account
1. Repository setup
Create a new repository in Github that follows the following naming convention and initialise it with a
This repository will host both our source files (Jekyll) and will also contain a branch that contains the generated files for Github pages. Once checked out locally, let us create a custom orphan branch like this:
git checkout --orphan gh-pages \ && git commit --allow-empty -m "initial commit" \ && git push -u origin gh-pages \ && git checkout main
Then head into
Settings->Pages of your repository in Github and set your source branch of Github pages:
This will ensure that Github looks up any content on that branch and serves it automatically at the following url:
2. Jekyll setup
Next up, let us configure Jekyll on the
main branch. Keep in mind that
main has a different git history to
gh-pages. We will not directly commit anything to
gh-pages - instead, we host all the Jekyll files on the
main branch only and let the Github Action do the rest!
Let us configure Jekyll by generating a new site:
jekyll new --skip-bundle .
(optional) build and test the Jekyll site locally:
bundle install && jekyll serve
and then head over to http://127.0.0.1:4000 to view your page locally:
push your Jekyll site to Github:
git add -A \ && git commit -am "setup Jekyll blog" \ && git push origin main
3. Github Action
The Jekyll source files are sitting now on the
main branch but we want to automatically build our website like we used to do earlier locally. For this we will use a Github action. This action will build our website and then force-push it to the
Create a new file under the folder
.github/workflows/github-pages.yml. Github will look for any files hosted in the
.github/workflows folder and run a so called action. Within that file, define the following:
name: Build and deploy Jekyll site to GitHub Pages on: push: branches: - main jobs: github-pages: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: helaili/jekyll-action@v2 with: token: $ target_branch: gh-pages
This action will automatically take care of building your Jekyll page and pushing it to the
gh-pages branch. Before this works we need to define a custom github token, as the default
GH_TOKEN will not work within actions.
Make sure to set this token to never expire and assign the following permissions:
- write:packages (optional)
- delete:packages (optional)
ATTENTION! NEVER reveal any of your tokens or hardcode them into your code. Hackers will use them to compromise your account!
Copy the token that is shown and define a new secret within your repository called
Next, push your changes to your repository:
git add -A \ && git commit -m "Setup workflow" \ && git push origin main
Within your repository on Github you should now seen a new action getting triggered:
4. (optional) Setup custom domain
Having a long url such as https://bitbrain.github.io works but does not look very good on your CV. You can setup a custom domain like I have: https://bitbra.in this page is hosted on Github Pages but has a custom domain setup.
Create a new file called
CNAME that contains your domain, for example:
and commit and push that file. Now, head to
Settings->Pages to setup your domain:
This will only work if you own the domain and you configured your CNAME entry correctly within your domain provider. Follow this guide to learn how to set up your custom domain within AWS.
Let me know in the comments if you face any issues so I can keep this guide up-to-date! If you want to use the custom Jekyll theme of this blog, feel free to checkout this guide!