For our current project we’ve been making heavy use of markdown, both in the forums as well as developer documentation. I’ve been finding it so painless that it got me thinking about an overhaul of my blog.

I’ve always found Blogger a bit… tedious. I just wanted to write simple posts and not have to fiddle with HTML/CSS too much. But I was using another site to include code snippets. Then there was the browser-based text editor. And having to use a VPN to access it from within China meant I usually couldn’t be asked to bother with it at all.

In writing our documentation I started to really appreciate the model supported by Bitbucket (and Github). A search turned up this post that got me thinking a migration to markdown was within reach. Namely, composing the blog posts in markdown then converting everything to a static website with Jekyll.

Installing Jekyll on OSX

Naturally, things on OSX take a bit more work. I already had ruby installed, so setting up Jekyll:

  1. Follow Jekyll installation instructions. Additionally:
  2. sudo gem install jekyll-import to install jekyll-import
  3. Follow the Blogger import instructions


I’ve become a big fan of writing markdown with Visual Studio Code.

As mentioned in Working with drafts you need to start Jekyll with jekyll serve --drafts to pickup items in the _drafts/ folder.

Open a browser to localhost:4000 to preview the site.

Publishing to BitBucket

jekyll build will output the website to _site/.

Bitbucket provides pretty clear instructions for setting up a static website.

I ended up with a directory structure similar to:

|____ .git/
|____ src/
| |____ jekyll/
| |____ _posts/
| |____ _drafts/
| |____ _site/
| |____ _config.yml
| |____ Gemfile
|____ index.html

This allows me to keep the markdown and generated static site in the same repository. Copying the contents of _site/ to the root of the repository and using git push to publish to Bitbucket.

And with that I bring you!