Why Jekyll and Github Pages
Jekyll is an static site generator, it is simple to use with YAML front matter. It is quite convenient to blog with markdown and Jekyll supports it build-in. Github Pages provide the space to host the website for free. Both of them are well-documented, and works well with each other. One thing that makes they works well but not perfect is that although Github Pages can generate the website using Jekyll but as it generates in safe mode, it does not support Jekyll plugin. However, the good news is we can generate the site locally and then push it to Github. It sounds like not convenient but we can write a bash script to do so automatically in one step. We will talk about it later.
- Know YAML front matter is something you can put at the front of a script and it can automatically
- have part of the layout and tags you defined before
- define variables (Liquid)
- Be able to using
gitcommands, if not please check Git tutorial or search on Google. You could use a desktop version instead of command lines, but I think it's better to try comment line once because it may help you to have a better understanding of how it works.
Set up repository
Following the steps on Github Pages to initiate the repository. Caution: If you are building user/organisation pages, please use
master branch, if you are building project pages, please use
Install and Initiate
Steps are shown here.
After installation, to initiate a basic theme Jekyll website at current folder, simply run
If you have a error says the directory is not empty, just move all files to other directory and move them back after initiation.
Running Jekyll and Test Websites Locally
If you use
bundler, you need to use
bundle exec jekyll server or
bundle exec jekyll serve.
For those who don't, please use
jekyll server or
Leave command window as it is running and then open your browser and navigate to
http://localhost:4000 and you can see your site locally.
_config.yml contains settings for the website, check out details at the official website here.
|title||The title of the website, by default it will shown at the website and the search result in a search engine|
|It is used in the contact list if you choose to use it|
|description||By default it is used in the meta tag in the head and shown in the footer|
|baseurl||the subpath of your site, e.g.
|url||the base hostname and protocol for the site, e.g.
|shown in the contact list in the footer if you wish|
|markdown||which markdown engine you want to use, e.g.
|highlighter||which syntax highlighter you want to use, e.g.
you can set your own like
|pagination||the number of posts you want to display on each page|
Host your website using custom domain
- you need to buy a domain from a domain registrar, like Godaddy.
- add a
CNAMEfile which contains your custom domain name in the root of your repository.
- If your custom domain is a subdomain (like
blog.pwzxxm.com), then you need to add a
CNAMErecord in your domain provider or DNS server provider if you are using custom DNS service.
- If your domain is an apex domain (only have one dot in your custom domain), you need to set up
18.104.22.168to your records.
- Find more details
Check out Jekyll Multi Language Plugin.
Build the site locally if you use plugins
The problem is Github build Jekyll websites in safe mode so the plugin won't work. However, we can create a 'dummy' repository to generate the site first and then move the content in
_site folder to the original repository.
- generate the site locally using
bundle exec jekyll serve buildor
jekyll buildin the 'dummy' repository.
- copy all files to the actual repository excludes
- cut the files under
_sitefolders to the root path of the repository.
touch .nojekyllto disable github to generate the site
- commit all changes.
Here is a bash script:
#!/bin/bash comment="$1" push_commit="git commit -a -m '$comment'" # commit and push changes eval 'cd ~/git/local' # modify PATH here eval 'bundle exec jekyll build' eval 'git add .' eval $push_commit eval 'git push --all origin' # copy remove in pwzxxm.github.io eval 'cd ~/git/PwzXxm.github.io' # modify PATH here eval 'cp ./README.md ~/git/' # modify where you want to temporally put the README.md eval 'rm -rf ./*' eval 'cp -r ~/git/local/* ./' # modify PATH here eval 'cp -r _site/* ./' eval 'rm -rf _site/*' eval 'cp ~/git/README.md ./' # put the file back eval 'touch .nojekyll' # commit and push changes eval 'git add .' eval $push_commit eval 'git push --all origin' echo "Done"
To use it, simply copy it to a
yourchoice.sh file, change the paths in the file and give it permission to run, and run it.
If you like the style or you want to know the codes behind it, just check out:
You can grap and use any code from my site as you wish. However, the content of this site is copyright, if you want to use any posts please contact me.