I am hooked. Octopress is a lot nicer than Wordpress for a guy like me who likes to tinker with files, directories, the Terminal, and administration of websites. Instead of HTML, Octopress relies on Markdown. A way to “mark up” your text, without using HTML syntax. It is a more natural way to write a blog post.
Another big benefit to Octopress is that it creates a website with static pages and doesn’t depend on an database. That is so attractive to me. Let me explain why.
When I originally took this site down 4.5 years ago, I wasn’t smart and left all my posts in a MySQL DB just sitting on my server. Wordpress had numerous versions since then, including numerous DB updates. I would have had to:
- Re-enable my blog.
- Upgrade it to the latest Wordpress
- Export to get all of the posts out of the site.
Of course, I couldn’t even get past step 1. I tried every trick I knew and I still couldn’t get Wordpress re-initialized using my old files and DB. I ended up going for a different approach. My MySQL experience got me to the point of logging into the PHP UI, and I could export all of my posts to XML. In 2 nights, I was able to write a simple command-line application that took the XML and converted it to Octopress’ .markdown format. Amazingly, my third successful export of the MySQL XML to .markdown got me all the way there. (Yes, I can do this programming thing sometime, even for my personal usage.)
I was left with 1200 .markdown files. Luckily I was able to twiddle that down to about 250 posts by getting rid of the intermediate “revision” posts that Wordpress saves to the database every time you hit Update on the Web UI.
Next step was to filter out the .markdown files. I had some posts that were banal. Some posts that were more suited for my family blog. And some posts that just didn’t really belong in a public blog. It is not that they were bad. They just were polarized viewpoints. February 2009-October 2009 (the months I kept up with the blog) were not the best times to talk about politics in this country. (Is there ever a good time?) I am at the point in my life where putting stuff like that out there doesn’t do any good. You end up looking like an ass to a good percentage of people, because people almost never share your viewpoint, and it is not like a blog is a good place to convert people to your way of thinking. It is better to leave that stuff to private conversation.
I jumped the gun a little bit. I got so excited talking about exporting that I forgot how to get started with Octopress. For a Terminal hacker like me, the easiest way to get Octopress is via git. You just do this from the command-line:
$ git clone git://github.com/imathis/octopress.git octopress
$ cd octopress
I saw online, that a good thing you may want to do is to name your local repository after the website you are creating, like so:
$ git clone git://github.com/imathis/octopress.git mywebsite.com
$ cd mywebsite.com
To make use of Octopress, you just need to have a recent Ruby installed. I had a 2.0 version, but decided to use rbenv and installed the latest Ruby.
After you install Ruby, you call the following commands:
$ gem install bundle
$ rbenv rehash
$ bundle install
The tree layout for the Octopress repository is quite simple:
CHANGELOG.markdown
Gemfile
Gemfile.lock
README.markdown
Rakefile
_config.yml
config.rb
config.ru
plugins/
public/
sass/
source/
The 2 .markdown files are (GitHub) documentation. The Gemfile is what keeps Ruby dependencies in order. The Rakefile is sort of like a Unix Makefile, just with a Ruby syntax. Later on in this post when you call ‘rake’, you are actually executing commands in the Rakefile. The two big folders that you will interact with are these two:
source/
public/
The source folder is where you put posts, pages, and assets (images). The public folder is what is generated by Octopress (Jekyll) and is what gets uploaded to your website.
OK. Now that we covered getting Octopress installed, back to doing Markdown and blog posts. After making modifications to the .markdown files, I simply put them all in the source/_posts folder. To simplify the process of making a new page or post .markdown file you do one of these two from the top level of the octopress folder:
$ rake new_post[“Post Title”]
$ rake new_page[“Page Title”]
A post is a blog post. This is what you will do most of the time to create content. A page is a static page, like an “About” page. It gets put in a special folder so that you can connect it up to the navigation.
After figuring out the markdown files, the next thing you have to modify is the _config.yaml file that is at the root of the git repository. You configure things like:
- Blog name
- Blog tagline
- URL for blog
- SSH destination
There is a whole slew of things you can modify here. Luckily it is rather straight forward.
Now that all of the files are configuration are in order. It is just a matter of launching this from the command-line:
$ rake generate
For a blog like mine that has over 100 posts, it takes about 5 seconds to generate my entire site.
Anytime you create a new post, or change your blog, this is the command you launch. It takes your markdown files and other assets from the source folder, and compiles it into a site in the public folder. With this all being wrapped up in .git. It makes it super simple to take the source folder and create its own repository (or submodule). Another attractive feature for a backup obsessed person like me.
After rake generate does its thing with Ruby and Jekyll, you can preview your site locally by issuing the following command:
$ rake preview
This opens up a web server on port 4000. You check out your site by launching your browser to here http://localhost:4000. It is that easy. (Well it should be that easy. I had to add thin to the Gemfile, so that the pages displayed in Safari 7).
(BTW, I just discovered that if you keep rake preview running while you are making edits, it will continually scan your source folder looking for changes and regenerate. No need to kill rake preview while editing a post. Just refresh the page after saving the .markdown file.)
Once you are happy with how the blog looks, you just launch this:
$ rake deploy
If your SSH and authorized_keys are configured correctly for copying files to a web server, your static files should be deployed correctly to your website. The process uses rsync, so essentially only changes are uploaded to the server. This makes deployment quite fast.
I still need to come up with a good list of Terminal aliases to make doing rake generate, rake preview, and rake deploy easier. I also should look to see if there is a suitable front end for doing all of this. If I even decided to move my other Wordpress blog to Octopress, my wife wouldn’t like the Terminal.
I also recommend the use of this QuickLook plugin on Mac. It is a great way to view .markdown files in a QuickLook window.
Next step for me is to get proficient in Markdown. I know how to do links, bold, italic and bullet points, but I don’t know how to reference assets like pictures and movies. I also need to check out how plugins work. Assumably they go in the plugins folder above.
Thanks to the Octopress site, mainly this page, for all the valuable information.