In this post I’ll be sharing some of the things that I’ve discovered while working with Octopress.
As you all know Octopress is a blogging framework much like Wordpress but only static and its powered by Jekyll which is a static site generator. Static means that it generates html and other assets whenever you generate the site. Every configuration are stored in files. Therefore there’s no database involved. There’s no login and other dynamic things that you might find in Wordpress and other CMS.
You own your content. Posts in octopress lives in your hard drive and then you just deploy them later on.
Fully customizable and extensible. You get to write your own plugins and themes. And you can customize almost anything on your site.
You can deploy anywhere. All you need are the files that were generated. No need for PHP, MySQL.
More difficult setup. You have to install a bunch of stuff from the command line before you get it to work. But the docs are great so there’s no need to worry.
It takes time to generate the whole site when you’re publishing something, probably a minute or two but that’s just my computer. It might be faster on more powerful computers.
The process for installing a theme is simply downloading the theme then extract it into the
.themes directory and then execute the following command:
1 2 3 4
There’s also a bunch of plugins that you can use for Octopress. You can install the plugins on the
plugins directory inside
octopress. I personally use the following plugins:
- video_tag (vimeo, youtube)
- backtick code block
Customizing Octopress is easy. All you have to do is to edit the files on the following directories:
- source – html templates, scripts, images and other site assets (E.g. fonts)
- sass – stylesheets
- plugins – plugin files which are mostly ruby files
- .themes – theme files
Here’s a screenshot of the source directory where most of the files that Octopress uses to generate a site are stored.
In Octopress there are site layouts which are basically just html files with templating logic. Here’s the default layout used in Octopress. Most of the time the default layout is the layout used in the index page of an Octopress blog.
There’s also the
post layout which just inherits from the default layout.
And then loads the actual post inside the
So where does Octopress know where to find the
article.html that we are
including inside the
article section? It finds them inside the
All the files that are included by doing
include file.html are stored in the
Opening up the
article.html file we see something like this:
Upon reading the code you will see that this actually does either of two things.
First it checks if the current page is the
If its the
index page then it doesn’t load all the content of the blog post
but only if you have specified it in your post.
Going back to the Octopress documentation under the blogging basics section.
You will see that in order to specify where your content will be cut in the index page
you have to put the
<!-- more --> comment right after the specific spot where you want
the content to be cut. Someone might have written a plugin that automatically only loads a bit of the actual content in the index page but having a control on where the content will be cut is really good.
On the other hand if the current page is something other than the
index page then it simply loads the whole content.
Here are some of the behaviors that I noticed while I was using Octopress:
If the source file (markdown) that you are trying to convert to html is not valid it will either return an error when you execute
rake generateor it will simply fallback to the previously generated site without returning an error.
Errors in plugins will return an error when executing
Posts that are not published (published: false) will show up on
rake previewbut does not show up on
Here are some of the commands that I frequently used when working with Octopress:
rake generate – used for generating the site
rake preview – used for previewing the whole site on your browser. The common port is
4000. So to access your Octopress site offline you would have to type in
localhost:4000that is if you haven’t setup a virtual host on your machine.
rake gen_deploy – used for generating the whole site and then deploy it to your preferred hosting site (E.g Github pages, Heroku).