GitHub pages serves web sites using Jekyll, which builds static pages from your liquid files. This build however, is not always successful. In this post, I tried to list most common GitHub Pages build errors and their fixes.
Common Github Pages errors and their fixes
There was a YAML syntax error on line 2 column 14 in
mapping values are not allowed in this context. For more information, see https://help.github.com/articles/page-build-failed-invalid-yaml-in-data-file/.
This error generally caused by using an illegal characters on front matter part of a post or page. For example in my case I used
: in post title. It can be easily fixed by either removing illegal character or quoting title text like this:
--- layout: post title: "Python: How to do stuff in python" desc: My awesome description for page ---
A file was included in
python/_posts/2013-12-25-python-quickstart-for-programmers.mdthat is a symlink or does not exist in your
_includesdirectory. For more information, see https://help.github.com/articles/page-build-failed-file-is-a-symlink/.
This error message is rather descriptive. It is generally caused when you misspell or rename a include template. In my case, I renamed a template and forgot to fix that on an old post.
There was a YAML syntax error on line 2 column 1 in
did not find expected key while parsing a block mapping. For more information, see https://help.github.com/articles/page-build-failed-invalid-yaml-in-data-file/.
This error occurred when I tried using liquid tags on front matter of a post. Unfortunately, you can’t use liquid on front matter of GitHub pages. For self hosted Jekyll sites however there are some workarounds. However, you can use replace filter before using your variable on page content, if that works for your case of course.
Was build successful?
GitHub Pages may not send you definitive error messages every time your page build fails. Actually you can easily debug your pages using commits log on your repository.
First, open your repository page on web browser and click on commits.
You will see a small icon next to each commit. This small icon shows progress of the page builds. If you see a yellow circle, this means your page build is on progress. If you see a green tick, this shows that last page build was successful.
If you see a red cross this means that your page build has failed. You can click commit code button next to that line to understand where the build has failed.
GitHub Pages is a really great platform if you like commit & push publishing. Gives you more control on your content, makes your site faster than 90%. On the other hand, It is a little harder to troubleshoot. I hope this guide helps you on your way.