Octopress

What is Octopress?

Octopress is a framework designed for Jekyll, the static blogging engine powering Github Pages. Have a look through the documentation and if you have trouble, I’ll be happy to help. If you find errors in the documentation post an issue or fork and send a pull request on the site branch.

First, I want to stress that Octopress is a blogging framework for hackers. You should be comfortable running shell commands and familiar with the basics of Git. If that sounds daunting, Octopress probably isn’t for you.

Before you begin

Install Git
Install Ruby 1.9.3 using either rbenv or RVM

Setup Octopress

Get the source code from GitHub

git clone git://github.com/imathis/octopress.git octopress
cd octopress    # If you use RVM, You'll be asked if you trust the .rvmrc file (say yes).
ruby --version  # Should report Ruby 1.9.3

Install dependencies

Install bundler

bundler - Ruby Dependency Management

Bundler manages an application's dependencies through its entire life across many machines systematically and repeatably.

See the bundler website http://gembundler.com for information on getting started, and Gemfile for more information on the Gemfile format.

gem install bundler

Install all dependencies using bundle

Defined in the Gemfile.

See the bundler website http://gembundler.com for information on getting started, and Gemfile for more information on the Gemfile format.

bundle install

Sample output

$ bundle install
Fetching gem metadata from http://rubygems.org/.......
Fetching gem metadata from http://rubygems.org/..
Installing rake (0.9.2.2) 
Installing RedCloth (4.2.9) with native extensions 
Installing posix-spawn (0.3.6) with native extensions 
Installing albino (1.3.3) 
Installing blankslate (2.1.2.4) 
Installing chunky_png (1.2.5) 
Installing fast-stemmer (1.0.1) with native extensions 
Installing classifier (1.3.3) 
Installing fssm (0.2.9) 
Installing sass (3.1.20) 
Installing compass (0.12.2) 
Installing directory_watcher (1.4.1) 
Installing ffi (1.0.11) with native extensions 
Installing haml (3.1.6) 
Installing kramdown (0.13.7) 
Installing liquid (2.3.0) 
Installing syntax (1.0.0) 
Installing maruku (0.6.0) 
Installing jekyll (0.11.2) 
Installing rubypython (0.5.3) 
Installing pygments.rb (0.2.13) 
Installing rack (1.4.1) 
Installing rack-protection (1.2.0) 
Installing rb-fsevent (0.9.1) 
Installing rdiscount (1.6.8) with native extensions 
Installing rubypants (0.2.0) 
Installing tilt (1.3.3) 
Installing sinatra (1.3.2) 
Installing stringex (1.4.0) 
Using bundler (1.2.3) 
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.

Install the default Octopress theme

rake - Ruby Make

Rake is a simple ruby build program with capabilities similar to the regular make command.

Rake has the following features:

Rakefiles (Rake's version of Makefiles) are completely defined in standard Ruby syntax. No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?).
Users can specify tasks with prerequisites.
Rake supports rule patterns to synthesize implicit tasks.
Flexible FileLists that act like arrays but know about manipulating file names and paths.
A library of prepackaged tasks to make building rakefiles easier.

rake install

$ rake install
## Copying classic theme into ./source and ./sass
mkdir -p source
cp -r .themes/classic/source/. source
mkdir -p sass
cp -r .themes/classic/sass/. sass
mkdir -p source/_posts
mkdir -p public

Preview locally (default on port 4000)

rake preview

$ rake preview
Starting to watch source with Jekyll and Compass. Starting Rack on port 4000
directory source/stylesheets/ 
   create source/stylesheets/screen.css 
/home/terry/.rvm/gems/ruby-1.9.3-p327/gems/maruku-0.6.0/lib/maruku/input/parse_doc.rb:22:in `<top (required)>': iconv will be deprecated in the future, use String#encode instead.
>>> Change detected at 19:10:39 to: screen.scss
[2012-12-16 19:10:39] INFO  WEBrick 1.3.1
[2012-12-16 19:10:39] INFO  ruby 1.9.3 (2012-11-10) [x86_64-linux]
[2012-12-16 19:10:39] INFO  WEBrick::HTTPServer#start: pid=11949 port=4000
Configuration from /bea/octopress/octopress/_config.yml
   create public/stylesheets/screen.css 
127.0.0.1 - - [16/Dec/2012 19:10:40] "GET / HTTP/1.1" 404 22 0.5959
Dear developers making use of FSSM in your projects,
FSSM is essentially dead at this point. Further development will
be taking place in the new shared guard/listen project. Please
let us know if you need help transitioning! ^_^b
- Travis Tilley
>>> Compass is polling for changes. Press Ctrl-C to Stop.

Deploying to GitHub Pages

3 ways to deploy Ocotopress

GitHub Pages
Heroku
rsync

Of course in this case we use the beloved GitHub way: http://octopress.org/docs/deploying/github/

Use this if you want to host a blog from http://username.github.com (though you can also use custom domains). Create a new Github repository and name the repository with your user name or organization name username.github.com or organization.github.com.

Github Pages for users and organizations uses the master branch like the public directory on a web server, serving up the files at your Pages url http://username.github.com. As a result, you’ll want to work on the source for your blog in the source branch and commit the generated content to the master branch. Octopress has a configuration task that helps you set all this up.

Deploying Static Resources to GitHub

NOTE: The static resources (HTML, XML, JavaScript, images) are generated in _deploy folder.

rake setup_github_pages

Sample output

$ rake setup_github_pages
Enter the read/write url for your repository
(For example, 'git@github.com:your_username/your_username.github.com)
Repository url: git@github.com:terrywang/terrywang.github.com
Added remote git@github.com:terrywang/terrywang.github.com as origin
Set origin as default remote
Master branch renamed to 'source' for committing your blog source files
rm -rf _deploy
mkdir _deploy
cd _deploy
Initialized empty Git repository in /bea/octopress/octopress/_deploy/.git/
[master (root-commit) 1f2c5bf] Octopress init
 1 file changed, 1 insertion(+)
 create mode 100644 index.html
cd -
---
## Now you can deploy to http://terrywang.github.com with `rake deploy` ##

The above

Ask you for your Github Pages repository url.
Rename the remote pointing to imathis/octopress from ‘origin’ to ‘octopress’
Add your Github Pages repository as the default origin remote.
Switch the active branch from master to source.
Configure your blog’s url according to your repository.
Setup a master branch in the _deploy directory for deployment.

Next run

1. rake generate

$ rake generate
## Generating Site with Jekyll
unchanged sass/screen.scss
/home/terry/.rvm/gems/ruby-1.9.3-p327/gems/maruku-0.6.0/lib/maruku/input/parse_doc.rb:22:in `<top (required)>': iconv will be deprecated in the future, use String#encode instead.
Configuration from /bea/octopress/octopress/_config.yml
Building site: source -> public
Successfully generated site: source -> public

2. rake deploy

$ rake deploy
## Deploying branch to Github Pages 
rm -rf _deploy/index.html
## copying public to _deploy
cp -r public/. _deploy
cd _deploy
## Commiting: Site updated at 2012-12-16 08:50:14 UTC
[master f9509ca] Site updated at 2012-12-16 08:50:14 UTC
 61 files changed, 2658 insertions(+), 1 deletion(-)
 create mode 100644 assets/jwplayer/glow/controlbar/background.png
 create mode 100644 assets/jwplayer/glow/controlbar/blankButton.png
 create mode 100644 assets/jwplayer/glow/controlbar/divider.png
 create mode 100644 assets/jwplayer/glow/controlbar/fullscreenButton.png
 create mode 100644 assets/jwplayer/glow/controlbar/fullscreenButtonOver.png
 create mode 100644 assets/jwplayer/glow/controlbar/muteButton.png
 create mode 100644 assets/jwplayer/glow/controlbar/muteButtonOver.png
 create mode 100644 assets/jwplayer/glow/controlbar/normalscreenButton.png
 create mode 100644 assets/jwplayer/glow/controlbar/normalscreenButtonOver.png
 create mode 100644 assets/jwplayer/glow/controlbar/pauseButton.png
 create mode 100644 assets/jwplayer/glow/controlbar/pauseButtonOver.png
 create mode 100644 assets/jwplayer/glow/controlbar/playButton.png
 create mode 100644 assets/jwplayer/glow/controlbar/playButtonOver.png
 create mode 100644 assets/jwplayer/glow/controlbar/timeSliderBuffer.png
 create mode 100644 assets/jwplayer/glow/controlbar/timeSliderCapLeft.png
 create mode 100644 assets/jwplayer/glow/controlbar/timeSliderCapRight.png
 create mode 100644 assets/jwplayer/glow/controlbar/timeSliderProgress.png
 create mode 100644 assets/jwplayer/glow/controlbar/timeSliderRail.png
 create mode 100644 assets/jwplayer/glow/controlbar/unmuteButton.png
 create mode 100644 assets/jwplayer/glow/controlbar/unmuteButtonOver.png
 create mode 100644 assets/jwplayer/glow/display/background.png
 create mode 100644 assets/jwplayer/glow/display/bufferIcon.png
 create mode 100644 assets/jwplayer/glow/display/muteIcon.png
 create mode 100644 assets/jwplayer/glow/display/playIcon.png
 create mode 100644 assets/jwplayer/glow/dock/button.png
 create mode 100644 assets/jwplayer/glow/glow.xml
 create mode 100644 assets/jwplayer/glow/playlist/item.png
 create mode 100644 assets/jwplayer/glow/playlist/itemOver.png
 create mode 100644 assets/jwplayer/glow/playlist/sliderCapBottom.png
 create mode 100644 assets/jwplayer/glow/playlist/sliderCapTop.png
 create mode 100644 assets/jwplayer/glow/playlist/sliderRail.png
 create mode 100644 assets/jwplayer/glow/playlist/sliderThumb.png
 create mode 100644 assets/jwplayer/glow/sharing/embedIcon.png
 create mode 100644 assets/jwplayer/glow/sharing/embedScreen.png
 create mode 100644 assets/jwplayer/glow/sharing/shareIcon.png
 create mode 100644 assets/jwplayer/glow/sharing/shareScreen.png
 create mode 100644 assets/jwplayer/player.swf
 create mode 100644 atom.xml
 create mode 100644 blog/archives/index.html
 create mode 100644 favicon.png
 create mode 100644 images/bird_32_gray.png
 create mode 100644 images/bird_32_gray_fail.png
 create mode 100644 images/code_bg.png
 create mode 100644 images/dotted-border.png
 create mode 100644 images/email.png
 create mode 100644 images/line-tile.png
 create mode 100644 images/noise.png
 create mode 100644 images/rss.png
 create mode 100644 images/search.png
 rewrite index.html (100%)
 create mode 100644 javascripts/ender.js
 create mode 100644 javascripts/github.js
 create mode 100644 javascripts/libs/ender.js
 create mode 100644 javascripts/libs/jXHR.js
 create mode 100644 javascripts/libs/swfobject-dynamic.js
 create mode 100644 javascripts/modernizr-2.0.js
 create mode 100644 javascripts/octopress.js
 create mode 100644 javascripts/pinboard.js
 create mode 100644 javascripts/twitter.js
 create mode 100644 sitemap.xml
 create mode 100644 stylesheets/screen.css
## Pushing generated _deploy website
Counting objects: 79, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (72/72), done.
Writing objects: 100% (79/79), 179.28 KiB, done.
Total 79 (delta 1), reused 0 (delta 0)
To git@github.com:terrywang/terrywang.github.com
 * [new branch]      master -> master
## Github Pages deploy complete
cd -
$ git status
# On branch source
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   Rakefile
#	modified:   _config.yml
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#	sass/
#	source/
no changes added to commit (use "git add" and/or "git commit -a")

NOTE: use git log or tig (text-mode) or gitk to check commit logs.

This generates your blog, copy the generated files into _deploy/, add them to git, commit and push them up to the master branch. In a few seconds you should get an email from Github telling you that your commit has been received and will be published on your site.

Push source (octopress) to source branch => GitHub

DO NOT FORGET to add source (octopress itself) to index/staging area and commit, push to source branch on GitHub.

$ git add .
$ git commit -m 'init'
[source a2acf42] init
 120 files changed, 4361 insertions(+), 3 deletions(-)
 create mode 100644 sass/_base.scss
 create mode 100644 sass/_partials.scss
 create mode 100644 sass/base/_layout.scss
 create mode 100644 sass/base/_solarized.scss
 create mode 100644 sass/base/_theme.scss
 create mode 100644 sass/base/_typography.scss
 create mode 100644 sass/base/_utilities.scss
 create mode 100644 sass/custom/_colors.scss
 create mode 100644 sass/custom/_fonts.scss
 create mode 100644 sass/custom/_layout.scss
 create mode 100644 sass/custom/_styles.scss
 create mode 100644 sass/partials/_archive.scss
 create mode 100644 sass/partials/_blog.scss
 create mode 100644 sass/partials/_footer.scss
 create mode 100644 sass/partials/_header.scss
 create mode 100644 sass/partials/_navigation.scss
 create mode 100644 sass/partials/_sharing.scss
 create mode 100644 sass/partials/_sidebar.scss
 create mode 100644 sass/partials/_syntax.scss
 create mode 100644 sass/partials/sidebar/_base.scss
 create mode 100644 sass/partials/sidebar/_delicious.scss
 create mode 100644 sass/partials/sidebar/_googleplus.scss
 create mode 100644 sass/partials/sidebar/_pinboard.scss
 create mode 100644 sass/partials/sidebar/_twitter.scss
 create mode 100644 sass/screen.scss
 create mode 100644 source/_includes/after_footer.html
 create mode 100644 source/_includes/archive_post.html
 create mode 100644 source/_includes/article.html
 create mode 100644 source/_includes/asides/delicious.html
 create mode 100644 source/_includes/asides/github.html
 create mode 100644 source/_includes/asides/googleplus.html
 create mode 100644 source/_includes/asides/pinboard.html
 create mode 100644 source/_includes/asides/recent_posts.html
 create mode 100644 source/_includes/asides/twitter.html
 create mode 100644 source/_includes/custom/after_footer.html
 create mode 100644 source/_includes/custom/asides/about.html
 create mode 100644 source/_includes/custom/category_feed.xml
 create mode 100644 source/_includes/custom/footer.html
 create mode 100644 source/_includes/custom/head.html
 create mode 100644 source/_includes/custom/header.html
 create mode 100644 source/_includes/custom/navigation.html
 create mode 100644 source/_includes/disqus.html
 create mode 100644 source/_includes/facebook_like.html
 create mode 100644 source/_includes/footer.html
 create mode 100644 source/_includes/google_analytics.html
 create mode 100644 source/_includes/google_plus_one.html
 create mode 100644 source/_includes/head.html
 create mode 100644 source/_includes/header.html
 create mode 100644 source/_includes/navigation.html
 create mode 100644 source/_includes/post/author.html
 create mode 100644 source/_includes/post/categories.html
 create mode 100644 source/_includes/post/date.html
 create mode 100644 source/_includes/post/disqus_thread.html
 create mode 100644 source/_includes/post/sharing.html
 create mode 100644 source/_includes/twitter_sharing.html
 create mode 100644 source/_layouts/category_index.html
 create mode 100644 source/_layouts/default.html
 create mode 100644 source/_layouts/page.html
 create mode 100644 source/_layouts/post.html
 create mode 100644 source/assets/jwplayer/glow/controlbar/background.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/blankButton.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/divider.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/fullscreenButton.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/fullscreenButtonOver.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/muteButton.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/muteButtonOver.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/normalscreenButton.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/normalscreenButtonOver.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/pauseButton.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/pauseButtonOver.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/playButton.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/playButtonOver.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/timeSliderBuffer.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/timeSliderCapLeft.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/timeSliderCapRight.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/timeSliderProgress.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/timeSliderRail.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/unmuteButton.png
 create mode 100644 source/assets/jwplayer/glow/controlbar/unmuteButtonOver.png
 create mode 100644 source/assets/jwplayer/glow/display/background.png
 create mode 100644 source/assets/jwplayer/glow/display/bufferIcon.png
 create mode 100644 source/assets/jwplayer/glow/display/muteIcon.png
 create mode 100644 source/assets/jwplayer/glow/display/playIcon.png
 create mode 100644 source/assets/jwplayer/glow/dock/button.png
 create mode 100644 source/assets/jwplayer/glow/glow.xml
 create mode 100644 source/assets/jwplayer/glow/playlist/item.png
 create mode 100644 source/assets/jwplayer/glow/playlist/itemOver.png
 create mode 100644 source/assets/jwplayer/glow/playlist/sliderCapBottom.png
 create mode 100644 source/assets/jwplayer/glow/playlist/sliderCapTop.png
 create mode 100644 source/assets/jwplayer/glow/playlist/sliderRail.png
 create mode 100644 source/assets/jwplayer/glow/playlist/sliderThumb.png
 create mode 100644 source/assets/jwplayer/glow/sharing/embedIcon.png
 create mode 100644 source/assets/jwplayer/glow/sharing/embedScreen.png
 create mode 100644 source/assets/jwplayer/glow/sharing/shareIcon.png
 create mode 100644 source/assets/jwplayer/glow/sharing/shareScreen.png
 create mode 100644 source/assets/jwplayer/player.swf
 create mode 100644 source/atom.xml
 create mode 100644 source/blog/archives/index.html
 create mode 100644 source/favicon.png
 create mode 100644 source/images/bird_32_gray.png
 create mode 100644 source/images/bird_32_gray_fail.png
 create mode 100644 source/images/code_bg.png
 create mode 100644 source/images/dotted-border.png
 create mode 100644 source/images/email.png
 create mode 100644 source/images/line-tile.png
 create mode 100644 source/images/noise.png
 create mode 100644 source/images/rss.png
 create mode 100644 source/images/search.png
 create mode 100644 source/index.html
 create mode 100644 source/javascripts/ender.js
 create mode 100644 source/javascripts/github.js
 create mode 100644 source/javascripts/libs/ender.js
 create mode 100644 source/javascripts/libs/jXHR.js
 create mode 100644 source/javascripts/libs/swfobject-dynamic.js
 create mode 100644 source/javascripts/modernizr-2.0.js
 create mode 100644 source/javascripts/octopress.js
 create mode 100644 source/javascripts/pinboard.js
 create mode 100644 source/javascripts/twitter.js
$ git push origin source
Counting objects: 4073, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (1459/1459), done.
Writing objects: 100% (4073/4073), 936.30 KiB, done.
Total 4073 (delta 2327), reused 3995 (delta 2285)
To git@github.com:terrywang/terrywang.github.com
 * [new branch]      source -> source

NOTE: With new repositories, GitHub sets the default branch based on the branch you push first, and it looks there for the generated site content. If you’re having trouble getting GitHub to publish your site, go to the admin panel for your repository and make sure that the master branch is the default branch.

Configuring Ocotopress

Main configuration files Rakefile and the _config.yml

List of files for configuring Octopress

_config.yml # Main config (Jekyll's settings)
Rakefile # Configs for deployment
config.rb # Compass config
config.ru # Rack config

Configurations in the Rakefile are mostly related to deployment and you probably won’t have to touch them unless you’re using rsync.

Blog Configuration

In the _config.yml there are three sections for configuring your Octopress Blog. Spoiler: You must change url, and you’ll probably change title, subtitle and author and enable some 3rd party services.

Main Configs

url:                # For rewriting urls for RSS, etc
title:              # Used in the header and title tags
subtitle:           # A description used in the header
author:             # Your name, for RSS, Copyright, Metadata
simple_search:      # Search engine for simple site search
description:        # A default meta description for your site
date_format:        # Format dates using Ruby's date strftime syntax
subscribe_rss:      # Url for your blog's feed, defauts to /atom.xml
subscribe_email:    # Url to subscribe by email (service required)
category_feeds:     # Enable per category RSS feeds (defaults to false in 2.1)
email:              # Email address for the RSS feed if you want it.

Note: If your site is a multi-author blog, you may want to set this config’s author to the name of your company or project, and add author metadata to posts and pages to give proper attribution for those works.

Jekyll & Plugins

These configurations are used by Jekyll and Plugins. If you’re not familiar with Jekyll, you should probably have a look at the configuration docs which lists more options that aren’t covered here.

root:               # Mapping for relative urls (default: /)
permalink:          # Permalink structure for blog posts
source:             # Directory for site source files
destination:        # Directory for generated site files
plugins:            # Directory for Jekyll plugins
code_dir:           # Directory for code snippets (for include_code plugin)
category_dir:       # Directory for generated blog category pages

pygments:           # Toggle python pygments syntax highlighting
paginate:           # Posts per page on the blog index
pagination_dir:     # Directory base for pagination URLs eg. /blog/page/2/
recent_posts:       # Number of recent posts to appear in the sidebar

default_asides:     # Configure what shows up in the sidebar and in what order
blog_index_asides:  # Optional sidebar config for blog index page
post_asides:        # Optional sidebar config for post layout
page_asides:        # Optional sidebar config for page layout

If you want to change the way permalinks are written for your blog posts, see Jekyll’s permalink docs.

Note: Jekyll has a baseurl config which offers mock subdirectory publishing support by adding a redirect to Jekyll’s WEBrick server. Please don’t use this. If you want to publish your site to a subdirectory, (see Deploying Octopress to a Subdirectory).

3rd Party Settings

These third party integrations are already set up for you. Simply fill in the configurations and they’ll be added to your site.

Github - List your github repositories in the sidebar
Twitter - Setup a sidebar twitter feed, follow button, and tweet button (for sharing posts and pages).
Google Plus One - Setup sharing for posts and pages on Google’s plus one network.
Pinboard - Share your recent Pinboard bookmarks in the sidebar.
Delicious - Share your recent Delicious bookmarks in the sidebar.
Disqus Comments - Add your disqus short name to enable disqus comments on your site.
Google Analytics - Add your tracking id to enable Google Analytics tracking for your site.
Facebook - Add a Facebook like button
The Octopress layouts read these configurations and only include the javascript and html necessary for the enabled services.

Push the config changes to GitHub

Here we have 2 branches to take care of:

master => _deploy/
source => octopress

NOTE: they both are git repositories.

Edit _config.yml

git add _config.yml
git commit -m 'config octopress'
git push origin source

Preview locally using `rake preview`

If changes are correctly refreshed. Re-generate master and push to GitHub.

rake generate
rake deploy

Adding a new About page

1. Create a new About page

$ rake new_page['about.markdown']
mkdir -p source
Creating new page: source/about.markdown
$ git status
# On branch source
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#	source/about.markdown
nothing added to commit but untracked files present (use "git add" to track)

2. Preview

rake preview (about.markdown will be converted to about.html)

3. Edit about.markdown (markdown) as required

4. Add the About to navigation

5. Edit source/_include/custom/navigation.html to add it to navigation

6. Preview locally to make sure it works

7. rake generate && rake deploy

8. Push changes to source branch (backup octopress itself)

git add .
git commit -m 'about page'
git push origin source

Disqus Comments

In Disqus Admin, add a new site, pay attention to the shortname, this is the one needed in _config.yml.

We can log in at shortname.disqus.com in fact.

Edit _config.yml

# Disqus Comments
disqus_short_name: terrywang
disqus_show_comment_count: false

How it works

Take a look at the files

source/_layouts/post.html and pages.html

{% if site.disqus_short_name and page.comments == true %}
  <section>
    <h1>Comments</h1>
    <div id="disqus_thread" aria-live="polite">{% include post/disqus_thread.html %}</div>
  </section>
{% endif %}

source/about.markdown

---
layout: page
title: "about"
date: 2012-12-16 22:26
comments: true
sharing: true
footer: true
---

So 2 requirements for disqus to work: 1. disqus shortname is set in _config.yml 2. comments value set to true in page / post source.

Commit the change

git commit -a -m "Disqus"

Preview at localhost:4000

rake preview

Updating Octopress

Updating Octopress is actually updating the source branch, NOT master (master => contents of _deploy).

The current working directory was cloned from octopress GitHub repository

Check working directory .git/config to make sure remote repository octopress exists and point to the correct repository URL, of course you can use git remote -v to do the same.

$ cat .git/config 
[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "octopress"]
	url = git://github.com/imathis/octopress.git
	fetch = +refs/heads/*:refs/remotes/octopress/*
[branch "source"]
	remote = origin
	merge = refs/heads/master
[remote "origin"]
	url = git@github.com:terrywang/terrywang.github.com
	fetch = +refs/heads/*:refs/remotes/origin/*

In this case, the update is simple and straightforward, just get the latest Octopress by running

git pull octopress master

NOTE: the above will most likely fail due to conflicts.

Recommended: do a git pull --rebase so that the commits will be placed on top of the latest upstream head of octopress.

NOTE: git rebase => Forward-port local commits to the updated upstream head.

NOTE: git pull -r - Rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to the upstream branch and the upstream branch was rebased since last fetched, the rebase uses that information to avoid rebasing non-local changes.

git pull -r octopress master

Most likely there will be conflicts, Rakefile in particular.

For example

$ git pull -r octopress master
remote: Counting objects: 160, done.
remote: Compressing objects: 100% (57/57), done.
remote: Total 113 (delta 69), reused 93 (delta 49)
Receiving objects: 100% (113/113), 58.76 KiB, done.
Resolving deltas: 100% (69/69), completed with 27 local objects.
From git://github.com/imathis/octopress
 * branch            master     -> FETCH_HEAD
First, rewinding head to replay your work on top of it...
Applying: init
Using index info to reconstruct a base tree...
<stdin>:3018: trailing whitespace.
		
<stdin>:3032: trailing whitespace.
		
<stdin>:494: new blank line at EOF.
+
<stdin>:545: new blank line at EOF.
+
<stdin>:839: new blank line at EOF.
+
warning: squelched 6 whitespace errors
warning: 11 lines add whitespace errors.
Falling back to patching base and 3-way merge...
Auto-merging Rakefile
CONFLICT (content): Merge conflict in Rakefile
Failed to merge in the changes.
Patch failed at 0001 init
When you have resolved this problem run "git rebase --continue".
If you would prefer to skip this patch, instead run "git rebase --skip".
To check out the original branch and stop rebasing run "git rebase --abort".

Manually resolve conflicts

Remove the Rake file

$ git rm Rakefile
Rakefile: needs merge
rm 'Rakefile'

Check current working tree status

$ git status
# Not currently on any branch.
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#	deleted:    Rakefile
#	modified:   _config.yml
#	new file:   sass/_base.scss
#	new file:   sass/_partials.scss
#	new file:   sass/base/_layout.scss
#	new file:   sass/base/_solarized.scss
#	new file:   sass/base/_theme.scss
#	new file:   sass/base/_typography.scss
#	new file:   sass/base/_utilities.scss
#	new file:   sass/custom/_colors.scss
#	new file:   sass/custom/_fonts.scss
#	new file:   sass/custom/_layout.scss
#	new file:   sass/custom/_styles.scss
#	new file:   sass/partials/_archive.scss
#	new file:   sass/partials/_blog.scss
#	new file:   sass/partials/_footer.scss
#	new file:   sass/partials/_header.scss
#	new file:   sass/partials/_navigation.scss
#	new file:   sass/partials/_sharing.scss
#	new file:   sass/partials/_sidebar.scss
#	new file:   sass/partials/_syntax.scss
#	new file:   sass/partials/sidebar/_base.scss
#	new file:   sass/partials/sidebar/_delicious.scss
#	new file:   sass/partials/sidebar/_googleplus.scss
#	new file:   sass/partials/sidebar/_pinboard.scss
#	new file:   sass/partials/sidebar/_twitter.scss
#	new file:   sass/screen.scss
#	new file:   source/_includes/after_footer.html
#	new file:   source/_includes/archive_post.html
#	new file:   source/_includes/article.html
#	new file:   source/_includes/asides/delicious.html
#	new file:   source/_includes/asides/github.html
#	new file:   source/_includes/asides/googleplus.html
#	new file:   source/_includes/asides/pinboard.html
#	new file:   source/_includes/asides/recent_posts.html
#	new file:   source/_includes/asides/twitter.html
#	new file:   source/_includes/custom/after_footer.html
#	new file:   source/_includes/custom/asides/about.html
#	new file:   source/_includes/custom/category_feed.xml
#	new file:   source/_includes/custom/footer.html
#	new file:   source/_includes/custom/head.html
#	new file:   source/_includes/custom/header.html
#	new file:   source/_includes/custom/navigation.html
#	new file:   source/_includes/disqus.html
#	new file:   source/_includes/facebook_like.html
#	new file:   source/_includes/footer.html
#	new file:   source/_includes/google_analytics.html
#	new file:   source/_includes/google_plus_one.html
#	new file:   source/_includes/head.html
#	new file:   source/_includes/header.html
#	new file:   source/_includes/navigation.html
#	new file:   source/_includes/post/author.html
#	new file:   source/_includes/post/categories.html
#	new file:   source/_includes/post/date.html
#	new file:   source/_includes/post/disqus_thread.html
#	new file:   source/_includes/post/sharing.html
#	new file:   source/_includes/twitter_sharing.html
#	new file:   source/_layouts/category_index.html
#	new file:   source/_layouts/default.html
#	new file:   source/_layouts/page.html
#	new file:   source/_layouts/post.html
#	new file:   source/assets/jwplayer/glow/controlbar/background.png
#	new file:   source/assets/jwplayer/glow/controlbar/blankButton.png
#	new file:   source/assets/jwplayer/glow/controlbar/divider.png
#	new file:   source/assets/jwplayer/glow/controlbar/fullscreenButton.png
#	new file:   source/assets/jwplayer/glow/controlbar/fullscreenButtonOver.png
#	new file:   source/assets/jwplayer/glow/controlbar/muteButton.png
#	new file:   source/assets/jwplayer/glow/controlbar/muteButtonOver.png
#	new file:   source/assets/jwplayer/glow/controlbar/normalscreenButton.png
#	new file:   source/assets/jwplayer/glow/controlbar/normalscreenButtonOver.png
#	new file:   source/assets/jwplayer/glow/controlbar/pauseButton.png
#	new file:   source/assets/jwplayer/glow/controlbar/pauseButtonOver.png
#	new file:   source/assets/jwplayer/glow/controlbar/playButton.png
#	new file:   source/assets/jwplayer/glow/controlbar/playButtonOver.png
#	new file:   source/assets/jwplayer/glow/controlbar/timeSliderBuffer.png
#	new file:   source/assets/jwplayer/glow/controlbar/timeSliderCapLeft.png
#	new file:   source/assets/jwplayer/glow/controlbar/timeSliderCapRight.png
#	new file:   source/assets/jwplayer/glow/controlbar/timeSliderProgress.png
#	new file:   source/assets/jwplayer/glow/controlbar/timeSliderRail.png
#	new file:   source/assets/jwplayer/glow/controlbar/unmuteButton.png
#	new file:   source/assets/jwplayer/glow/controlbar/unmuteButtonOver.png
#	new file:   source/assets/jwplayer/glow/display/background.png
#	new file:   source/assets/jwplayer/glow/display/bufferIcon.png
#	new file:   source/assets/jwplayer/glow/display/muteIcon.png
#	new file:   source/assets/jwplayer/glow/display/playIcon.png
#	new file:   source/assets/jwplayer/glow/dock/button.png
#	new file:   source/assets/jwplayer/glow/glow.xml
#	new file:   source/assets/jwplayer/glow/playlist/item.png
#	new file:   source/assets/jwplayer/glow/playlist/itemOver.png
#	new file:   source/assets/jwplayer/glow/playlist/sliderCapBottom.png
#	new file:   source/assets/jwplayer/glow/playlist/sliderCapTop.png
#	new file:   source/assets/jwplayer/glow/playlist/sliderRail.png
#	new file:   source/assets/jwplayer/glow/playlist/sliderThumb.png
#	new file:   source/assets/jwplayer/glow/sharing/embedIcon.png
#	new file:   source/assets/jwplayer/glow/sharing/embedScreen.png
#	new file:   source/assets/jwplayer/glow/sharing/shareIcon.png
#	new file:   source/assets/jwplayer/glow/sharing/shareScreen.png
#	new file:   source/assets/jwplayer/player.swf
#	new file:   source/atom.xml
#	new file:   source/blog/archives/index.html
#	new file:   source/favicon.png
#	new file:   source/images/bird_32_gray.png
#	new file:   source/images/bird_32_gray_fail.png
#	new file:   source/images/code_bg.png
#	new file:   source/images/dotted-border.png
#	new file:   source/images/email.png
#	new file:   source/images/line-tile.png
#	new file:   source/images/noise.png
#	new file:   source/images/rss.png
#	new file:   source/images/search.png
#	new file:   source/index.html
#	new file:   source/javascripts/ender.js
#	new file:   source/javascripts/github.js
#	new file:   source/javascripts/libs/ender.js
#	new file:   source/javascripts/libs/jXHR.js
#	new file:   source/javascripts/libs/swfobject-dynamic.js
#	new file:   source/javascripts/modernizr-2.0.js
#	new file:   source/javascripts/octopress.js
#	new file:   source/javascripts/pinboard.js
#	new file:   source/javascripts/twitter.js
#

Download the Rakefile from the latest commit (master)

Download latest Rakefile from github

wget -c -S https://raw.github.com/imathis/octopress/master/Rakefile

Or

curl -L https://raw.github.com/imathis/octopress/master/Rakefile -o Rakefile

Add the new Rakefile back to stage (index)

git add Rakefile

Complete the git rebase operation

$ git rebase --continue
Applying: init
Applying: config octopress
Applying: Google Analytics
Applying: about page
Applying: Disqus

Then keep gems updated

bundle install

update the template's source and style

rake update_source
rake update_style

Done!

Push updated octopress source to GitHub

NOTE: git rebase changed the commit history (put local changes on top of master), -f is need to when pushing

git push -f origin source

Sample output

$ git push -f origin source
Counting objects: 4208, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (1527/1527), done.
Writing objects: 100% (4208/4208), 997.41 KiB, done.
Total 4208 (delta 2409), reused 4098 (delta 2345)
To git@github.com:terrywang/terrywang.github.com
 + 70f38f4...24b080b source -> source (forced update)

If working directory is cloned from terrywang.github.com repository

Switch to source branch, initially the .git/config looks like below

$ cat .git/config 
[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	url = https://github.com/terrywang/terrywang.github.com.git
[branch "master"]
	remote = origin
	merge = refs/heads/master
[branch "source"]
	remote = origin
	merge = refs/heads/source

Or use git remote -v

$ git remote -v
origin	https://github.com/terrywang/terrywang.github.com.git (fetch)
origin	https://github.com/terrywang/terrywang.github.com.git (push)

Add the remote octopress repository using git add

git remote add octopress https://github.com/imathis/octopress.git

Check what's been added in .git/config

$ cat .git/config 
[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	url = https://github.com/terrywang/terrywang.github.com.git
[branch "master"]
	remote = origin
	merge = refs/heads/master
[branch "source"]
	remote = origin
	merge = refs/heads/source
[remote "octopress"]
	url = https://github.com/imathis/octopress.git
	fetch = +refs/heads/*:refs/remotes/octopress/*

Or git remote -v

$ git remote -v
octopress	https://github.com/imathis/octopress.git (fetch)
octopress	https://github.com/imathis/octopress.git (push)
origin	https://github.com/terrywang/terrywang.github.com.git (fetch)
origin	https://github.com/terrywang/terrywang.github.com.git (push)

Update using git pull

git pull - fetch from a remote repo and try to merge into the current branch

Update

git pull octopress master

Merge

To merge another branch into your active branch (e.g. master), use

git merge branch

in both cases git tries to auto-merge changes. Unfortunately, this is not always possible and results in conflicts. You are responsible to merge those conflicts manually by editing the files shown by git.

After changing, you need to mark them as merged with

git add file

before merging changes, you can also preview them by using

git diff source_branch target_branch

Don't forget to push the new octopress version to remote source branch.

Reference

Octopress Documentation

Terry : Octopress

Octopress

What is Octopress?

Setup Octopress

Install dependencies

Install bundler

Install all dependencies using bundle

Install the default Octopress theme

Preview locally (default on port 4000)

Deploying to GitHub Pages

Deploying Static Resources to GitHub

Push source (octopress) to source branch => GitHub

Configuring Ocotopress

Main Configs

Jekyll & Plugins

3rd Party Settings

Push the config changes to GitHub

Adding a new About page

Disqus Comments

Updating Octopress

The current working directory was cloned from octopress GitHub repository

Manually resolve conflicts

Download the Rakefile from the latest commit (master)

If working directory is cloned from terrywang.github.com repository

Update using git pull

Reference