How to setup Jekyll Blog Hosted on GitHub Project Pages
This blog post documents the setup done to create Data Gallery Blog and instructions on how to create and add a new post.
Instructions used to create the Data Gallery Blog can be found on Jekyll on Github Pages and Jekyll Documentation. They include configuration options, plug-ins and theming not included in this post.
Installing ruby
Jekyll requires the Ruby language. If you have a Mac, you’ve most likely already got Ruby. To confirm if you have the required 1.9.3 or 2.0.0 version, open up the Terminal application, and run the command:
ruby --version
If you have older version, follow these instructions to install Ruby.
Installing Bundler
Bundler is a package manager that makes versioning Ruby software a lot easier if you’re going to be building GitHub Pages sites locally. You don’t have to use it, but it’s recommended and the instructions in this document assume that you are using Bundler.
gem install bundler
Installing Jekyll
Create a file in your site’s repository called Gemfile
and add the line gem 'github-pages'
and run:
bundle install
Creating new blog site
To create a new bog site, run:
jekyll new myproject
myproject
will be the repo name and a directory name where the blog will be located. If you are using github project pages, it will also be a part of the url (https://username.github.io/project). If you want to use GitHub User or Organization pages, follow those instructions instead.
Adding content
In the _posts
directory, crate your content file in this format: ‘YYYY-MM-DD-your-title.md’.
Add the section about markdown & metadata.
Editing config
Edit about.md
.
Publishing on GitHub
Create a new repo called myproject
. Follow those instructions.
On a command line, inside “project” directory, run:
git init
Next, create new branch called “gh-pages” by running those commands:
git branch gh-pages
git checkout gh-pages
To check the current branch:
git branch
There is one more config file change that needs to be made to run the blog on GitHub Pages. Add those two lines to _config.yml
:
url: https://username.github.io
baseurl: project
If you are using custom domain names, then use this url line url: "https://customomain.com"
instead. In our case we are using
url: "https://www.datagallery.io/"
baseurl: "/blog"
Finally, add and commit all changes to GitHub:
git add .
git commit -m"your comment goes here"
git push origin gh-pages
In your browser, view https://username.github.io/project
. In case of this project the url is https://www.datagallery.io/blog/.
Running Jekyll locally in GitHub Pages Environment
To run Jekyll in a way that matches the GitHub Pages build server, in the root of your repository (after switching to the gh-pages branch for project repositories), run Jekyll with Bundler:
bundle exec jekyll serve --baseurl ''
The site should be available at https://localhost:4000. For a full list of Jekyll commands, see the Jekyll documentation.
Running Jekyll locally (the classic way)
Inside the “project” directory:
jekyll build
jekyll serve
In your browser, view https://localhost:4000.
The _sites
directory is generated by Pelican and can be deleted and regenerated at any time.