It would be really meta of me to take a screenshot of this text editor and use it as my header graphic.

Speeding Up Blog Publishing with Markdown

People are good at some tasks. Computers are good at other tasks. I haven't been shy about my love of automating routine tasks so I don't have to do as much, but one area that has remained pretty high-touch has been writing blog posts. I'm not using WordPress or any kind of 3rd-party blog hosting—there's just a plain old normal Laravel blog model that stores the HTML you're reading now. When I first started writing these posts, the IntroCave admin panel had a WYSIWYG (What You See Is What You Get) blog composer similar to what you might see in a WordPress admin panel. After giving the blog a visual refresh, though, it was tedious to constantly switch back and forth from the HTML view to the code view to add the proper CSS tags. I ditched the fancy editor for a plain text box, instead opting to just write all my posts straight in HTML.

I'm being too kind to WYSIWYG editors, though.

I've hated WYSIWYG editors ever since my very first programming job. I was tasked with writing a wiki editor using Adobe's Flex. It suuuuuuucked, and I've hated them ever since. It's not all their fault, though—the problem is how I write.

Write the Post

I don't use a word processor. I don't want to think about formatting. I don't want to think about header graphics. I don't want to think about font-sizes or header-sizes. I just want to write words, and that means just using a dumb simple text editor. I can save my drafts to disk without worrying about refreshing or losing state, I don't have to think about formatting, and I can just work on the content of the article without having to think about anything else.

It would take a tremendous amount of code for a textarea inside of a web browser to have the same level of usability and reliability as a simple text editor. Hotkeys do weird things, sometimes the form's CSRF token expires if you leave it open too long, sometimes they try to do smart autocorrect bullshit that takes you out of your flow. Writing is hard enough without your tools getting in the way, so I prefer to use a tool that's just designed to extract words out of me.

Edit/Format/Publish the Post

Once a post is done, I have to format it for the blog. This mostly means wrapping paragraphs in the right tags, adding links, adding headers, and stubbing in a few images. I add a new feature or widget to posts every now and then, but for the most part, I'm working with a very very small number of types of styled elements. Going in and manually adding CSS classes using the WYSIWYG editor was too cumbersome.

Up until now, I would just switch over from plaintext to HTML. It's not so hard to go copy/paste in a handful of paragraph tags and CSS classes, and it gives me the flexibility to add special formatting if I want to throw a new kind of list in the middle of a post. Tedious: yes. But less tedious than editing in-browser, even though I have to copy/paste my markup into a form field every time I want to preview changes.

This can be a fairly tedious process depending on the ratio of words to other stuff, and it's one of the reasons I decided that outsourcing blog content wasn't worth it. A lot of the content marketing services are set up to publish for you in WordPress, but it would be too much to ask for them to exactly format their posts using the markup that makes them look normal on my blog.

The final step in my editing process is to pass the text through a spelling/grammar checker. I'm currently using Grammarly for this, and it usually catches at least a half-dozen small mistakes.

Enter Markdown

It's hardly revolutionary to say that Markdown solves this problem for me. It's been around for 15 years, pretty much for this exact reason. The reason I didn't switch earlier was honestly just misplaced fear. My writing goes through three phases: WRITE -> EDIT -> PUBLISH. Even though the majority of my writing happens in the writing phase, I do tend to tweak a lot in the editing phase.

I wanted to use a tool to convert my text draft into an HTML draft automagically, but I also knew I would need to hand-edit that HTML markup to add the proper CSS classes. You can't easily go back to the text version once you've made changes to your generated file, as those changes are highly at risk of getting overwritten if you run your processor again. In an ideal world, your generated files are never touched at all—you just publish the output and stick to editing the text versions.

I knew Markdown could do most of that, but I assumed it would be a pain in the ass to augment the generated HTML syntax. Markdown has a bit of a reputation (largely owing to its original author, John Gruber) for being opinionated: i.e. do it our way or don't bother. When I finally sat down to write my own Markdown processor, I realized there was no need. The Red Carpet gem gives you pretty nice callbacks to muck with the output however you want. The whole thing is tiny and should save me at least 30 minutes on every blog post I write. You can see my tiny processing script below.

The thing I like best about this particular gem is that you can mix and match HTML in with your Markdown syntax pretty easily, whether it's a YouTube embed or a Github gist like below. I can never remember the syntax for a link in Markdown, so I just write HTML tags like I'm used to and the processor doesn't whine at me.

Besides saving me time with each blog post, having a Markdown processor also opens the door to hiring writers again. While asking for hand-formatted HTML is a tall ask, requesting an article in Markdown syntax is reasonable. There's always going to be a little bit of work uploading images and fixing paths, but it seems a lot less tedious than it was before.

Moral of the story: keep working on your tools and processes. It's worth it!

If you're curious what my rendering script looks like, I've embedded it below. I could probably bake the Markdown processing step into my web server instead of running a script in the console, but I like having the flexibility to tweak it before it goes in the database if I ever run into something that Markdown can't handle.