Nerdy Blogging: Publishing Tools and Workflow for Developers

“Have some system going for producing content”

That has been sitting on my todo list app since May 5th 2019. It has also been nagging at the back of my mind, constantly getting pushed down the priority list in favour of more urgent and reactionary tasks. The nice and easy low hanging fruits.

So almost two months later, a plan got cancelled and I got an afternoon freed up. Decided to go all in. Trying out different things, different options, to sort out how I should blog, once and for all.

Ten hours later, I have finally arrived at a writing and publishing workflow I’m happy with.
I settled on three final solutions: self hosted WordPress, Medium, and Markdown.

Who is this for

You’ll find it useful if you’re looking to blog while:

  1. Having everything under version control.
  2. Having a local content “seed” aka “source code” which gets “deployed” everywhere, instead of starting a draft on the cloud.
  3. Having the least amount of GUI work. More CLI and automation.
  4. Having an easy and reliable formatting (blog in Markdown)
  5. Publishing primarily on the blog, then syndicating to Medium, for SEO purpose and reading experience. I still prefer people reading my content in Medium than my blog. It’s just not as pretty although I have picked the best theme I can find so far. Might need to tinker with the CSS eventually. Medium’s reading experience is hands down still the best out there. Ghost is close runner up.
  6. Taking advantage of Medium’s built-in audience / platform.
  7. Having a way to keep the text on the different platforms as consistent as possible with each other, with minimal work.

TL;DR

  1. Learn Markdown. MacDown’s tutorial is straight to the point.
  2. Set up self hosted WordPress
  3. Use markpress
  4. Set up git to track your *.md
  5. Use Medium WP Plugin

If this sounds like something you’d like to replicate but the TL;DR doesn’t make sense yet, read on!

A bit of background

I have been keeping a personal commitment to practice writing and publish more content. So far it has not been fun.

Resistance, procrastination, endless rabbit holes, mental constipation, juggling tasks, and clearing mental RAM.

Anyone who have attempted to pick up blogging knows how difficult it is to maintain that habit and keep a consistent posting schedule.

It’s probably not as bad as a writer’s block in professional sense, but getting ideas out of our heads are generally hard.

Sometimes it comes down to having no ideas. Sometimes it’s about having no angle. Most of the time it’s because a lack of a clear system and smooth process in place.

First let’s break down the writing and publishing process into a couple of stages:

  1. Capturing and collecting ideas / topics. This includes researching.
  2. Drafting
    1. Dumping
    2. Outlining
    3. Editing
  3. Publishing
  4. Distribution / cross posting / content strategy (Medium, Twitter, Facebook, Instagram, newsletter, podcast, and so on??)

My theory is that if I had a clear system to support each stage, the whole process would be as smooth and effortless as possible from external standpoint.

At that point, I would only need to kick into gear the internal game, to sit down and come face to face with the dark abyss of Procrastination and Resistance.

Anyway.

When I decided to start thinking about the points of friction that might be preventing me from publishing more, it immediately became obvious that there are just too many steps to actually get to the point where I can start writing. And to make it worse, there are also quite many steps to getting it published.

Open Evernote, choose an idea / draft, continue research, finalise the draft, getting the text to the blog’s CMS, getting the formatting right, cross posting to Medium, and so on.

And there’s this unsettling feeling of not having an easy way to keep the writing synchronised across the different places it now lives. I don’t know which version is the most updated one, and no way to track and observe how the thought process has evolved with time.

If I updated my draft, I need to manually update the blog, then update the cross-posted. And do all the formatting shebang again.

I need a change tracking system and a reliable way to format and keep everything synchronised.
Then there’s the adjacent decision to be made around content strategy. When and what to post to blog, when to tweet, when to share to Facebook, when to repackage as podcast, when to share as Instagram caption…..

Paralysing.

Argh. I probably only have 30 mins till the next activity… I’ll just go check what’s in the fridge.

The context switching is too costly. I like the way Steven Kotler described it: We need to edit out the transition in between tasks.

As per the stages in the writing and publishing process I laid out earlier, I’ll only cover the Drafting, Publishing, and part of the Distribution stages for now because those are the parts that involve the most friction and can be supported with tools.

Will add / describe the rest of the stage some time when I get to it. Let me know which one you’re interested to know more about.

This is what I end up with

A. Tools

Drafting, Publishing, and Distribution

  • Self hosted WordPress
  • markpress, a command line tool to create and publish Markdown post for WordPress. This tool also allows you to also update post without touching / going to the CMS.
  • MacDown, an open source Markdown editor for macOS
  • Medium WP Plugin, to cross post to Medium directly from WordPress
  • Local repo to track the *md’s
  • (optional) Cloud-based repo to sync to. Backup backup backup. I use github.
  • Easy Table of Contents WP Plugin, to add ToCs to the posts. Unrelated to the publishing workflow, just loving the readability boost.

A couple of Markdown editors for other OS:

Tools I said goodbye to:

  • Evernote
  • Notion
  • Ghost

(see “What I have tried” below for details on why I dropped this from the Drafting, Publishing, and Distribution stage)

Capturing / Ideating

Tools I have tinkered with so far. Been moving data and notes around and running iterations across the board.

  • txt files (the most bulletproof way. indentation is where it’s at)
  • Evernote (too linear, still clipped most of articles, as I have an active yearly subscription to the Premium plan)
  • Trello (finding it too elaborate. same with asana and workflowy)
  • Google Docs (purely for the ability to create ToCs and the change tracking. if Evernote ever supports these, I am dropping this for good)
  • Google spreadsheet (using it mostly as a habit tracker and breaking down ideas from a couple of angles)
  • Notion (trying to get ramped up on this. looks super powerful and flexible)
  • gingkoapp.com (mindmapping on steroid. I can see myself getting hooked on this some day down the line, it just haven’t happened yet)

B. Steps

Drafting, Publishing, and Distribution

Set up all the tools. Then start writing:

  1. Draft locally (create Markdown files with markpress, keep the *.md in a local repo, synced to cloud)
  2. Publish to WordPress using Markpress
  3. Cross post to Medium directly from WordPress using the Medium WP Plugin
  4. Edit .md, update post via markpress, replicate the changes to Medium (still a manual process but much easily and reliably done using the git diff available to you now)

This is essentially the same with how some people blog in HTML / static blogs. I just find WordPress still provides the most solid set of feature out of the box. The static sites options are still uncomparable or the tradeoff is not sufficient for me to justify fully adopting.


Well that’s basically it.

Following are just all the different options and methods I have experimented with.

Nothing below is really important to know if you’re just trying to set up the same workflow. But it might be useful to understand what the different options are out there, why I am not happy with any of them, and how I end up with the above.

In case you’re curious, read on.

What I have tried

Drafting, Publishing, and Distribution

Evernote -> WordPress (manual) -> Medium (manual)

Draft in Evernote, copy pasted the plain text to WordPress Editor, do extra edits to make sure it’s formatted alright, published it, manually imported to Medium from the Import Page, edit on Medium so it looks good.

The problem with this approach is I always end up with different versions in the draft, WordPress, and Medium. And this annoys the hell out of me, because there is really no single source of truth and easy way to synchronise the text to all places when I change it.

Google Docs -> WordPress (manual) -> Medium (manual)

Draft in Google Docs. I liked that I can track all the revision changes and I can create outlines with headings and stuff (Evernote is too linear).

But this still involves all the manual copy pasting and entails the same problem of text inconsistencies across platforms.

Notion (manual) -> Markdown -> repo -> WordPress (manual) -> Medium (manual)

Draft in Notion, manually export to Markdown, copy the .md to local repo, commit to github, manually copy paste the Markdown text to WordPress Editor (with Jetpack’s Markdown support enabled), then manually imported to Medium from the Import Page, then finally edit on Medium so it looks good.

The only advantage is I save time fiddling with the formatting on WordPress CMS. Who doesn’t love Markdown?? I always end up with better looking articles.

More or less the same pain of copy pasting and inconsistency.

There is still also no easy / programmatic way to get the Markdown out of Notion (API still in progress?). So that’s already a big friction. I need to click the Export menu, select Markdown, download the zip file, extract, get the .md file, put it in my local repo, start editing there (so, any changes to the draft is not reflected back to Notion, which is ugh)

Ghost -> nope.

Set up Ghost. Dropped it because apparently:

  1. it doesn’t offer any easy way of posting programmatically without logging into the CMS
  2. the front end site doesn’t even support search?? Sure the site does look pretty out of the box but this is kinda a deal breaker for me.

It was fun though getting it set up on my VPS. Reminds me of the good ol days of web development and deployments. https://medium.com/@hamxiaoz/why-i-moved-from-ghost-to-jekyll-and-github-dad59515bee0

Markdown -> WordPress (via email) -> Medium (manual)

Publishing Markdown to WordPress via email. I should say I am impressed with how flexible it is. I can add shortcodes in the email body to set the post title, permalink, categories, publish status, delay, excerpts, and I can directly email the blog post in Markdown (even though the formatting acts a bit funny at times).

This cuts down the manual copy pasting to WordPress Editor.

But, being a fussy reader that I am, I still don’t feel comfortable publishing something directly from email without making sure all the formatting looks OK before publishing.

So I still need to log into the CMS, review, publish and then I still need to manually import to Medium.

And it’s only to publish but not edit. So once it’s published, I cannot update the post programmatically. I need to edit them on the CMS.

So, not good enough, but I was quite happy to settle for this workflow if I had to.

Other tools

I haven’t tried any other writing apps like Bear, Ulysses, Scrivener, etc because my main painpoint is the manual work with the actual publishing logistics. I don’t have that much issue with the writing process itself.

Final thoughts

It’s a bit shocking how complicated blogging could be.

To be exact, getting your ideas and words out there.

Getting the idea out of our heads is already hard. Once we managed to get that done, we still need to deal with these BS friction around getting the text published and distributed?

How many different steps, components, tools, platforms, options, dependencies, integration gaps, file formats, APIs, are in the picture.

Argh interoperability !

Just to illustrate, here are some options / questions / tangent I looked into during the process:

  • Possibly using static site generation options / stack like Jekyll, Netlify, Github Pages, Hugo, GatsbyJS
  • How to easily publish from Notion -> WP -> Medium
  • How to crosspost from Ghost to Medium
  • How to post to Ghost via email / without touching the CMS
  • How to get Markdown out of Notion (I quite love the writing experience)
  • How to blog with Notion https://blog.kowalczyk.info/article/a8cf04d756ec4963905960822b004440/powering-a-blog-with-notion-and-netlify.html
  • How to export Markdown from Google Docs / Evernote
  • How to convert from HTML to Markdown https://domchristie.github.io/turndown/
  • Tinkered with githooks for some sort of continuous deployment, e.g. committing a change on the .md file would trigger the updates on the blog and Medium / other syndication targets. Fortunately I haven’t tinkered too much into this because the Medium WP Plugin works OK for now.
  • Exported HTMLs from Medium, tried to republish on Ghost
  • WordPress theme to show all the changes that has happened to a post, git diff-style.

I even went down a bit of rabbit hole with no-coding hosted solutions and suits of writing / online publishing tools like:

  • https://sheety.co/
  • https://sheetsu.com/
  • https://tobloef.com/text2mindmap/
  • https://twitter.com/gingkoapp
  • https://carrd.co/build
  • https://webflow.com/
  • https://bubble.is/
  • https://skaffolder.com/
  • https://www.squarespace.com/
  • https://svbtle.com/
  • https://tryretool.com/
  • http://tilda.cc/
  • https://www.wix.com/
  • https://lab.zeroqode.com/

Most probably I am just overcomplicating and over-engineering it, but hey don’t you wish there’s an easier interface from your brain to some platform out there? Articulating and distributing your thoughts and ideas.

If you want to post long form, you got all these frictions. If you tweet, it takes practice to distill your thoughts into 260 chars. Threading is also an art.

Online publishing can be much better.

Such interesting, much opportunity.


Also published on Medium.

Leave a Reply

Your email address will not be published. Required fields are marked *