Dealing with Code on Medium

Yesterday my frustration meter with Medium-s code editing finally hit the limit. The problem has been described in multiple places. Just to describe why I’m annoyed with it.

First of all, there are quite a few ways of adding code to a Medium.com, however all of them are frustrating or lacking in some way.

Code Blocks

First of all the integrated code blocks. In essence they look like this:

package main
func main() {
    println("Hello World")
}

At least in theory. When you use tabs, this happens:

package main
func main() {
 println("Hello World")
}

When you copy-paste from Visual Studio Code, this happens:

package main
func main() {
println("Hello World")
}

When you edit, it will behave in all sorts of weird ways. I don’t really mind the no-syntax-highlighting, but the font-size could be smaller. Anytime I tried to use them then editing any indentation, deleting and undo made it break.

Gist

You can also link to gist.github.com, which looks much better:

However, the problem is when you try to add multiple code snippets. My most recent post had 12 different code paragraphs. When you put multiple files into a single gist you cannot link them to individually… so you end up with a mess like this:

Of course you can create separate gists, but manually making 12 of them is pretty annoying.

Medium API

Medium does support creating new posts via an API, where you can provide a markdown or html file. However the issue is that you cannot later update that post. There’s even an issue posted with no feedback from Medium.

I understand the complications. Since Medium tracks the highlights that people have made, updating the content is not as trivial as updating the html. However it definitely isn’t that complicated either since structural diffing does work.

Screenshots

The least frustrating approach I’ve found was using code screenshots. Obviously, this is very annoying for readers.

Conclusion

All in all, the general experience of sharing posts on Medium, is pretty good. The citing, highlighting and getting feedback part is really great. Interacting with comments is somewhat annoying and the stats aren’t that great. However the code part is a great deal frustrating.

None of the solutions I previously mentioned were usable, so I ended up writing my own “solution”.

loov/gistsnip

The idea was to take an existing working code, add some annotations and then the tool will automatically create gists based on the comments.

For example from the following code it will create automatically two gists:

func main() {
    //gistsnip:start:loop
    for i := 0; i < 100; i++ {
        fmt.Println(i)
    }
    //gistsnip:end:loop

    //gistsnip:start:example
    fmt.Println("hello world")
    //gistsnip:end:example
}

Of course, when you modify your code, it will update the existing gists rather than creating new ones. The folder where you run gistsnip contains a file called .gistsnip, which contains necessary metadata for it.

You can see a how your medium post looks like in:

Server and a Database

And the code repository for the medium post:

egonelbre/db-demo

This should allow me to continue working on Medium, until I find a better solution. The migration is going to be annoying, but probably worthwhile.