At EmacsConf21, I announced a new standard for a lightweight markup language: Orgdown.

As with every new standard, you need to think carefully before you launch something like this.

xkcd comic "Standards" (Creative Commons Attribution-NonCommercial 2.5 License; https://xkcd.com/927)

Therefore, I’m going to explain my motivation on this new standard here.

You can find a short version of this article in form of a twelve minute video I presented at the EmacsConf21.

Issue: One Term for Two Different Things

Unfortunately, the term "Org-mode" refers to two different things. On the one hand side, it refers to an Elisp implementation of a software extension for the GNU/Emacs platform. On the other hand, it refers to a lightweight markup language similar to Markdown, AsciiDoc, Wikitext or reStructuredText.

I do like both.

I’m using the Org-mode implementation on GNU/Emacs for a decade and I’ve blogged about my PIM workflows here on this site. Frequent readers might know my Using Org-mode Features (UOMF) series where I try to bridge the gap between Org-mode as a tool and its application in everyday’s workflows for users.

Independent of this, I do like the design of Org-mode markup. This is why I wrote Org Mode Is One of the Most Reasonable Markup Languages to Use for Text back in 2017. To my surprise, that article gained much of an audience, keeping it in my top ten blog article list ever since with respect of access numbers.

However, there were many misunderstandings in the aftermath of my article. In many online discussions, people did not seem to be able to differ between the Elisp code and the design of the markup language. The point I was trying to make is that Org-mode does make much sense outside of GNU/Emacs. Within emails, for personal notes in any text-based setting, as a markup for web-forums and source code repositories, for all sorts of non-Emacs-centric workflows.

Issue: Missing Publicity of Existing Org-Mode Usage Outside of GNU/Emacs

After I have pointed out my main points why I do think that Org-mode is superior to other lightweight markup languages, I now have to do about the issue of mixing up implementation and markup. My intention is not specific to users of GNU/Emacs. I really do believe that people who will never open up GNU/Emacs should think of adapting Org-mode as a markup language for text.

Of course, when somebody who is moving from being a markup novice to somebody who wants to make his/her life as smooth as possible, tool-support for writing Org-mode text is something that is highly recommended. With "tool support", I refer to things like collapse and expand (outlining), syntax highlighting, (keyboard) commands for quickly inserting new elements such as headings, support for jumping to (internal) link destinations, and so forth.

At this point, I want to emphasize that there are many tools out there that offer support for Org-mode syntax. It’s not GNU/Emacs or nothing. You’ve got the choice already.

Issue: Level of Org-mode Support

One of the issues within the discussions was that users of GNU/Emacs tend to mock users of other tools because Org-mode within GNU/Emacs has been and probably will be ahead of anything else feature-wise and usability-wise in my opinion.

While tool-support is a must-have for advanced users in my point of view, it is - and should be! - purely optional.

People tend to assume that any tool that support parts of Org-mode syntax needs to get as similar to the GNU/Emacs implementation of Org-mode. In my opinion, this is not necessary for most use-cases.

When you do compare, e.g., the different flavors of Markdown with Org-mode, you will notice that Markdown has a very limited syntax. Despite the fact that Markdown does lack many handy Org-mode elements, it seems to be - by far - the dominant lightweight markup language in terms of tool-support and popularity.

From this perspective, the average user does not need most of the Org-mode elements that are missing in other languages such as Markdown. For writing simple text documents, you don’t need most advanced elements.

Unfortunately, there is no sub-set of Org-mode which reflects a certain milestone in syntax support.

Orgdown

To address all the issues mentioned above, I do think that there is demand for something that introduces a new term for the syntax. Something that is less than Org-mode but "good enough" for most use-cases of average users. A new standard where tools and users may compare features of tools.

Therefore, I propose the name Orgdown.

It can be abbreviated as OD or coolified to O↓ or even ⧬.

Orgdown Levels

Now that we do have a name, we need to define what Orgdown stands for. Orgdown is just a name for the syntax of Org-mode in contrast to any implementation.

With this alone, we would not win much so far. Therefore, I defined that Orgdown is expressed in different levels.

The first level is called Orgdown1 (or OD1 or O↓1 or ⧬1). It consists of a well-defined sub-set of Org-mode syntax elements:

• simple text formatting
• headings
• lists and checkboxes
• example, quote and src blocks
• comments
• web links
• tables (without calculations)

You can always discuss the availability of Org-mode syntax elements in this initial Orgdown level. I tried to find a compromise that should work for most people, starting with lightweight markup that is based on Org-mode.

If this Orgdown1 is not enough, we will defined extended sets of Org-mode syntax elements with Orgdown2, Orgdown3, and so forth. The higher the level, the more elements will be supported. Each level supports all the syntax elements of the previous levels and more.

OD1 Compatibility Index

The nice thing about such level definition is that you are now able to compare tool-support. Orgdown1 can be summed up with 43 specific features. Each feature can be supported in a most basic way (one point) and in an advanced way (two points). The basic support is easy to get: just don’t be confused by this syntax element. The definition of advanced support spans from simple syntax highlighting up to functionality to create or modify an element.

If you do have a specific tool at hand, you can test the 43 features, derive the two support levels for each, sum up the numbers and get an end result of maximum 86 (43 features with advanced support). By calculating the percentage with respect to this maximum number possible, you get a simple to understand Orgdown1 support percentage, the OD1 Compatibility Index. You can take a look at tools support pages like this one for Orgzly to determine the OD1 Compatibility Index of a tool.

Since Orgdown is hosted on GitLab.com, you can hand in improvements for the documentation, additional OD1 Compatibility Index and tool support pages for other tools.

Advantages so Far

I want to summarize the the advantages of Orgdown for everybody so far:

• Better Org-mode support in non-Emacs tools
• Promote the beautifully crafted Org syntax to a larger set of people
• To push better support for collaboration for Emacs and non-Emacs users using text-based documents
• Comparison for Orgdown support of different tools
• Finally: fix the irritating mixup of markup language syntax and Elisp implementation

What to Do Now?

In case you are interested in Orgdown, you can now visit the GitLab page, learn how to write Orgdown in simple to understand steps, take a look on syntax examples of Orgdown1, look for further answers in the FAQ section, look through the tools that already support Orgdown1 and probably learn how to contribute to the idea and the standard of Orgdown.

I need your help in order to make this a success story!

Promote the idea, add tools, write more parsers or improve existing ones, use the term Orgdown1 to label tool properties, spread the idea by promoting Orgdown as a separate term compared to Org-mode and its mixed-up definition with the Org-mode ELISP implementation.

If Orgdown really resonates with you, you can add a formal specification to the GitLab project. I guess that some of the existing formal definitions of Org-mode already do qualify for Orgdown1 by stripping down to the few things Orgdown1 is concentrating on.

You can create a Language Server Protocol specific for Orgdown1 which would multiply the possibilities for adapting Orgdown1 in all kinds of editors.

I do do find the idea intruiging that Orgdown1 is a perfect markup candidate for the Gemini project. That would be a linked web of plain Orgdown1 files that form a parallel Internet without advertisements, malware, bloated web pages, concentrating on the essential value of information in form of simple text files and links. While this exceeds the basic idea of Orgdown by far, I would love to see this happen some day.

In the meantime, let’s kick-start Orgdown with Orgdown1 and spread the brilliant markup design of Org-mode using Orgdown as a well-defined standard.

Backlinks

• 2021-11-30 Irreal on Orgdown