World of Dualities

Random ramblings of a software geek.

Yet Another Getting Started Post - Blog with Octopress 3 on Windows 10

TLDR;

  • Blog more than you tweet
  • Static blogs are great if you are a developer
  • Octopress is a good platform to setup a technical blog, but you need to know Jekyll first
  • Setting it up on Windows is slightly tricky if you are new to Ruby
  • This post has some useful tips to help you with that

Why blog?

I was recently evaluating the kind of activities I was doing on a daily basis and found that I was consuming a lot more content that creating it. Also, I was spending a lot more keystrokes on twitter than a less ephemeral medium like a blog.

So, inspired by Scott Hanselman’s urging devs to blog more, I decided to do some more blogging. (Let’s see how this turns out!) I had a very minor presence before on blogger - but wanted to own my content from now on.

Since then, I spent some (too much?) time trying to decide a good platform to setup my blog - and thought it might be a good idea to post my thoughts and struggles when I finally managed to get this blog up and running.

The idea of a statically generated site, without the headaches of performance and security are very appealing to me. Looking at what others have done, I found that Jekyll is a popular platform, and Octopress seemed to improve upon it. So after considering various options, I settled on using Octopress.

This is where ‘the fun’ began.

My starting point

I’m a web developer who’s spent a lot of time on the Microsoft stack. Windows is my main OS - and I’d never developed with the Ruby language/ecosystem. I plan to go into more detail in a separate post about the specific technical issues I had to solve, but this post about is what worked for me in the end.

The main issue I found with various (helpful) blog posts around the web describing how to use Octopress / Jekyll was a ton of unsaid assumptions - and a primary focus on devs who already knew Ruby or were on a Mac/Linux etc.

I wanted to avoid that, so here goes:

Assumptions

  • You are a web developer on Windows looking to setup a ‘statically generated’ blog
  • You know about DNS in general and can figure out how to setup domains etc
  • You can deal with the commandline
  • You know about Git (an awesome distrbuted version control system) and GitHub and already have git installed
  • You know about Chocolatey (a great machine package manager for Windows)
  • You know about Markdown
  • You’re willing to try out new things
  • You don’t know much about Ruby (in reality, this post has nothing much to do with Ruby anyway - other than setting it up so Octopress can be installed and used)

What I will cover

  • Basic setup of Octopress on Windows (what worked for me)
  • Some thoughts on how I setup my repo

What I will not cover / repeat

Using Octopress 3 on Windows 10 and publish to Github pages

At the end of this, my plan was to: - Have a Github pages hosted statically generated blog (for free) - Have my custom domain pointed to it - (Later) Be able to easily add some of the features/services found on a more full-featured platform like Wordpress

Setup steps:

1. Install Ruby using Chocolatey

From an admin PowerShell session, run:

  choco install ruby -y

Chocolatey installs applications at C:\tools by default. I personally don’t like that - but I can live with it: they have their reasons.

This gave me Ruby at C:\tools\ruby21.

2. Install DevKit

Ruby has a package manager (gem - like Nuget in the Microsoft world) - and some packages need native ‘compilation’ after installation. This is what the DevKit enables/simplifies? on Windows.

In the same admin PowerShell session, run:

  choco install ruby2.devkit -y

This gave me Ruby DevKit at C:\tools\DevKit2.

In my case, the DevKit installation (tried and) did not discover where Ruby was installed. So I had to tell it where to find Ruby.

Find the C:\tools\DevKit2\config.yml file and add the following line at the end (this is the location of your Ruby installation) (note the forward slashes and include the - at the beginning):

  - C:/tools/ruby21

3. Install Octopress (which brings Jekyll with it)

Now, you can use the gem package manager to install the Octopress gem (i.e package).

  gem install octopress

4. Setup a new blog using Octopress

The docs on Github for Octopress assumes a lot and (to me) wasn’t clear if you started with a init or new.

It turns out that if you have nothing are you want to start a new Octopress blog, you can run:

  octopress new blog

This will create a directory called blog, setup Jekyll (as if you ran jekyll new), and initialise Octopress.

5. Setup a Git repo for the Octopress blog

I left the Git setup till after I got Octopress setup locally - because this was something I already knew how to do, but I was (still am) not sure what the best way to setup the Octopress blog repo is for my needs.

I didn’t want people to view my half-baked draft posts. So for now, I decided to setup another ‘remote’ for my git repo - on Bitbucket, which is another good place to host your source repositories.

So I set it up with:
- A remote on Bitbucket to hold the blog source, settings etc. - A remote on Github to publish the generated site to Github pages using Octopress

Setting up Octopress deployment to Github involves running:

  octopress deploy init git https://github.com/krishna-nadiminti/krishna-nadiminti.github.io.git

from your blog directory.

When trying to deploy to Github, at one point Octopress complained - and gave me some guidance on how to setup the repo. This happened when I was on the master branch with some uncommitted changes. Octopress said:

  You cannot deploy to the same branch you are working in.
  This will overwrite the source for your site.

In the end, I’m not sure if this is the right way to set it up, but I have it working this way:

  git remote -v

  deploy  https://github.com/krishna-nadiminti/krishna-nadiminti.github.io.git (fetch)
  deploy  https://github.com/krishna-nadiminti/krishna-nadiminti.github.io.git (push)
  origin  https://bitbucket.org/krishna_nadiminti/blog.git (fetch)
  origin  https://bitbucket.org/krishna_nadiminti/blog.git (push)

  git branch

  master
  * source

So, a remote called deploy pointing to Github which seems to be the default remote Octopress uses to publish changes, and origin is the source on Bitbucket, and a branch called source to keep the source files, and master for deployment.

In my case I have the following in my .gitignore:

  _site
  .sass-cache
  .jekyll-metadata
  _deploy.yml
  .deploy

Now that Octopress is setup, let’s briefly look at the directory structure it created (note that I didn’t yet setup themes and other integrations):

Blog directory structure

Publish flow

The flow I’m using to get my blog posts published is:

  • Create/Edit a (new) page / post / draft using :
    • Octopress commands (octopress new draft / post / page)
    • Or using your favorite editor, create .md files in _drafts / _posts / _pages folders
  • Add your post content using the markdown syntax to your .md file
  • Generate your blog using jekyll build
  • If you created a draft, you need to octopress publish _drafts/[file name of draft.md] before you build it, to see it on the generated site
  • Save and preview by running jekyll serve (and browsing to http://localhost:4000 - the default server jekyll runs up for previewing your blog)
  • Once you are happy, commit your changes to Git and deploy using octopress deploy
  • Push to the remote where the source is (because Octopress just deploys the generated content under its _sites folder)
  • Enjoy, profit, get rich etc.

I hope this post will help someone trying to setup Octopress on Windows.

Till next time…take it easy!

Comments