QR Code contains TinyURL of this article.A Web Publishing Workflow

Introduction

I really enjoy writing for my nanoc-generated website. I’ve spent some time tweaking things to my liking and I’ve now got a robust, fast and lean publishing platform that’s a pleasure to work with.

In this article, I am writing about the workflow I employ on this website.

Rakefile

I begin by creating my new post from the CLI with the command:

rake new_post\["My Super Post"\]

which runs this Ruby script:

require 'stringex'
desc "Create a new post"
task :new_post, :title do |t, args|
  mkdir_p './content/weblog'
  args.with_defaults(:title => 'New Post')
  title = args.title
  filename = "./content/weblog/#{title.to_url}.md"
  if File.exist?(filename)
    abort('rake aborted!') if ask("#{filename} already exists. Want to overwrite?", ['y','n']) == 'n'
  end
  puts "Creating new post: #{filename}"
  open(filename, 'w') do |post|
    post.puts '---'
    post.puts "title: \"#{title}\""
    post.puts "created_at: #{Time.now}"
    post.puts 'kind: article'
    post.puts 'published: false'
    post.puts 'tags: [  ]'
    post.puts "---\n\n"
  end
  command = 'open -a \'Sublime Text 2\' ' + filename
  exec command
end

The script creates a Markdown file — with a HTTP-friendly slug — and writes some YAML front-matter. It auto-populates the post title and time-stamp. Then it loads that file up in to Sublime Text 2 from where I can immediately start writing.

Sublime Text

When I consider the CMS applications I have used over the years one common grievance I’ve had with them all has been their reliance on a WYSIWYG editor, whether web or desktop based. When I’m writing, regardless of the medium, I don’t particularly want to consider styling, formatting, HTML or anything else, I just want to get my words down.

I write with the Sublime in OS X’s full screen mode. In this way I can write without distraction and with complete disregard of presentation. Sublime’s minimal interface results in a writing environment where all I can see are my words. The editor is fast to start up and suffers no lag when in use. In short, it gets out of my way, whilst providing everything I need to get the job done. Sublime Text is the perfect name for it.

Markdown

I use a variant of Markdown1 called Kramdown in my posts. Writing with Markdown reminds me of writing in the word-processors of old — WordStar and its ilk — where the author controls formatting with control codes such as ^B for bold, ^Y for italics and ^S for underscoring.2  In Markdown we can achieve similar results with, for example, *italics* and **bold** which results in “italics and bold”.

One can also use Markdown to add hyperlinks and images to a document with the same plain-text paradigm. Kramdown, as a superset of Markdown, goes even further by providing syntax for the following compositing elements:

  • tables
  • footnotes
  • abbreviation / acronym expansion
  • definition lists
  • fenced code blocks
  • maths blocks

Writing in Markdown is easy, it demands no thought beyond the composition of the text.

nanoc compiles my website revisions in iTerm in the foreground. In the background, Sublime Text 2, the editor.

Guard

Guard automatically launches a nanoc compile any time I make a change within a series of monitored folders in my local instance of the Perpetual βeta website. So, if I save a post in Sublime, Guard detects the change in the file-system and nanoc re-compiles the website. But nanoc is smart enough to only compile pages that are actually changed by my edits, so rebuilds are fast.

Thanks to this immediate compilation, I’m able to review my local instance in real time.

Proofing

I use a trio of scripts provided by Matt Might for highlighting passive voice, weasel words and duplicates in my writing. I run these via a small Bash script with a simple proof my-super-post.md command (I have aliased proof in my Bash profile). The Bash script looks like this:

#!/bin/sh
if [ "$1" = "" ]; then
 echo "usage: `basename $0` <file> ..."
 exit
fi
echo "Weasel Words: "
~/shell_scripts/weasels.sh $*
echo
echo "Passive Voice: "
~/shell_scripts/passive_voice.sh $*
echo
echo "Duplicates: "
~/shell_scripts/dups.pl $*
echo
echo "Spell Check: "
cat $* | aspell -H list | sort | uniq -c

The output consists of numbered lines from my Markdown file where proof has determined that I could improve the writing:

weasel words:
54: I write with the editor in OS X’s full screen mode. In this way I can write without distraction and with complete disregard of presentation. Sublime’s minimal interface results in a writing environment where all I can see are my words. The editor is fast to start up and suffers no lag when in use. In short, it gets out of my way completely, whilst providing everything I need to get the job done. Sublime Text is the perfect name for it.

passive voice:
80: I use a trio of scripts provided by Matt Might for highlighting passive voice, weasel words and duplicates in my writing. I run these with a small Bash script with a simple `proof my-super-post.md` command (`proof` is aliased in my Bash profile). The Bash script looks like this:

duplicates:
my-super-post.md:76 my

Spell Check:
1 teh

We can see from this that I should remove the word “completely” from line 54 and that the phrase “is aliased”, in line 80, is passive voice. I have also duplicated the word “my” on line 76. To add insult to injury, I have also misspelled the word “the.”

Title Capitalisation

I use Aristotle Pagaltzis’ version of John Gruber’s Title Case Perl script, as an OS X service, to check that I have capitalised my headlines and titles correctly.

Presentation Review

I finally get to read the post on my local instance at this point. This is usually the first time that I consider presentation. If any adjustments are necessary then I take care of them at this stage.

HTML Tidy

Then, to apply the final polish, I process the generated HTML file(s) with “HTML Tidy for HTML‍5”. This step ensures that I have well-formed (and nicely formatted) HTML that is (almost) guaranteed to pass W3C Validation.

Publish

When I am happy that my post is complete and free of obvious error, I can finally publish it to the live website. I do this with a simple Git commit:

git commit -am "New Blog Page: My Super Post"

Then I push the new release to Git:

git push

which uploads any revisions or new content to the production repository. A post-commit hook on the repository then checks those changes out, directly on to the live website, and my revisions are then live.

Post Publishing

I have a couple of IFTTT “recipes” that take effect once I publish a new article. The first tweets the post title and link to my Twitter stream and the second sends the same information as an update to my LinkedIn profile.

Periodic Maintenance

There are some periodic maintenance tasks I perform to keep the Perpetual βeta in tip-top condition.

  • I use Integrity to check for broken links — both internal and external;
  • I also use Google’s Webmaster Tools to advise me of errors and other things that might need my attention;
  • Another service I rely is Unicorn, the W3C’s Unified Validator. This all-in-one-place tool checks the HTML, CSS, Feeds and Internationalisation of any page I point it at.

Final Words

I am happy with this process. I love its simplicity and the speed with which I can move through it. I perform almost every step of this process from the command-line and within Sublime Text, with barely a GUI in sight. It’s a textual workflow rather than a visual one. Surely, as it is words I am crafting, that is as it should be?

Updated: 21st April, 2014.

Added the “Title Capitalisation” section.

Updated: 26th April, 2014.

Added the “Periodic Maintenance” section.

Updated: 1st May, 2014.

Added the “Post Publishing” section.

Updated: 1st Jan, 2015.

Added the “HTML Tidy” section.

  1. John Gruber’s text-to-HTML syntax. ↩︎

  2. See also Kevin Lipe’s take on using Markdown and a plain text editor in the evocative article, “Markdown is the New Word 5.1” ↩︎