I run two email newsletters for the Graduate School. One delivered weekly through MailChimp and one monthly through lists.oregonstate.edu. The monthly newsletter is also posted to our Drupal website. I spend a lot of time on these newsletters and what follows is how I write and proof them. I also use these methods for copy editing blog posts and other types of editing and writing (minus the CSS inlining.) At the end, I’ll share some additional tools that I hope to incorporate in the future.

Write in Markdown

For me, the easiest way to write my newsletters is in Markdown. While Markdown is not an exact standard, there are enough services using it that it is fairly well supported across the web and within tools. Github supports it. BeeGit is a content writing and editing platform that uses it.

I use the Sublime Text 3 text editor with the Markdown Editing package. The Markdown Editing package gives you some special highlighting, a color scheme, and other niceties. It does not, however, provide an HTML preview. When first writing in Markdown, I used BeeGit for its preview and Markdown cheat sheet until I became more comfortable with the syntax.

Why do I use Markdown? My top reasons:

• Conversion to HTML with Pandoc (more on this later)
• I can use my text editor (goodbye Word)
• The files are only plain text for maximum preservation value
• Creating a link is a breeze
• Creating a link is a breeze
• Creating a link is a breeze

So yeah, creating links is a breeze. My newsletters take the format of blurb and link, blurb and link, etc. If I had to create each link using a WYSIWYG, I would find a new line of work.

Words to avoid, grammar and style

Some talented people have released tools that check your text for common errors beyond spelling mistakes. I use four of these.

Proselint focuses on usage, not grammar. Here’s a list of what it checks for. It is a command-line only tool at this time.

retext-mapbox-standard is a combination of language tools that checks for gendered language and potential slurs, words to avoid in educational writing, jargon, and more, plus it can read Markdown. The project is meant as an example of what organizations can do to enforce their own style guides, but I use it as provided by Mapbox. Also a command-line tool.

OSU copy cop is a tool I made that checks some of the editorial standards set forth by OSU. Saying “I made” isn’t really true: I copied it from the original Copy cop and added a few OSU things.

Grammerly is a web and desktop application that checks usage, grammar, spelling, and more. Available as a free tier and paid tier. I copy my text into it and out of it, which isn’t efficient, but gets the job done and it doesn’t complain about the Markdown I paste in. The available browser plugin also checks your text while you write posts on websites like Facebook and Twitter, which can help you avoid some embarrassing mistakes.

Pandoc to convert to HTML

Pandoc is a fantastic tool that converts between file types. Converting Markdown to HTML goes like this:

pandoc -o file-out.html file-in.md

That’s it and bam! HTML ready to go.

Add CSS to the header

For my monthly email newsletter I like to inline some of my CSS into the HTML, so before sending it through an inliner tool (see below) I have pandoc create a standalone HTML document with my CSS in the HEAD of that doc. If you give Pandoc the -H option it will grab the contents of that file and put it in the HEAD of the doc you are creating.

pandoc -o -s file-out.html file-in.md -H add-to-head.html

The add-to-head.html file looks like:

<style>
  p {
    margin-bottom: 1em;
  }
</style>

Inline the CSS

Now that my HTML doc is ready with the styles in the HEAD, I can run the whole thing through an inliner tool and it will put the styles inline with my HTML. I use Mailchimp’s inliner tool for this. I think there are some command line tools for this (like Juice) but this website makes it quick.

Add to Drupal and send email

Finally, after the inliner step, my newsletter’s HTML is ready. I go to my Drupal site and paste in the HTML. From there I copy the text and paste it directly into Gmail for sending. The result is a plain, single column newsletter layout. Here’s an example.

Future improvements

I’d like to add a HTML template system (like this or this) to my workflow so I can create better layouts for the email newsletters. For that, I’ll need to go back to an email program that allows me to edit the HTML directly, like Thunderbird, or use an email service provider. For Mailchimp, WordPress, or anywhere else I just need HTML, I follow the steps above but stop after I convert the Markdown to HTML.

— John McQueen, Web Communications, Oregon State University Graduate School