A Markdown-based Workflow

Writing in Markdown is quick and easy, so just about everything I do begins its life as Markdown. If you do this for a while, you realize that you want to go back and edit things, so now you've got some choices.

  1. Forget the original (if you even still have it) and just do edits on the resulting HTML.
  2. Keep the original Markdown around and go through the "publishing" process every time you make a change.

One obvious drawback to the first option is interrupting the writing process to deal with tags. Another is that HTML might not have been the final destination. Maybe you converted it to a PDF or something.

The second option, which is how I lived for a long time, gets to be a pain in the ass. It usually involves making changes to the original, generating HTML, going to the HTML version and removing the old <body> contents and pasting in the new, then copying the new version to whatever web server it lives on. And that's the best case scenario. There's usually more to it.

So, what I've been able to do for just about every task is keep the original Markdown and either eliminate or greatly simplify the conversion process. Here are some examples.


I've been a TextMate user longer than a Markdown user, but as it turns out, TextMate has excellent support for writing Markdown. Probably no need to go into detail here.

Publishing to the Web

This is a fairly obvious application. I wrote RenderMarkdown to address some of my needs here. Just save the file to a web server and walk away. The conversion to HTML happens on the fly. It's a key component in a documentation repository I use at work, but that'll be a separate post.

For posting dated content, like articles or blog entries, Mango is just about perfect. Again, you basically just save a file to the web server and you're done, but with Mango your documents are automatically sorted by date, indexed by tag, searchable, etc.

Generating PDFs

There's a great tool called wkhtmltopdf. It does some of the same things as htmldoc, but it supports CSS so you get much better control over the final appearance. In addition to the content itself, it can automatically generate a table of contents from the headings in the document. The specific command I use is:

% wkhtmltopdf -t --outline foo.html ~/Desktop/foo.pdf

Of course you can create a command in TextMate to automate this (much like the mail command discussed below). There are just a couple of issues with wkhtmltopdf that I have yet to resolve.

  • It doesn't seem to be able to see all of the system fonts in Mac OS X. It's technically an X11 application, so I don't know how that works.
  • It doesn't handle unusual characters, like ⌘ correctly. This is quite possibly another symptom of the same font issue.

On the iPhone

There are a few Dropbox-based text editors for iOS, but the one I've settled on is Elements because of its support for Markdown. Because it uses Dropbox, you can create files on either your iOS device or computer, and if those files happen to be Markdown, you can generate an HTML preview in Elements. (I actually requested this feature and it was implemented and approved in the App Store within a couple of weeks, so responsive developers are another plus.)

Sending HTML E-mail

Wait, what? Ew.

Yeah, I know. It's not something I do very often, but when I need to have some fancy formatting in an e-mail message, of course I want to just write Markdown then send. For this, I have a TextMate command that involves Safari and AppleScript.

I don't think it's clean or stable enough to share the actual code, but I'll describe the basic process.

  1. Create a temporary file which includes:
    • An HTML skeleton to open/close <html>, <head>, <body>, etc.
    • CSS pulled in from a file referenced by $TM_MAIL_CSS
    • The HTML generated from the document itself
  2. Open the temporary file in Safari
  3. Tell Safari (via AppleScript) to send the page as E-mail then close it
  4. Remove the temporary file

From there, you add the recipient and subject. It obviously works better for sending new messages than for replying. I suppose I could come up with an AppleScript in Mail that opens a reply as a new Markdown document in TextMate, but I haven't taken it that far yet.

So, that's about it. Anyone else have any tricks of this sort or maybe some ways to improve what I'm doing? The one thing I don't think I'll ever figure out is how to type "Markdown" on the first try (as opposed to "MArkdown"). Every fuckin' time, I swear.

blog comments powered by Disqus