How to publish a newsletter so you own your writing

—— notes —— 5 mins

Heads up! This workflow was dependent upon Mailchimp allowing free access to their "import by URL" function, which is no longer the case as of September 2019. That's how the web works these days ¯_(ツ)_/¯ I now use Substack, even though it is "locked away".

I write a newsletter called The Littoral Line. It's mostly an outlet for me to summarise and clarify my thoughts about what I've found interesting, and to share them with other people. I took the road less travelled when I set up my newsletter. Mostly to play with the available systems to find a way to publish in markdown, with the least friction possible. Partly because I was concerned about owning my writing. That's not to say I thought it valuable, but that I just don't like the aesthetics of having it locked away on some platform, ready to be forgotten and lost forever when the platform gets acquihired.

I wanted it to be just a folder of files on my computer so that I could simply create a new blank document and start writing. But I also wanted those files to work as a publishing system. What follows is a short explanation of how I do this.

The newsletter system

So I own my writing, I create a website of newsletter posts which I publish to a subdomain of this site: Then I import each post into Mailchimp via its URL to create a new email campaign. This means I never write within the email delivery platform. And all my letters are just markdown files, just as they are on this website's blog.

Yes, I still use Mailchimp to send out the actual emails. I always try to defer to the best available tools for the job, and because I have no wish to learn about email delivery I definitely want to defer this difficult technical job to one of the many excellent freemium products available.

Because the best writing tool for the web is markdown, I use Jekyll to build the newsletter site. There are other web publishing tools emerging—which I've actually written about in my newsletter—but none allow me to keep the simplicity of an old school CSS file (the styles in emails need to be inline and the markup table-based for email clients to handle them). I also have some old projects on Jekyll, so I need to keep my hand in it.

Publishing a newsletter in two steps

I have two basic steps for publishing a newsletter: write it, then queue it.

Write it directly on Github

I write directly on Github by creating a new markdown file in the _posts directory. When I save that file, I get a new post published on my website via some webhooks magic (this also points to Github being a pretty good CMS).

Just remember to name the file correctly and to set Jekyll front-matter with the appropriate edition title and date. This isn't an extra step: you'd still need to configure a newsletter's title and metadata within a platform editor anyway.

Schedule it (via RSS)

Using the newly published website blog post URL, I schedule up a new email campaign in Mailchimp using their "import HTML from URL" option. When I have some more time I'll add an RSS feed to the website and point Mailchimp to watch this feed. This should cut out the Mailchimp queuing. But haven't tried this yet, so I can't say "from here on it's trivial…" just yet.


There is some prior setup and configuration necessary. If you were to fork my repository and replicate my system, you'd need to:

  • setup your own domain that is linked to a Github-based deployment service, such as Zeit Now.

  • setup an account with any email service that allows you to create a newsletter campaign from a URL, such as Mailchimp.

Once you have this, you won't actually need to setup a local development environment. You'd simply update the alias fields within the now.json config to match your website domain, create a new markdown file, and start writing.

Running the writing system locally

If you don't like the Github writing experience, you can create a new markdown file in your local file system. That way you can write using your favourite code editor or indeed your favourite markdown editor. So long as your markdown file sits within your project's _posts directory, you're good to go.

If you want to preview the post as it would appear in the email, run a Jekyll development server with bundle exec jekyll serve --watch (I have this set as a simple bash alias js so I don't need to remember the command).

Publishing a Jekyll site with Zeit Now

Once I'm happy with a newsletter edition, I simply redeploy the website using Zeit's Now deployments to my littoralline subdomain. To do that, all I do is commit to Github. Let me repeat: to publish, I just commit to Github. That's because I have a now webhook set for the Github repository. The Now Github app simply reads my now.json config and automatically does it's thing whenever I push a commit.

This tiny piece of magic removes the forgetfully manual process of running now && now alias from the project root in my terminal and strips another layer of friction from publishing. And this is what allows me to write directly in Github.

And that's a wrap

So that's how I publish a newsletter while always retaining ownership of my writing. It's a both a showcase of web tools and chance to play with them in context to see when they work, and when they don't.

While this may sound counter-intuitive, it's also helped me think deeply about what my intent is when writing. As I progressed with this project, I came to an important realisation: any reduction in the publishing process went directly into more time writing. With this self-contained markdown-based publishing system, I can now happily keep my excuses for not writing to plain old procrastination.