Starting a blog with Poole and Github Pages
Why?!
Starting a blog with Poole and Github pages is the easiest way for a programmer to have a blog online without paying for hosting while still having world class delivery.
How?
The following instructions are what I used to get going and I’m writing it here for me to keep a record for myself. At the same time, point any one that is interested as well.
I originally followed this article found it fantastic. Many parts of my article will be very similar. Thanks Josh!
The following instructions are meant for someone that has some familiarity with git and Github. If you need help on any part (even git) I can be reached by my contact page
The blogging system used will be Jekyll, a static site generator using Ruby. Instructions for its dependencies the as follows:
Get rvm
rvm is Ruby Version Manager and is a great way to manage different versions of Ruby and gems. I have it installed on even a vanilla Linux system since the built in version of Ruby on most operating systems are a bit out of date.
Get rvm here: http://rvm.io
Install Ruby with rvm
Make sure there’s a more recent version of Ruby installed on the system by running the rvm command:
rvm install ruby-2.1.5
tell rvm use use the ruby just installed:
rvm use 2.1.5
check that Ruby 2.1.5 is installed by running:
ruby -v
and the response on Linux will be:
ruby 2.1.5p273 (2014-11-13 revision 48405) [x86_64-linux]
note: at the time of this writing, ruby 2.3+ is out, but I have found 2.1.5 to be easier to get going with all associated gems. :-D
Install nvm
nvm is the node equivalent of rvm. It allows multiple versions of node to be installed at once. Node is required for Jekyll to handle JavaScript rendering.
To install in Linux:
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.2/install.sh | bash
For other instructions and additional details: https://github.com/creationix/nvm
Install node with nvm
nvm install 4.0.0
then tell nvm to use installed version by running: nvm use 4.0.0
check node is the right version by running command: node -v and the
response will be: v4.0.0
Get Jekyll Gem
Jekyll is the blogging system I use to write, publish, and manage my blog. I love it because it’s basically a blog system by a programmer for a programmer.
gem install jekyll
check that Jekyll is installed by running:
jekyll -v
If a huge error starting with: 'autodetect': Could not find a
JavaScript runtime. See https://github.com/rails/execjs for a list of
available runtimes. (ExecJS::RuntimeUnavailable)
Make sure node is installed, running and using version 4.0.0 or above.
Get Poole
Jekyll by itself does not come with very much to start with. Poole is a world-class Jekyll theme for mobile and desktop to help get started right away.
Clone the Poole repo to a local folder by running command:
curl -Lo poole.zip https://github.com/poole/poole/archive/v2.0.0.zip
unzip file by running: unzip poole-2.0.0.zip
Test out site:
If running on a local machine, run: jekyll serve and open a browser
to: http://localhost:4000
(If running on a remote server (i.e. EC2), add: --host 0.0.0.0, so
the command is: jekyll serve --host 0.0.0.0 and open a browser to:
http://remote.server:4000
Jekyll is running in server mode and has output:
acl@edam:~/src/poole-2.0.0$ jekyll s --host 0.0.0.0
Configuration file: /home/acl/src/poole-2.0.0/_config.yml
Source: /home/acl/src/poole-2.0.0
Destination: /home/acl/src/poole-2.0.0/_site
Generating...
done.
Auto-regeneration: enabled for '/home/acl/src/poole-2.0.0'
Configuration file: /home/acl/src/poole-2.0.0/_config.yml
Server address: http://0.0.0.0:4000/
Server running... press ctrl-c to stop.
The page should look like the demo site on Poole.
Push repo to Github page repo
Goto Github and signup/login. Create a
new public repository with the name: #{ID}.github.io, where #{ID}
is a github username. My personal github ID is: a-leung, so the repo
name will be: a-leung.github.io.
Change into the poole directory and run the following commands to initialize the git repo and push to github:
git init
git add .
git commit -m 'initializing site with poole'
git remote add origin [email protected]:a-leung/a-leung.github.io.git
git push -u origin master
note: change a-leung/a-leung.github.io to your github ID.
Open site in browser
Goto: http://#{ID}.github.io and see the Poole site! (or checkout
mine: http://a-leung.github.io.
Congratulations, the site is now accessible to the world!
Blog
Cool. Now the blogging infrastructure has been setup, start creating posts!
Filename in Jekyll
Every post in Jekyll resides in the _posts directory and have a name
format: YYYY-MM-DD-title-of-post.md. Use an editor and create a new
file with this name:
2016-07-15-starting-a-blog-with-poole-and-github-pages.md
File content
In the file add the following content:
---
layout: post
title: Starting a blog with Poole and Github Pages
---
# Why?!
Starting a blog with Poole and Github pages is the easiest way for a
programmer to have a blog online without paying for hosting while
still having world class delivery.
The items between ---:
---
layout: post
title: Starting a blog with Poole and Github Pages
---
is called the front matter, and this tells Jekyll how to process the file. This file will be a post, with title: “Starting a blog with Poole and Github Pages”.
Build site with new post
With the new post created in the _post directory, Jekyll will build
a new site, putting the posts in date order and re-arranging every
page by running command: jekyll build
Optional: changes can be seen before pushing by running Jekyll serve:
jekyll serve and opening browser browser to the local Jekyll
http://localhost:4000, just like
before
Publish new site
Now that the new site looks good with
Add changes to the git repo:
git add .
git commit -m 'ARTICLE: Starting a blog with Poole and Github Pages'
git push origin
Open in browser the github page before now will look like:
Profit!
Now comes the really hard part: writing! So the blogging framework/infrastructure is done, this is the routine I follow:
- make new posts in the
_postsdirectory - run:
jekyll build - commit changes to git repository:
git add .; git commit -m 'ARTICLE: new post' - push to github:
git push origin
Conclusion
Whew, lots of detailed setup work, but it’s a great workflow for me. Again, if help is needed, please contact me. It took work for me to figure things out, and I will help you to get going as well.