My previous attempt at setting up a Jekyll blog was successful, but I did not like the theme I was using. This time I will try the HPSTR theme by Michael Rose. I have Jekyll installed already, but I think bundler will install it again. I have a GitHub account. I’ll delete the previous repositories and start fresh. I am doing this on a MacBook Pro running Mac OSX 10.10.5.
Install Bundler
$ cd ~
$ sudo gem install bundler
$ cd ~/Sites/oppenheimer-blog
$ bundle install # I got errors
Create a file called Gemfile in the new repository.
$ cd oppenheimer-blog
$ nano Gemfile
Add the lines:
gem 'github-pages'
source 'https://rubygems.org'
Save and exit.
Finish installation. Note: I had some errors installing nokogiri. After Googling around and trying a few things, I came upon this solution on Stackoverflow.
$ sudo port selfupdate
$ sudo port upgrade outdated # this took a long time
$ sudo port install libiconv libxslt libxml2
$ sudo gem install nokogiri -- --use-system-libraries --with-xml2-include=/usr/include/libxml2 --with-xml2-lib=/usr/lib/
$ cd ~/Sites/oppenheimer-blog
$ bundle install # Success!
Install Octopress
$ sudo gem install octopress --pre
Octopress 3 is due out soon, so I may wait before I dive into learning Octopress.
Fork a Theme
I’ve decided to try the HPSTR theme from Michael Rose.
I forked the theme to my Git repository. I have previously set up ssh keys for authentication to GitHub.
Clone the theme to my local repository.
$ cd ~/Sites
$ git clone git@github.com:dgoppenheimer/hpstr-jekyll-theme.git
$ cd hpstr-jekyll-theme
Try the bundle install again in the hpstr-jekyll-theme directory.
Bundle complete! 4 Gemfile dependencies, 38 gems now installed.
Use bundle show [gemname] to see where a bundled gem is installed.
Rename the repository on GitHub. Go into the repo, and click Settings. Change the repo name to oppenheimer-blog and click Rename. Also update the existing local clone.
$ git remote set-url origin git@github.com:dgoppenheimer/oppenheimer-blog.git
Rename the local directory.
$ cd ../ # move out of the hpstr-jekyll-theme directory
$ mv hpstr-jekyll-theme oppenheimer-blog
$ cd oppenheimer-blog
Give it a whirl. Note: I changed a file in the images directory.
$ git add .
$ git commit -m "added my profile photo; changed avatar.jpg to avatar-orig.jpg"
$ git push
$ git checkout gh-pages
$ git merge --no-ff master
$ # there were several conflicts
$ git log
$ git reset --hard 16638192f5
$ git checkout master
$ # delete local and remote gh-pages branches
$ git branch -d gh-pages
$ git push origin :gh-pages
$ git checkout -b gh-pages # create new, fresh gh-pages branch
$ git push origin gh-pages
Crank up the local server.
$ # in the oppenheimer-blog directory, on the gh-pages branch
$ bundle exec jekyll serve
Check http://localhost:4000 for the site. Success!
Testing the Site on GitHub Pages
The site should be visible at http://dgoppenheimer.github.io/oppenheimer-blog/. However, it is lacking the css.
Start by following the tips on the Jekyll site. Start by looking at the base url option in _config.yml. While I’m at it, I’ll change a few of the other options like Site name, etc.
In the oppenheimer-blog directory:
$ git status
$ git commit -am "changed _config.yml"
$ git push origin gh-pages
$ git checkout master
$ git merge gh-pages
$ git push origin master
$ bundle exec jekyll serve --baseurl '' # to test locally
So the changes I made to _config.yml did not completely destroy the site. I can access it locally, and all the links work. Now I’ll see if I can get it to work on GitHub Pages.
Workflow:
Make sure you are on the gh-pages branch.
$ git branch
gh-pages
master
$ # make changes to _config.yml
$ git commit -am "made changes to _config.yml"
$ git push origin gh-pages
Check site at http://dgoppenheimer.github.io/oppenheimer-blog/
I finally got it to work. It helped to view page source in Safari and look at the path that was being used. Then I could go back to _config.yml and adjust the url option. I eventually used url: http://dgoppenheimer.github.io/oppenheimer-blog and baseurl: /oppenheimer-blog.
When developing locally, change the url option to http://localhost:4000 and use bundle exec jekyll serve --baseurl ''.
Customizing the Site
Header
Add a bio to the _config.yml file.
Images
Crop images to 1024 x 256 pixels
Excerpts
Change {{ post.content }} to {{ post.excerpt }} in index.html in your site’s root directory. Right below {{ post.excerpt }}, paste
<p><a class="btn" href="{{ site.url }}{{ post.url }}">Continue Reading</a></p>
The above code places a “Continue Reading” button right below the excerpt. I got this code from the post, Customise HPSTR Jekyll Theme, on the lsfalimis blog. Also in this post I learned how to escape the liquid tags in code blocks.
Add excerpt: to the YAML front matter for each post and write a unique excerpt for each post. Do not use Markdown when writing the excerpt in the front matter.
Deleting the Master Branch
Since I was planning to keep the gh-pages and master branches in sync anyway, I thought I should just delete the master branch to keep things easier. I got these instructions from Oli’s blog.
Make sure that you are in the oppenheimer-blog directory and on the gh-pages branch.
$ git status
On branch gh-pages
nothing to commit, working directory clean
Go to GitHub and change the default branch to gh-pages for the oppenheimer-blog repository. Click on the repository name, then Settings > Branches. Change the default to the gh-pages branch and click Update.
Delete the master branch on the remote (GitHub) and locally.
$ cd ~/Sites/oppenheimer-blog
$ git push origin :master
$ git branch -d master
Enabling Disqus Comments
Follow the instructions from the accepted answer to this question on Stackoverflow. The instructions from Disqus are here.
Briefly:
Register on Disqus.
Add comments: true to the YAML front matter.
Modify the disqus_comments.html file in the _includes directory. Replace the example site.disqus_shortname with the disqus shortname you received when you registered your site. I also added this line so I could test the site locally:
// var disqus_developer = 1; // Comment out before you push to gh-pages
I added these lines as well.
var disqus_identifier = "{{ site.disqus_shortname }}{{ page.url | replace:'index.html','' }}";
var disqus_url = '{{ site.url }}{{ page.url }}';
var disqus_title = '{{ page.title | slugify }}';
Enabling Google Analytics
Wow. This theme is so well-designed that all you have to do to enable Google Analytics is to place your Tracking ID in the appropriate place in the _config.yml file. Neat.
Workflow
Write a post using Markdown. Name it according to Jekyll conventions and put it in the _posts directory. Then commit it locally and push it to GitHub.
$ cd ~/Sites/oppenheimer-blog
$ git status
$ git add .
$ git commit -m "a message about the post"
$ git push origin gh-pages # check site at http://dgoppenheimer.github.io/oppenheimer-blog/
—and Bob’s your uncle!