Blogging with Middleman

Richard LaFranchi

Fri Mar 27 2015

This is my fourth post in four days blogging with Middleman App. I've been having a blast so far and wanted to share my experience with using Middleman. I'm using Middleman's Drops Template with some small customizations. I was looking for something quick, simple, and stylish to get it up and running. Initializing the application with this template was super simple.

# Getting Started

Prerequisites: Git, Ruby

Install Middleman:

$ gem install middleman

Install the Drops template:

$ mkdir ~/.middleman
$ cd ~/.middleman
$ git clone https://github.com/5t111111/middleman-blog-drops-template.git blog-drops

Initialize a project with the Drops template:

$ middleman init my_blog_project --template=blog-drops
$ cd my_blog_project
$ bundle install

Run the Server

$ bundle exec middleman

You can now see your blog at http://localhost:4567

# Configuration

You'll need to edit the configuration file to suit your needs. The Drops template includes some neat options such as your social links, google analytics tracking, site meta description, and others. Here's the main set of lines in the config.rb file that you will want to customize

# /config.rb

###
# Site Settings
###

# set site URL
set :site_url, 'http://blog.example.com'
# set site title
set :site_title, 'Drops Template'
# set site description (only used for meta description for the moment)
set :site_description, 'Site Description'
# set site author name
set :site_author, 'Site Author'
# set site author profile information
set :site_author_profile, 'Lorem ipsum dolor sit amet, cu facilis indoctum interpretaris has. Ius ea quod euismod fierent, per in legere gubergren accommodare, ut labitur partiendo urbanitas duo. Tamquam inciderint at sed. Per at nibh graecis intellegebat. Probo brute ancillae sit ex, tota recusabo disputando usu et.'
# set site author profile image (should be in images_dir)
set :site_author_image, 'profile.png'
# when true, the page and site titles will be reversed (page title | site title)
set :reverse_title, true
# twitter/facebook/github/linkedin links in author page (otherwise set nil)
set :social_links,
    twitter: 'https://twitter.com',
    facebook: 'https://facebook.com',
    github: 'https://github.com/5t111111',
    linkedin: 'https://linkedin.com'
# set Google Analytics account, like "XX-12345678-9"
# set :google_analytics_account, 'XX-12345678-9'

I decided to keep the same profile image, but just replaced it with my own photo in the directory /source/images. You can also replace the drops.png header image as well.

# Writing a Blog

Your posts can be created in the directory /source/posts and the naming patter is as follows.

{year}-{month}-{day}-{url-slug}.html.md

For example, let's say you want to create a hello world post dated on January 1, 2001. The file would be named 2001-01-01-hello-world.html.md. I've been writing my posts in markdown. Middleman is setup to use front matter to define certain variables. For example I can define the title and tags for the post at the top of the filelike so:

---
title: Hello World
tags: one, two
---

The Drops template also includes some nice styling for writing code blocks. Here's how a nice Ruby block looks.

def juicy_fruit
  puts "The Taste is Gonna Move Ya!"
end

# Deploying to Github Pages

It is possible to deploy the blog to heroku or any host for that matter, but I decided to take advantage of my free Github Page at rlafranchi.github.io. You'll need to create a public github repo where the repo name is your pages url. Since my github username is rlafranchi, my repo was set accordingly. I started by adding the middleman-deploy gem to my Gemfile

# Gemfile
gem 'middleman-deploy' # make sure to run bundle install again

You'll also need to initialize a repo locally and set the remote origin to match your github repo. Once that is done you'll want to create a new branch in your repo like so:

$ git checkout -b blog

In my case I called it the blog branch and from here on out any changes will be committed to the blog branch. We will need to add the following configuration.

# config.rb

activate :deploy do |deploy|
  deploy.method = :git
  deploy.branch   = 'master'
end

Once you've written a post, then you are ready to deploy. The following will compress and compile files and push the build directory to the master branch.

$ middleman deploy --build-before

Browse to your github page and enjoy! You could also run $ middleman build and upload the build directory to a hosting account of your choice.

# Adding Disqus

A huge benefit of using middleman as opposed to a CMS like WordPress or Drupal is that you do not need a database. This limits the ability to handle comments, so I looked at a third-party solution called Disqus. Feel free to make a comment below. All I had to do was create a partial in the directory source/partials which included the javascript code provided by Disqus when you create an account and add a site. The Drops template uses the slim syntax.

#disqus_thread
javascript:
  /* * * CONFIGURATION VARIABLES * * */
  var disqus_shortname = 'shortname';

  /* * * DON'T EDIT BELOW THIS LINE * * */
  (function() {
      var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
      dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
      (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
  })();
noscript
  Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a>

I then included the partial in the layout

-# source/layouts/layout.slim
- unless current_article.nil?
  = partial "partials/disqus"

# Thoughts

So that's my experience so far with Middleman, and I expect I shall continue to use it for my blog. It's perfect for my use case of being able to share code and various projects I've worked on.