Org-mode trumps markdown.

Why org-mode should atleast be accepted as an alternative to markdown.

What started this?

As an Emacs user I prefer using org mode wherever I can. However due to the org-spec being massively extensive it is quite hard to find implementations that apply all of it features. GitHub and GitLab have partial support but beyond that our text editors and other tools have basically no support.

I want to possibly change this since not only org-mode more extensive it also has only 1 "flavour" or variant. Unlike markdown, which I'm pretty GFM - GitHub Flavoured Markdown is the most popular variant.

I want to bring more attention to org-mode which is often overlooked in the favour of markdown. Not that markdown is any easier, but because it has caught more traction.

Before you continue, it might be worth having a look at what exactly org-mode is through their documentation/website.

Why you should use it

If you are a developer, org-mode is an invaluable. It allows for a lot of functionality to be done quickly and easily through org files. This might include timesheets, project management, time tracking and a lot more.

This means that as long as your team can use org-mode files, they can easily integrate into your system without having to use external software. Comes with the added benefit that everything is git tracked.

You want visualisations for progress. Use graphviz or even svg-tag-mode for quick visualisations. Compared to markdown, which not only has different opinions on how every feature can be implemented, but also limited export support makes it look like a loser when compared org-mode.

org-babel and org-tangle

One of my favourite use cases for org-mode is the fact that you can do literate programing with it very easily. Want a jupyter notebook style experience, you got it (with a lot more language support). I typically use this to learn new languages and to have code examples for data visualisation, since its a lot easier to change parameters and execute the code block.

You can use org-tangle to tangle code blocks in your org file to specific files. For example, I can have a code block which might defining a Dockerfile and I can have the code block update the Dockerfile for me. This also allows me to split up the file into multiple code blocks allowing for detailed explanations of each part of code/file.

You can find an example of this in my emacs config. The README.org is the file I modify from which it creates my configuration file called config.el.

Consistency

Unlike markdown which has various different implementations depending on the platform that you use it on, org-mode is really consistent. Now since its feature set its certainly massive and daunting. It might be worth it to have atleast an org-mode light version matching atleast all the features of markdown.

Pandoc

Org-mode comes with lots of export options inluding html, odt and latex to name a few. This means that having your document in the format you want is much more likely and hassle free when compared to markdown.

Heck I write all my papers and reports in org-mode then exporting it to latex/latex pdfs. You can check out how I do that here.

Concluding thoughts

If you haven't already, have a read through what org-mode is and give it a fair shot. The best experience you get for org-mode is on Emacs. I want to change this to make it more accessible so more people use it.

Check the org-mode documentation.

This was inspired by this article.