Masochists are everywhere. Managing a system by hand appeals to a certain subset of the population, but I joined Puppet Labs because I was a fan of automating the shit out of menial tasks. I have no burning desire to handcraft an artisanal blog made out of organic bits. I tried web development at one point in my life and learned an important lesson:
I am not a web developer
What I DO want is to have a platform to share information and code I’ve accumulated along the way that:
- Doesn’t look like hell
- Doesn’t take forever to update
- Doesn’t require me being online to write a post
- Allows me to post code that’s syntactically highlighted and easy to copy/paste
- Accepts Markdown
- Fits into my DVCS workflow
- Is free – because screw paying for A BLOG
Seriously, is this too much to ask?
Originally I waded the waters of Posterous but found that not only did it have awkward Markdown syntax, but staging of blog posts was cumbersome. Also, while there WAS gist integration, the code you posted looked like crap. That sucks because most of what I post has code attached.
Others have sold their soul for Wordpress/Drupal/Bumblefuck CMS (whether hosted or unhosted platforms), but it still felt like too much process and not enough action for my taste.
Github to the rescue…again
Hosting static web content was out; like I said before, I don’t really want to ‘manage’ this thing. Jekyll, however, intrigued me. Jekyll is essentially a static site generator that allows you to throw Markdown at it and get static content in the end. There are even Jekyll bootstrap projects aimed at making it (even more) stupid simple. I tried plain vanilla Jekyll and realized that I didn’t really want/need that level of control (again, I’m not into web development). I pulled down Jekyll Bootstrap, but this time it felt a little TOO ‘template-y’. Next, I pulled down an awesome Jekyll template called Left by Zach Holman (seen, conveniently, in the picture on the left). I REALLY liked the look of Left, but was stuck with Jekyll’s code formatting that was…less than ideal. Jekyll is pluggable (and people have made plugins to fix this sort of thing), but I still didn’t have enough experience at that time to be able to deal with the plugins in an intelligent manner.
Octopress = Jekyll + Plugins + <3
During my plugin party, I discovered Octopress, which basically had EVERYTHING I wanted wrapped with a templated bow. I loved the way it rendered code, it supported things like fenced code blocks , and it seemed REALLY simple to update and deploy code. The thing I DIDN’T like was that NEARLY EVERY DAMN OCTOPRESS SITE LOOKS EXACTLY THE SAME! I know I said that I’m not a web developer and didn’t want to tweak styles a great bit, but damn – couldn’t I get a BIT of differentiation? That can be done, but you’re still editing styles (so some CSS is necessary – but not much). After evaluating all three options, I opted for Octopress.
Documentation? Who knew!?
Octopress.org has GREAT documentation for getting setup with an Octopress blog. They even have documentation for setting up Ruby 1.9.3 on rbenv or RVM (I recommend rbenv for reasons beyond this blog), so make sure to check it out if you’re unfamiliar with either. To not reinvent that documented wheel, make sure to check out that site to get Octopress setup (I recommend cloning all repositories to somewhere in your home directory like ~/src or ~/repos, but other than that their docs are solid). Normally I post the dirty technical details, but the point of this post is to outline WHY I made the decision I did and WHY it works for ME.
Pretty code is pretty
I’m not gonna lie – syntactical highlighting with the Solarized theme was pretty sexy. Let’s look at some Ruby:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
How about some Puppet code?
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
Doesn’t that look awesome?
For a blog with a ton of code, something like this is pretty damn important.
Markdown is becoming more prolific as a lightweight way to format text. If you’ve used Github to comment on code, then you’ve probably used markdown syntax at some point in your life. You’ll notice the recurring goal of being quick and precise, and markdown really ‘does it for me’.
It’s really liberating to write a blog post in (insert favorite text editor). Travelling as often as I do, I’m usually jotting down notes in vi because I’m in a plane or somewhere without internet access. Octopress not only lets you write offline, but it will let you generate and preview your site locally while being offline. That’s totally handy. My workflow typically looks like this:
- Generate a post
To start a new post, you can create a new file by hand, or use the
provided Rakefile to scaffold it out for you (NOTE: to see all commands
available to the Rakefile, you can run
rake -T). Here’s how to scaffold
- Edit the post file
- Generate the site content
Remember that Octopress/Jekyll generates static content to be uploaded to your host. With every change, you’ll need to re-generate the content. Yeah, that kinda sucks, but that action has been abstracted away in the Rakefile with the following command:
- Display and view the site
The following command will serve up your page over Webrick in the terminal, just navigate to http://localhost:4000 in your browser to see a local copy of how your site will look once deployed. Once you’re done, just do a Control+c from your terminal to cancel the process.
- Edit/generate/preview until done
- Commit your code and deploy
Because everything is a series of flat-files, you can use git to keep it all under version control. Did you make a mistake? Revert to a previous commit. Deploying to your blog is similarly easy, as you’ll see in the next steps
Be a unique snowflake
I used this article to help change the color scheme of my blog, and checked out a list of other Octopress sites to steal a couple of other tweaks. That’s all I needed for customization, but if you need more knobs they’re there for you to twist.
Hosted by your pals at Github
Github Pages is a free service for any Github user (again free to join) and is an EXCELLENT FIT for an Octopress blog. As you would expect, Octopress has great documentation for enabling deployment to Github Pages. If you have your own custom domain, you can STILL use Github Pages (hint, the instructions are on that page too).
Fuck it. Ship it.
The act of updating a blog has GOT to be frictionless. Is this simple enough for you:
Yep. That’s all it takes to deploy code to your blog once you’ve setup Github Pages. Forget about logging in, wading through a GUI, cutting/pasting content, FTPing things up to a host, and any of that crap. I’ve done that. ‘That’ sucks.
Write your own damn blog
You now have no excuse to NOT share all the cool things you’re doing. Seriously, if you can EDIT A TEXT FILE then you can ‘maintain’ a blog.