fd Blog

Daniel Hilgarth on software development

Blogging Workflow

One goal for when actually writing my posts was low friction. I didn’t want to execute ten different commands to just commit the fix of a typo.
Ten commands, you ask? Well, here you go:

  1. CD into the submodule
  2. Add the changed files to the staging area
  3. Commit the staged files
  4. Push the new commit
  5. CD out of the submodule
  6. Add the changed submodule to the staging area
  7. Commit the changed submodule
  8. Push the new commit

OK, only eight commands, you got me :-)
But anyway, that was way too much friction, so I added a push_posts rake task.
Now, I can simply edit my posts and when I am finished, execute rake push_posts["Commit message for posts"] - or rake push_posts if I am lazy - and that task takes care of the rest.

I added it to a new file called octopress_extensions.rb. I did this to make as little changes as possible to the original Rakefile.
The only thing I did change was adding import after the requires:

import "octopress_extensions.rb"

But there was more that caused friction:
While Octopress comes with its own new_post rake task, it had one big problem: It doesn’t support a workflow where you first write your posts as drafts.
To fix this, I created a simple directory layout with the two folders Drafts and Publish and added a few rake tasks to it.
The end result allows you to execute rake new_draft[title] to create a new draft and to publish it via rake publish_draft[draft_specification].
The rake tasks automatically take care of setting the appropriate properties in the YAML front matter of the post so that the drafts won’t be published by Octopress or Ruhoh. Additionally, it uses the current date when a draft is published, because you normally don’t want to use the date you created the draft as the publishing date.

This complete directory structure can live under source/_posts, so you won’t lose the preview functionality of Octopress. I actually created a private fork of this repository and added it as the posts submodule.

I published this as a GitHub repository, so go check it out!

With all these changes, I finally arrived at this workflow:

  1. Create a new draft: rake new_draft["Blogging Workflow"]. BTW: This will automatically open the new draft in the editor.
  2. Write the post
  3. Preview it: rake preview
  4. Correct/finish the draft
  5. Publish it: rake publish_draft["Blogging Workflow"]
  6. Commit all changes: rake push_posts

The only friction left is the fact that I have two rakefiles that live in different directories:

  • Steps 1 and 5 have to be executed from within source/_posts.
  • Steps 3 and 6 have to be executed from the root directory of the Octopress installation.

I could have added all the functionality to my octopress_extensions file, but I decided against it.
I wanted the posts directory to be self contained to support another workflow:
Wherever I want to author my posts, I only have to checkout the Posts repository instead of the complete Octopress repository and still have the functionality of being able to easily create drafts and publish them.
Back at the computer with the Octopress installation, I now can do a rake pull_posts and be up-to-date.

Instead of adding the functionality itself to octopress_extensions I am thinking about adding forwarding wrappers there. But I am not yet convinced that this is a good idea, so I haven’t done it so far.