This past month I’ve made several changes to my blogging style and configuration that have made my life much simpler and more productive. No more using a VM to compose a simple blog article cause I want to use Microsoft Live Writer or dealing with a database or expensive hosting. The expectation now, as long as topics and words keep flowing composing a blog article and deploying will be quick and painless. I bet you are wondering…What changes? There are three main changes.

1. Blogging platform is now Octopress and Jekyll hosting site on Github Pages.
2. Leverage Markdown syntax to compose bog articles
3. Text Editor of choice is now Sublime Text 2

However, during my journey to Octopress ( requires a separate post ) I’ve noted tweaks along the way to improve my experience. At this point the minor tweaks are mainly to structure and configuration, later I do hope to submit a few plug-ins. A minor pain point is switching between development and production if you are deploying your site in a non traditional manor, like say, to a subdirectory and not the root ( mydomain.com versus mydomain.com/blog ). To my displeasure, I’ve found myself commenting and uncommenting default configuration settings and custom settings in the _config.yml file based on my target deployment environment. Time to review the Rakefile and make some customizations to enable me to switch between environments with ease. For those of us new to Rake, Rake is a build program for Ruby, learn more here.

What is …

What is Github Pages?

The GitHub Pages feature allows you to publish content to the web by simply pushing content to one of your GitHub hosted repositories. [Learn more](http://pages.github.com/)

What is Jekyll?

Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server. This is also the engine behind GitHub Pages, which you can use to host your project page or blog right here from GitHub. [Learn more](https://github.com/mojombo/jekyll/wiki)

What is Octopress?

Octopress is a framework designed by Brandon Mathis for Jekyll, the blog aware static site generator powering Github Pages. To start blogging with Jekyll, you have to write your own HTML templates, CSS, JavaScripts and set up your configuration. But with Octopress All of that is already taken care of. Simply clone or fork Octopress, install dependencies and the theme, and you’re set. [Learn more](http://octopress.org/)

Restate Problem

Unnecessary commenting and uncommenting of default configuration settings and custom settings in the _config.yml file based on my target environment.

Goal

Provide an easy method to target different environments for site generation and deployment using a rake task rather than editing _config.yml settings manually.

Customization Discussion

The Octopress Rakefile is mainly used to create new posts, generate and deploy site to environment of choice. The Raekefile is like any build program, load settings for the environment, run tasks to accomplish some unit of work. The Octopress Rakefile loads config.yml to set Octopress, Jekyll, plug-ins, third party and custom settings consumed by build tasks or passed along to Octopress and Jekyll. The config.yml settings I find myself updating all the time are listed below.

1. root
2. url_base
3. disqus_developer

The idea is to transform a default .yml file with specific environment settings based on target deployment environment. I began fleshing out the design, then something said … wait! Checkout Octopress github to see if anyone has mentioned this as an issue or maybe made a similar change to which I can build upon or simply leverage myself. After some searching, I found a pull request from jpravetz for Rakefile mode switch. In essence he designed, built, and committed a pull request for exactly what I started to outline for myself. See the summary of his pull request below.

Added a rakefile switch to allow deployment to production or development servers.

* Generates _config.yml from source files (config-default.yml + config-MODE.yml) (task :gen_config)
* Can specify different deploy document_root for different modes.
* Defaults to development (rake task names backward compatible)
* Added rake task options, eg. rake generate['production']

Solution

I decided to proceed with implementing jpravetz pull request in my fork with a few minor changes purely based on preference. I despise senseless typing, environment abbreviations are well known ( dev, test, stage, prod ), these will serve as my environment file and mode naming convention.

• _config.yml – now fully generated by the gen_config[“mode”] task.
• _config-default.yml – defines all default octopress settings, used in the merge.
• _config-dev.yml – defines all development environment settings, used in the merge based on ‘mode = dev’
• _config-prod.yml – defines all production environment settings, used in the merge based on ‘mode = prod’

The generate rake task defaults to ‘dev’ and can be overridden by doing bundle exec rake generate[‘prod’].

It is also my preference to only leverage the “Preview Mode” for posts that are getting one last critical review before publishing to production NOT to use for marking drafts. I prefer to organize my drafts in folders as outlined below.

• _drafts
• _drafts_pages
• _drafts_private
• _company_drafts
• _company_drafts_private

I work mostly with drafts and posts folders moving *.mkd files between them. My current work-flow is something like this:

1. Create new draft post using new_draft[“Filename”] rake task
2. Work on it at my leisure or as time permits
3. Satisfied with draft, ready to preview in local site, publish draft as a post using publish_draft[“PartOfFileName”]
4. Generate local site – run bundle exec rake generate
5. Preview local site – run bundle exec rake preview
6. View in Chrome
7. All is good deploy the new post to live blog site. Otherwise I will work on it locally or yank it back to a draft post using yank_post[“PartOfFileName”]. It really depends on my time. I do not like leaving incomplete posts or drafts in my post directory for fear of deploying by mistake. I want my post directory to be clean and contain production ready posts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# usage rake new_draft[my-new-draft] or rake new_draft['my new draft'] or rake new_draft (defaults to "new-draft")
desc "Begin a new draft post in #{source_dir}/#{posts_drafts_dir}"
task :new_draft, :title do |t, args|
  raise "### You haven't set anything up yet. First run `rake install` to set up an Octopress theme." unless File.directory?(source_dir)
  mkdir_p "#{source_dir}/#{posts_drafts_dir}"
  args.with_defaults(:title => 'new-draft-post')
  title = args.title
  filename = "#{source_dir}/#{posts_drafts_dir}/#{Time.now.strftime('%Y-%m-%d')}-#{title.to_url}.#{new_post_ext}"
  if File.exist?(filename)
    abort("rake aborted!") if ask("#{filename} already exists. Do you want to overwrite?", ['y', 'n']) == 'n'
  end
  puts "Creating new post: #{filename}"
  open(filename, 'w') do |post|
    post.puts "---"
    post.puts "layout: post"
    post.puts "title: \"#{title.gsub(/&/,'&')}\""
    post.puts "date: #{Time.now.strftime('%Y-%m-%d %H:%M')}"
    post.puts "comments: true"
    post.puts "categories: "
    post.puts "keywords: """
    post.puts "---"
  end
end

As you can see from the code above you will need to define a new variable called posts_drafts_dir or whatever you see fit to alter it too at the top of the Rakefile with the others. You may also notice I include categories and keywords in the Octopress/Jekyll header these are left out from the default new_post rake task.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# usage rake publish_draft[my-draft] and reset the date to today
desc "Move draft post to _posts."
task :publish_draft, :filename_partial do |t, args|
  raise "### You must specify file name partial." unless args[:filename_partial]
  move_dir = "#{source_dir}/#{posts_dir}"
  new_date = Time.now.strftime('%Y-%m-%d %H:%M')
  new_file_date = Time.now.strftime('%Y-%m-%d')
  FileUtils.mkdir(move_dir) unless File.exist?(move_dir)
  Dir.glob("#{source_dir}/#{posts_drafts_dir}/*#{args.filename_partial}*.mkd") do |post|
    new_file_name_suffix = post.match(/-[a-z]\w.*/)
    new_file_name = "#{move_dir }/#{new_file_date}#{new_file_name_suffix}"
    FileUtils.mv post, "#{new_file_name}"

    # read the file and update the date: header
    text = File.read(new_file_name)
    puts = text.gsub(/(date:\s\w.*)/, "date: #{new_date}")
    File.open(new_file_name, "w") { |file| file << puts }
  end
end

The code performs the following tasks:

1. Rename the draft post, replace the current date part in the file name with todays date less time.
2. Move the file from _drafts directory to _posts directory
3. Then I read the file from _posts, perform a regex replace for the date header that Octopress and Jekyll read for todays date.
4. Done.

The feature I like the most about this rake task is that I can just type in the first few words of the draft that uniquely identify it. For instance, moving this blog post from _drafts to _posts I would run bundle exec rake publish_draft[“target-any”].

1

  Dir.glob("#{source_dir}/#{posts_drafts_dir}/*#{args.filename}*.mkd") do |post|

The magic is simple, on line nine above, get a list of file paths matching the anything before the passed in file name partial and anything after with .mkd extension.

1
2
3
4
5
6
7
8
9
10

# usage rake yank_post[my-draft]
desc "Move post to _drafts."
task :yank_post, :filename_partial do |t, args|
  raise "### You must specify file name partial." unless args[:filename_partial]
  move_dir = "#{source_dir}/#{posts_drafts_dir}"
  FileUtils.mkdir(move_dir) unless File.exist?(move_dir)
  Dir.glob("#{source_dir}/#{posts_dir}/*#{args.filename_partial}*.mkd") do |post|
    FileUtils.mv post, move_dir
  end
end

The code above simply moves a file from the posts directory to the drafts directory.