Taking a minor break from the “ElasticSearch on K8s” series
tl;dr: I’m moving back to maintaining my own site rather than depending on Medium as a platform for technical blogging, because of various reasons. Also introducing a tool to convert from Medium to Hugo.
A tale of not making up my mind
To start with somewhat of a boast, I’ve been writing blog posts for more than a decade now, on various platforms, SaaS ones to self-hosted solutions. Most of the posts are now nowhere to be seen since I cannot seem to make up my mind about where to keep my writings. I started some serious technical blogging about five years ago. That started with using Github Pages as a hosting service using Octopress as a site generator. After a while, getting exhausted on the themeing and waiting for the next Octopress version, I switched to Medium halfway through, importing all the posts.
Now after several years, I’m moving back to Github Pages. This time I’m using Hugo as a static site generator. Although, it too has somewhat widened the scope from being a simple blog generator to a fully fledged site generator, there seems to be a consistent stream of patches and support available for enough years ahead. The theme collection is good and relatively easy to customize.
Why not Medium?
No, it’s not because of the infamous paywall Medium seem to be aggressively marketing these days. I’m not that of a serious writer. And Medium has been a good platform to expose the articles I wrote to a wider audience. This move will restrict that to one or two shares I get on Facebook. There were feedback for some of the articles I wrote from all over the world. Writing on specific topics that only a few engineers searching for ways to debug their issues on the Internet would stumble upon is not that satisfactory. The only one is a small feedback (a clap, a follow, or a comment) and that is enough to keep on writing. Those were mostly thanks to Medium’s model on exposing the articles based on tags and topics. I will miss that in the future, especially the little dopamine hit you get when a new clap appears on one of your articles.
The main motivations for moving are mostly a few small reasons that piled on for a few years of usage.
Syntax highlighting
This is a story almost every technical writer on Medium has complaints on. When I started with Medium, this was the first drawback I noticed, but I hoped it would be fixed soon. Instead what Medium offers as an alternative is using Gists, which is a pain in the ass to do so for a long time, especially for technical articles that require multiple code examples.
It’s only a matter of time before you realize Medium is not for technical writers.
Opaque way of writing
This is mostly a personal preference. Medium, being a platform, has its own markup language that ultimately gets translated to HTML. Over time, I grew tired of this really special way of writing that I had to do on this one platform. Every other place that I did writing in, seems to have adopted Markdown in some way. Medium never seemed to want to do this (other than the backtick support). It’s only a matter of time one grows tired of this and says “fuck it”!
Brand name
As I said above, being on Medium gives you a lot of perks in terms of exposure. However the payback is that you sacrifice your personal identity. There is absolutely no customization to be done for personalization in the free tier. I understand this as a way of providing unified experience for the reader (most of the customizations I have done on other platforms have ended up as nightmares in terms of readability), and I understand serious writers who can spend on building their brand on Medium will get some level of customization for them. But that’s not for me.
On Medium, your content is part of a huge collection of articles (as opposed to a single collection of articles of your blog). So you have to share the same level of impression that one gets when they read shit like “How to Take Pictures of Your Girlfriend That She Won’t Hate”. This is not for me.
Control (lack of)
With the specific way of writing, and the inability customize anything other than the content in a restricted way, the whole experience on Medium has been an increasingly frustrating one. Being a bit of a control freak, this ultimately meant going back to a self-hosted solution. This way, the content I publish will not get the same level of audience, but at least I will be in control of the process and the content. Github and Hugo provides a more natural experience for me.
Conversion
Moving means baggage. Or dragging them to a new location. This is the hardest part of the process (some believe it’s picking a theme, which isn’t a trivial one either). I spent more time on this than I’d like to admit, but for a good cause.
Thanks to Medium providing a way to export content and an existing converter that translates Medium content to Hugo specific Markdown, starting the conversion process was relatively easy. Medium provides a way to request the content you have on their platform (posts, claps, comments etc.) as an archive. This sends a zip archive to your email after a few hours that can be used to generate Markdown content.
I started with bgadrian/medium-to-hugo to convert the content. It is a great tool, but there were few aspects of it that I thought could be better. One main issue was that it was generating a folder for each Markdown file, which seemed like a cluttered way of doing things to me. I forked it and modified to suite my personal preferences and eventually ended up changing it so much that there was no way I could open a PR that would get accepted. My fork is at chamilad/medium-to-hugo if anyone is interested in that way of doing things. The download links and the usage details are all in the README. The tool is written in Go. Any kind of contribution is welcome. Also, please visit the upstream project to see if you can contribute there too.
A few notable changes are,
- HTML to Markdown conversion library used is different, using JohannesKaufmann/html-to-markdown which has a great interface to work with. I had to fork it too to get some fixes in since the upstream seems to be a bit unresponsive
- Fix self referencing links - Any links found in the articles that refer to other articles by the same author on Medium will be converted to refer to the Hugo hosted article
- Github Gists found in the articles will be converted to Markdown code blocks. I had used a lot of Gists that were better off as just code blocks.
- Convert tweets and Slideshare embeds (from the Medium’s way of embedding things) to HTML embeds
- Handle rendering bugs like formatting directives inside code blocks
New Place
My new blog will be at chamiad.github.io. I haven’t setup any commenting platform to keep things simple. You can provide feedback through Twitter when necessary.
I will not remove the content already on Medium and will probably put links to the new posts on Github. I haven’t made up my mind about yet.
Here we go! Goodbye Medium!