Tools of the fad, part I: markdown

Today, I would like to say "No" to 3 things. All of them became popular sometime within the last 10–15 years, but instead of remaining in their niche use-cases where they belong, they started spreading and, like every cancer, infecting beautiful things with its unfitness. Their expanse continues to this day, and if it's not stopped, it will devour all beauty and perfection that is yet to be touched by it.

All three things on my list serve a different purpose and are different in nature. They do, however, share one thing – the goal of information organisation and presentation (which probably can be attached to any digital tool to some degree).

So, without any further ado, here they are.

Markdown

In simple words, markdown is when you're annotating your plain text document with extra characters that have standardised meaning, to have your document formatted (but not really). Yes, it's odd.

Wikipedia says that markdown is a markup language, which makes sense (in computer science), as it bestows some standardised meaning to some characters (or marks) that you add to your text, and the reader of your text, who knows markdown standard, will understand your formatting.

I know, I'm overcomplicating it. It's really much easier than that. And, ideally, like with any other programming languages, source code is for developers (who know the language), whereas, the rest of the world should see the "compiled" version, which in this case is rich text.

Markdown was invented around 2004, and based on some already standardised ways to represent basic formatting in plain text, that people of the internet used.
However, my first encounter with Markdown was through GitHub, around year 2010. And GitHub was definitely one source of Markdown's popularity, as it has integrated its slightly enriched standard into the whole platform.

It just made perfect sense!
GitHub was a storage place for source code. How would one create a nicely formatted doc with just source code?
HTML was one good standard for that. But it's a bit slow to write a lot of text with HTML tags, and it doesn't read smoothly when you read it from the source code.

But the markdown was better. Much more human-readable. Not as good as the regular rich-text, but better than any typical markup language.

Anyway, long story short: devs loved it! So much, that it started spreading like fire. Every week there was a new Markdown editor. The original standard was also "forked" into a couple of "flavours" with some subtle differences.

So, what's the problem?

My beef with this technology is not that it's great for the purpose described above where you provide your source code, and it's compiled and shows up (e.g., on GitHub's pages) as the proper rich-text. Ready for human consumption.

My beef with Markdown starts when I see it in a regular note-taking app or any other non-developer-targeted-app, where instead of proper formatting options you get your white square (plain text editor) and maybe a link to the markdown specs if the app is generous enough.

What's worse is that some apps give you the options:

• You can see only source code (so text with extra characters) – might not look pretty, but this is what it was designed for – storing formatting information in plain-text alongside the content.
• Alternatively, you can see the 2-panel editor, where on the left you write your source code and on the right you see the compiled output, and both columns scroll in a more-less synchronised way.
  The synchro is not great. Once you insert some images, which take a line in source code, but the height of the image out of the compiled version – the synchronisation is lost.
• The third option is to just see the compiled version (rich text) but in read-only mode. So if you want to edit – you have to switch to one of the above.
• Occasionally, there's also a 4th option (probably the worst) – when you see the compiled version (rich text), but when your cursor hits a piece of text that is formatted in some way, suddenly the Markdown formatting characters pop up around the block of the highlighted text, and you get to edit a block of source code sandwiched in between the blocks of rich-text (e.g., Typora).
• Some apps display the source code, but try to tweak it a little, so they show you the markdown characters slightly dimmed and format the actual content (e.g., Bear). This kind-of works, but depends on how much tweakery was involved. You know what I mean if you ever tried to edit a link in Bear (Yes, Bear shows all markdown characters, except the links. It converts links to something between rich text and markdown so that the links don't look as nice as in rich text, but are also not editable as in plain text). Bear v2 (currently in alpha) resolves most of these issues.

If the above sounds familiar, and you realised now, that you were writing code in places where you shouldn't need to, than it means that my conspiracy theory is real! ;-)

Or, more seriously – the weird fad is expanding.

Markdown is perfect for documenting code, for very basic readme pages and for some very basic wiki pages. Like in GitHub. Where everything is written by developers in their specialised code editors, designed for code.

But when I open a regular note app, or an email app or any other that wasn't targeted specifically for development usage, and I'm asked to use Markdown code to format my documents, then there's something wrong with this.

And this is where "enough is enough!".

The good, the bad, and the evil

Markdown does have some advantages over rich text, like:

• easy storage – plain text is easy to store in files, databases and anywhere else
• Portability – it doesn’t get any more portable than plain text. It can be imported by anything, sent via http protocol back and forth, and copy-pasted till oblivion.
• Easy to learn - there’s only a handful of special characters in Markdown

But there are also downsides:

• When markdown is stored as plain-text – every time it is displayed – it must be converted to rich text (or HTML). The conversion depends on the converter version, so it may happen that the dialect used to produce the content will not be compatible with one used to display it (this is probably not so bad, as most converters understand most popular dialects, but still something to be aware of).
• Storing images – plain-text can only reference external media, which must be stored separately and smartly linked to their corresponding documents (not a straightforward thing by any means).
• Images are the only media that can be referenced in markdown (so no videos, audio, or other embeds).
• Markdown – as plain-text is portable, but we still need an app to convert it to anything else than Markdown, and different apps will produce a different result (out of the same source).
• It’s easy to learn, but it still requires some learning, while a typical rich-text editor doesn’t (you just need to click some buttons, that are the same everywhere).

The important point is that markdown is not that shiny, cool toy that so many apps try to make it into. It’s a crude tool designed for behind-the-scenes development work. It flourishes there – in the development environment. It struggles everywhere else.

The take-away from this ugly debate is that things work best when they are used as designed, and not when they are forced into roles they have no place nor capacity to fulfil.

Further reading

• Interesting thread: https://twitter.com/nalband/status/1625541479295860752
• From the creator of Markdown: https://twitter.com/gruber/status/1398312745305579526