Org-mode support

Posted on: 17.12.2023 - @Moskas

This will be a short post to vent some of my frustration about weird org-mode support on GitHub.

Small introduction

As you may or may not know, I am an Emacs user, and I write notes in org-mode. Even drafts for the blog are first in an org-mode file.

I prefer using it over markdown wherever possible, mainly for consistency and additional perks of using Emacs, like code block evaluation, etc.

I am currently using two online git repository solutions: GitHub and Gitea/Forgejo (in the form of codeberg.org). Both of these solutions support org-mode, kind of.

While Gitea/Forgejo support is very good, and the format in my Emacs buffer and the format of README.org in the online repository look basically the same, sadly the same thing can't be said about GitHub.

GitHub...

GitHub has its own markdown flavor and documentation on its own wiki. Basic writing and formatting syntax wiki page.

There is no such thing for org-mode, and many elements of org-mode don't render correctly, like:

• Checkboxes They aren't rendered like markdown checkboxes; rather, they are represented as plain text [ ].
• Header flags If you want to create a header like * TODO List, you expect it to at least render in the correct way, right? Wrong. The TODO part of the header disappears completely.
• Org-mode priority flags Org-mode has its own formatting for specifying the importance of a given task: [#A] [#B] [#C]. I know GitHub Markdown doesn't have such flags, so they might as well be removed completely too, but they aren't.

So you can imagine how broken some org-mode files can look when pushed to github as the main README.org.