How to Do X in Octopress
So I spent the last couple days tweaking my Octopress themes and relearning how to do things since not blogging for a while and getting a new MBP. Navigating the Octopress file hierarchy isn’t easy, but hopefully this post will help you (and be a useful reference for myself).
So, let’s start with a preview of what we have to work with. If you’re reading this, I assume you know a bit about Git, the Unix shell, and what Octopress is.
Let’s start with the file hierarchy, my current setup, and the Git configuration.
My current setup:
For starters, I’m using [oh-my] zsh with the popular Solarized colour scheme. A typical Octopress folder looks something like this:
A typical Octopress configuration uses two branches (master and source). I use GitHub Pages for deployment and it looks for files in the master branch. But while editing posts and stylesheets, we really only have to worry about the source branch.
_config.yml holds various top-level/administrative info for your blog. This is where you’d put your blog’s name, your Disqus shortname (if applicable), what links you want in your navigation bar, usernames for various services (GitHub, Facebook, G+, etc.), Google analytics tracking ID, and so on.
A quick primer for non-ruby enthusiasts:
rake is basically the Ruby version of
GNU make. Some of the useful rake tasks descriptions are below. Upon executing any of the below rake tasks, a number of useful commands will be run resulting in some otherwise complex thing being completed.
clean — clean out caches: .pygments-cache, .gist-cache, .sass-cache
deploy — default deploy task
gen_deploy — generate website and deploy
generate — generate jekyll site
install[theme] — initial setup for octopress: copies the default theme into the path of jekyll’s generator.
list — list tasks
new_post[title] — begin a new post in source/_posts
preview — preview the site in a web browser
watch — watch the site and regenerate when it changes
Writing a new post
creates a Markdown file in
source/_posts named “2013-12-28-new-post-title-with-punctuation.markdown”, for example.
Deleting the file effectively deletes the post (assuming you haven’t already published the post to the interwebs)
If you’d like to preview your post in the browser,
will do the trick and show you your blog at localhost:4000 (more info on localhost). HTTP requests and responses will be logged in the same terminal window, so I recommend opening a seperate tab/window specifically for running this process.
Upon saving the file and refreshing the browser window, you’ll see how your post (along with the rest of the blog) will look.
Lastly, saving your post’s progress (anything done in the source branch really), can be done through
A number of themes are available here. I’ve opted for the “villainy” theme with several personal customizations. I’ll detail how I did those changes below.
Make your blog feel like home
Disclaimer: If you’re anything like me, you may spend several hours tweaking the various SCSS, HTML, and JS files at your disposal. It’s pretty addicting.
A little trick I use when I want to find where a specific css selector’s attributes are defined is to use
fgrep. For example, running
finds me the exact SASS file(s) I need (and any duplicate declarations that need to be eliminated).
A more detailed description can be found here.
That’s all for now folks; if there’s anything you’d like me to add, shoot me an email!