Markdown Is a Disaster: Why and What to Do Instead

This is a - hopefully qualified - rant about the use of Markdown as a Lightweight Markup Language (LML) instead of other LMLs that are more qualified to do the very same job.

I'm very well aware that Markdown is the most widely used syntax for that purpose at this moment. It's so widespread that most people do not even know that Markdown is only one LML among many.

My point is that Markdown is a bad syntax choice for LML applications. I think I have good arguments for my point. I also mention better designed LMLs that you should use instead in order to simplify your personal digital life as well as the digital life of so many others that are about to learn their main LML.

I am trying to explain everything from the basics as well. Furthermore, I try to explain everything within that context in order to address people who are not tech-savvy. If you know, e.g., what file formats are, you may skip sections, of course.

TL;DR: Among other design issues, Markdown with its zoo of different flavors has too many practical issues to deal with that better designed LMLs offer better alternatives with almost similar tool support.

In my business work, I need to work with different Markdown-based tools multiple times each day. In my personal life, I'm confronted with Markdown as well, although I'd like to keep that at a minimum for arguments mentioned in this article.

Furthermore, with my interest in PIM, one of my goals is to help people find the right tools for their jobs. I also do find some personal happiness in using good technical solutions in contrast to bad or mediocre ones.

Using Markdown-related workflows for many, many years, I do feel the pain that is related to them. In contrast to most people, I actually recognize and realize even subtle issues other people take for granted, implicitly assuming that there is no other way.

According to my experience, many Markdown alternatives do not come with the same set of disadvantages related to Markdown. Since most people have no experience with those alternatives, discussions on the Internet about the usefulness of Markdown ends up in me trying to push alternatives while other people seem to think that I want to take away their LML workflows and replace them with perhaps less suited technical workflows/solutions like text processing, word processing, complex markup languages or similar.

Some discussions I had did happen on social media platforms where I was not able to express and transfer my ideas properly due to length restrictions and necessary shortening. So I planned this article for quite some while so that I may send links to this instead of failing to transmit my arguments on micro-message platforms.

With all of my arguments written down here in full length, you are able to judge yourself if those arguments and effects also apply for your situation or not. Independent of that, you - of course - are free to continue preferring Markdown syntax. Your choice, your data, your effort, your future.

However, you might notice that some of the issues mentioned here will also affect your workflows, and little by little you might follow my rationale that Markdown isn't the best option here at all. ;-)

My final goal is that my personal Markdown exposure (decided by others) is reduced to an absolute minimum so that I might be able to replace it with much better designed syntax languages.

By using Markdown syntax to write down information, you decide on the form of this information for future (re-)use. If this choice does have some negative impact on the processing of your own data, you will feel some future limitations. If you have a large corpus of information written in some sort of Markdown, you will face more and more issues, converting it to a more appropriate format as conversion effort is raising linearly when it comes to manual checks, and so forth. If it takes ten minutes to convert a document to a different format, a thousand documents in your knowledge management would require a whole month of your full-time working hours. And the size of thousand documents is not a particularly large set of documents in a longer maintained knowledge management system.

If you agree with certain issues mentioned here, it's your own time spent on workarounds, fixes, unnecessary conversions, and so forth.

However, my most important argument is not about yourself and your own data. The most important argument relates to the majority of Markdown users: the ones who will start with learning and using an LML in future. People who are too young at the moment, people who are not even born yet.

Therefore, when I mention issues related to learning an LML syntax, you should not only think of yourself, who most likely have overcome certain syntax quirks by adapting to it. You actually should also think of all those people who need to invest their learning effort in future. Therefore, missing consistency and logic is one of my most important arguments here.

Just to make sure we're on the same page here: I do not want to take away awesome workflows that are made possible by using an LML like Markdown. I just want to mention that the very same kind of workflows are possible by using a better designed LML.

Unfortunately, some issues mentioned here do seem very subtle and minor. However, their consequences are not. With LMLs getting more and more popular and gaining wider use in tools, we really should make sure that our LML choice is a really good one. Personal feelings aside.

• What is an LMLs?
• Why are LMLs a great idea?
• How to use LMLs?
• Why the most dominant LML is a bad example
• What to use instead (for example)

I think that there is no strict definition of the term "lightweight markup" or "lightweight markup language". Therefore, I tend to stick to common sources like Wikipedia. As of 2025-05-10, the English Wikipedia article on LMLs reads:

A lightweight markup language (LML), also termed a simple or humane markup language, is a markup language with simple, unobtrusive syntax. It is designed to be easy to write using any generic text editor and easy to read in its raw form. Lightweight markup languages are used in applications where it may be necessary to read the raw document as well as the final rendered output.

I fully agree with that.

However, further down, the Wikipedia article also mentions HTML and also LaTeX without clearly stating if those are examples of lightweight markup languages or not. Just to make sure: according to my understanding here in this article, LMLs are syntax languages like the ones also mentioned in the Wikipedia article further down:

Presentation oriented languages include AsciiDoc, atx, BBCode, Creole, Crossmark, Djot, Epytext, Haml, JsonML, MakeDoc, Markdown, Org-mode, POD (Perl), reST (Python), RD (Ruby), Setext, SiSU, SPIP, Xupl, Texy!, Textile, txt2tags, UDO and Wikitext.

In my opinion, languages and syntaxes that are not LMLs: HTML, XML, (La)TeX, and similar "complex" markup languages are not that easy and simple to type.

Furthermore, I'd like to add a personal side remark related to the syntax of Org-mode: "Org-mode" refers to two different things:

1. an Elisp implementation to support working with text, like adding new headings, collapse/expand sections, …
2. an LML syntax, which is interpreted by the Elisp implementation above

This causes much irritation in many, many discussions. Therefore, I propose a different name for the syntax of Org-mode. This LML should be referred to as "Orgdown".

I have written about my motivation and more in this blog article. Therefore, be prepared that I'm using the term "Orgdown" instead of "the syntax of Org-mode" to simplify and clarify discussions here. I would urge you to follow this example to avoid such misunderstandings.

This article sometimes compares Markdown to Orgdown. This is because my personal LML preference is Orgdown. You should not assume that Orgdown is the only LML alternative to Markdown. It's just that my personal experience is dominated by this particular syntax and therefore it's easy for me to mention Orgdown examples in order to explain certain things.

The rationale of this article still holds true if you will never use Orgdown yourself, but any other LML that does not come with the downsides of Markdown.

Oh yes. So much for some name-dropping. But in case you haven't used one of those languages, you still don't know what LMLs are for and how they provide excellent services for your workflows.

No worries. I'll briefly explain the basic idea in this article: FIXXME: write and link article soon ;-)

For me, the most important properties of an LML are:

• The LML is easy to read by humans
• The LML is easy to learn by humans
• The LML is easy to type by humans (or generated by tools)
• The LML is easy to process by tools

This is very important. Therefore, let's take some time and explain them one by one.

Text-based information written in an LML should be easy to read, even by people who don't know that there are LMLs in the first place.

This is perhaps the most important criterion any LML needs to fulfill. Oversimplified, an LML is a convention on how to format text elements. If any LML is failing in this, the most fundamental purpose would be satisfied. So far, almost all LMLs I came across did fulfill this property. So does Markdown.

I want to emphasize /why/ the learnability of an LML is so important to me. Imagine the number of people who are using LMLs these days.

Got a figure?

Okay, and now imagine the number of people, who will use LMLs in future. Think about it. All the people. From now until the end of you imagine it.

Got one number as well?

I'd be surprised if you didn't come to the conclusion that the second number is much higher than the first one. If so, it's obvious that the number of people who will need to learn the conventions of the LML at hand exceeds the number of people who have been using it until now.

Let's take a different example with a more obvious learning curve at hand.

Let's say you've spent years learning how to program in a specific programming language. With this knowledge and experience, it's easy for you to accomplish basic tasks in that programming language. You don't need to think about the formal boilerplate. You don't need to think much about the syntax of the programming language anymore. You can focus on the task that needs to be solved by your source code.

The same effect exists also for users of such simple things like an LML. If an LML is badly designed, you first need to learn some things by heart, so that you do not mix up things that are not so intuitive right from the start.

However, if you're beyond that point, you must not forget that there were some things that were not that intuitive right from the start. You just have adapted to the tool. You forgot how it was when you started using this tool in the first place.

And this is exactly my point why you need to put yourself in a beginner's position if you're discussing the design of an LML. Even if it gives you the impression of being a very easy type of technology. Even if you are a person who has mastered the learning of this convention in the past, which now looks rather trivial to you.

Another aspect why the learnability is so important is when people are not in touch with a certain thing on a daily basis. When you're doing your taxes once a year, you'll probably need some directions, a bit of a help, a written workflow so that you don't forget something, you get the idea. For a tax accountant, the same task is a very trivial thing to do. She or he doesn't need those things. The task at hand is so familiar, that they are able to do that on their own.

Coming back to the topic of LMLs, this is a similar issue for people who update a Markdown document only once a year or so. They might forget how to write a heading. How an itemizing list is formatted. How a URL looks like with a description.

Therefore, the learnability is also very crucial when comparing LMLs. And this is typically an aspect where LML professionals often fail because the LML at hand is so familiar already that they forgot how it is for somebody who is using that LML for the first time.

Good LML design needs to minimize the cognitive burden of its users to an absolute minimum.

One of the original ideas for LMLs was that it should be used to manually type emails. I do think that a broad adoption of syntax conventions would be a great idea.

Since we're supposed to use an LML anywhere, it's probably illusive that you've got great tool support that helps you when inserting a new heading, extending a table, reformatting a list, and so forth.

(Exception: Emacs does provide tools support for entering text really anywhere because of its enormous flexibility and versatility, but that's another story.)

Therefore, a well designed LML needs to be easily typed by humans, even without any tool support at all.

You might want to use it in many different contexts, such as composing an email, writing a book, filling out a web browser form, and so forth.

If an LML is not optimized for easy typing, this additional manual effort will haunt you, even if you have given in and you're not aware of it anymore. ;-)

Last but not least, written information in the form of a formatted text using LMLs is often not a "write once, read by human" type of thing.

It could, but it should not be limited to that.

For example, if you do have your knowledge base written in a specific LML and you want to blog about this topic as well, it would be very helpful if you could reuse the text for this other context without unnecessary effort.

Even if you never thought of reusing your text in other contexts, it's super helpful if you keep this option available for your future self.

A typical workflow looks like that:

1. LML: You write the text yourself in the form of an LML syntax.
2. Converter/generator: You use a tool that reads your text and converts it into a desired different format.
3. End result: This could be, e.g., an HTML page for the web, a PDF file, a ODT/docx document, an epub (ebooks).

The general rule should be that a text must not be manually re-written when reused in different contexts. You would not blog the article if you can't reuse your knowledge base text. If you want to write a book, it would be inefficient not to be able to reuse your notes fragments as much as possible, if it's ready for being published that way.

Reusing information needs to be as smooth as possible.

If the design of an LML adds additional effort, it would fail for that purpose.

In the previous sections, I have summarized what basic properties any well-designed LML needs to cover.

My personal experience is that Markdown - as the most widely used LML at this moment - fails in most of those properties.

In the next sections, I want to explain how I came to this provoking conclusion.

Please do remember: I do not want to take away your LML workflows. I just think that you would be much happier when you would switch to a better LML than Markdown.

It's helpful to start with a brief overview of the early days of Markdown.

To my knowledge, this is one of the earliest public mentions of Markdown: a blog article from 2004-12-17 on Daring Fireball.

It also came with a syntax example file: https://daringfireball.net/projects/markdown/syntax.text

This definition consisted of the following syntax elements:

1. inline HTML

   • "For any markup that is not covered by Markdown's syntax, you simply use HTML itself."

2. paragraphs

3. multiple heading types

   • Setext-style headers as in:

     1st level heading
     =================
     2nd level heading
     -----------------
     

   • closed Atx-style headers (hash characters upfront and closing)

     # first level heading #
     ## 2nd level heading ##
     

   • open Atx-style headers (hash characters upfront)

     # first level heading
     ## 2nd level heading
     

4. blockquote (using > characters)

5. lists (using *, +, -, 1. + HTML)

6. code blocks (indented by ≥4 spaces or ≥1 tabs)

7. horizontal rule (using ≥3 hyphens, asterisks, or underscores)

8. web links

   • as in

     [an example](http://example.com/ "Title")
     

   • auto-links as in

     <http://example.com/>
     

9. file links as in

   [a sub directory](/subdir/)
   

10. reference-style link as in

    [an example][myid]
    [myid]: http://example.com/  "Optional Title Here"
    

    • The link URL may, optionally, be surrounded by angle brackets

    • ids are case insensitive

    • implicit links:

      [myid][]
      

11. emphasis (including intra-word emphasis)

    *em* or _em_
    **strong** or __strong__
    

12. code

    • single backticks within a paragraph
    • optional multiple backticks

13. images as in

    ![Alt text](/path/to/img.jpg "Optional title")
    

14. backslash escaping for literal characters above

That's it.

Enough for writing emails and simple text documents. I give you that.

However, when it comes to many other situations, people need more syntax elements.

And so the disaster began to develop. Some developers who were adapting early Markdown in their tools extended the syntax with additional syntax elements. One application was adding footnotes. Another one was adding internal links to headings. Another one was adding more options for working with source code. Yet another was adding other stuff.

And no one "merged" back these syntax extensions to the original source. You get the idea.

This way, we do have a set of Markdown "flavors" as they are called.

The Markdown Monster helps identify twenty four different Markdown flavors. And I would not be surprised if that number is much lower than the actual number of Markdown flavors out in the wild.

There are many tools out there - like the now-hyped Obsidian - that provide feature extensions by optional add-ons. Some of those add-ons also introduce their own special purpose syntax elements. If you want to reuse those elements in properly, you most probably would like to have this information processed as well when converting. Sadly, those proprietary syntax extensions do make the situation much worse. Therefore, by using such add-ons, you end up in some sort of lock-in situation although you've been using human-readable text. Unfortunately, most people don't get this issue until they suffer some sort of information loss.

Here is a quote from the Wikipedia article on Markdown:

The initial description of Markdown contained ambiguities and raised unanswered questions, causing implementations to both intentionally and accidentally diverge from the original version. This was addressed in 2014 when long-standing Markdown contributors released CommonMark, an unambiguous specification and test suite for Markdown.

Oh yes, there were some approaches to unifying or standardizing Markdown. Which resulted in yet another number of flavors because of universal laws.

In my daily business, those Markdown standards, such as MultiMarkdown, Markdown Extra, CommonMark do not play any particularly important role. More important here are the implicit standards set by tools like pandoc or GitHub Flavored Markdown (GFM) which is also used for GitLab.

Just to give you some idea of some syntax elements of Orgdown that were not part of the original Markdown, I copied some from this syntax overview:

• subscript/superscript
• underline text
• italic text
• verbatim text
• strike-through text
• tables
• checkboxes/in-line tasks
• meta-data (key/value) in drawers/properties
• blocks other than code blocks or inline HTML: quotations, verse, example, LaTeX, …
• comments (blocks or lines)
• heading tags
• priority markers
• task states for headings
• heading references
• time-stamps, date-stamps
• macros

You see, some of them are more than just nice to have when writing text.

With that in mind, I'm claiming that Markdown as such is a very bad LML choice:

OK, if Markdown would also fail here, it most probably would not have this prominent market position nowadays.

So let's concentrate on the other aspects here.

In many discussions, I have learned that most people that are using Markdown for a long period of time can't follow my rationale here. In my opinion, this is because they can't put themselves into the shoes of a Markdown beginner anymore. If you are still puzzled here, I recommend re-reading the "The LML Is Easy to Learn by Humans" section above.

For optimizing learnability, consistency is the key.

New users get frustrated if something behaves differently than they expect it to behave. That's no issue as long as Markdown syntax is written by humans and only read by humans. Potential issues arise long after the text has been written, when it's post-processed by a tool that interprets Markdown.

Inconsistency is an obvious handicap when something is learned for the first time. However, there is also another aspect where inconsistency is a bad thing to have: wrong retrieval of already learned knowledge.

Therefore, if something is inconsistent, it not only provides you frustration when learning something. It also provides frustration if you're trying to apply already learned knowledge, and need to remember something inconsistent instead of using your human brain and consistent LML design.

Let's discuss Markdown inconsistency with some syntax examples.

It's easy to insert a simple URL into Markdown: https://Karl-Voit.at gets translated into a clickable URL in probably all Markdown applications.

 https://Karl-Voit.at	  

As you can see, you don't need to use any special type of characters to mark a URL as such.

The tricky part comes when somebody wants to insert a URL with a description text.

In my opinion, the dominant part of this is the URL. Because you can use the URL as a simple URL as shown above. The description is purely optional.

So when you want to insert a URL with a description, you need to add some boilerplate to it. For some reason, in Markdown this boilerplate consists of different character types: parentheses as well as square brackets.

I don't know why this was considered something good when designing Markdown as the position defines what's the URL and what's the description.

Anyway, when you add a description to a URL for Markdown, you get:

 (https://Karl-Voit.at)[My webpage]	  

Oh. Or was it the other way round?

 [https://Karl-Voit.at](My webpage)	  

You'd be surprised how often I need to look this up myself when I haven't been writing Markdown for some days.

And then you realize that the logical assumption that the URL is the dominant part, and the description as an optional thing is the second element is somehow wrong in Markdown. It seems to be the case that in Markdown you should assume that there is text where an URL is added optionally. It's OK but that type of thinking conflicts with the simple URL syntax element at least in my head.

Therefore, the correct URL syntax with description in Markdown is:

 [My webpage](https://Karl-Voit.at)	  

Yes, you start with the description, and then you write the URL. You start with the square brackets, and then you use the parenthesis.

I hope you got the idea why I do think that the URL syntax in Markdown is not intuitive.

And this is not only just me. This irritating Markdown URL syntax design has become a meme already:

If you want a good laugh, try guessing how alt-text or titles are added to URLs. I guess most Markdown users will need to look this up when not written on a daily basis.

But we've got other syntax elements as well that I do have issues with.

If you're new to Markdown, I bet you were puzzled when reading section "The Origins of Markdown" when I mentioned that there are multiple different ways of writing headings.

I guess the original idea was that there were different conventions and the original authors did not want to overrule at least some of those older conventions, resulting in some flexibility when it comes to headings (only).

Therefore, all those examples are valid Markdown in its original form.

1st level heading
=================

Some text.

2nd level heading
-----------------

Some text.	  

Do I need to match the number of underlining characters to the heading line length? Yes or no?

What about the third level? I guess if you choose those heading types, you've decided that this document can't have a third level heading as long as you don't convert all headings to one of the other forms.

= first level heading =

Some text.

== 2nd level heading ==

Some text.

=== 4rd level heading ===

Some text.

[...]	  

Well, this is much better.

But what about a different number of hash-signs at the end? Therefore, the original Markdown authors defined the closing atx-style characters as purely cosmetic. So they are ignored, independently of how many characters you're using:

# first level heading ##################

Some text.

## 2nd level heading #

Some text.

### 4rd level heading

Some text.

[...]	  

Oh yes, they are useless. Therefore, you can omit them as well:

# first level heading

Some text.

## 2nd level heading

Some text.

### 4rd level heading

Some text.

[...]	  

Oh great. Then why mention those optional, useless characters at all? Bad design, I'd say. People might be intrigued to think that they need to manually count the initial characters and adapt the ending phrase accordingly. Which is wrong. Or useless. Or just bad LML design.

Either way, it has much potential to provide a frustrating experience when learning Markdown.

You may settle for one heading type and continue with your learning experience. Then you start using real-world tools that use "Markdown" (which flavor?) and you realize that the current tool at hand only supports one particular heading type of Markdown. Yes, even that is a common issue with some tools. They don't even support all syntax elements of the original Markdown definition.

Similar to the level of freedom Markdown defined for headings, it also defined multiple ways of emphasizing text:

 *foo* or _foo_ → HTML tag em
 **foo** or __foo__ → HTML tag strong	  

So do all tools need to support both?

Why not use one variant for one and the other variant for the second emphasis type? Another example where this level of freedom is a bad thing to have. A clean and consistent LML syntax design would have optimized the number of necessary characters and reduced the level of ambiguity.

Well, tables is a tricky topic here as they haven't been part of the original definition of Markdown except via inline-HTML. However, LML tables are so omnipresent that I'd like to include them here. They provide a good deal of trouble in my daily business with Markdown.

Here is a simple Markdown table:

| Column 1      | Column 2      |
| ------------- | ------------- |
| Cell 1, Row 1 | Cell 2, Row 1 |
| Cell 1, Row 2 | Cell 1, Row 2 |	  

For many use-cases this seems to be sufficient. It also has many options for aligning and so forth. Unfortunately, some table features are not possible with this table syntax as well. So I need Grid tables via pandoc as well:

+-----------------------+-----------------------+
| Column 1              | Column 2              |
+=======================+=======================+
| Cell 1, Row 1, line 1 | Cell 2, Row 1, line 1 |
| Cell 1, Row 1, line 2 | Cell 2, Row 1, line 2 |
+-----------------------+-----------------------+
| Cell 1, Row 2, line 1 | Cell 2, Row 2, line 1 |
| Cell 1, Row 2, line 2 | Cell 2, Row 2, line 2 |
+-----------------------+-----------------------+	  

I do have documents where both table types are used, depending on the table features I need.

To me, this is also an example of inconsistent Markdown design since no table (except HTML tables) were added to the original definition and therefore, multiple table syntax versions emerged.

Well, the reasons why Markdown is not easy to type overlap with the reasons why Markdown is not easy to learn. For example, I always struggle with the URL syntax (order, parenthesis type).

In my daily business, people prefer strong/bold emphasis over italics. Therefore, everything needs to be with two asterisks at the start and two asterisks at the end of the bold section. You may think that this is exaggerated, but I think that this extra effort every time could have been avoided with a better LML design.

When working with source code examples, Markdown knows the HTML tags. Furthermore, you could use triple backticks at the start and end of the code section. That's also fine with me. Sometimes, however, you need to use the third Markdown option: ≥4 leading spaces in each line. If that is necessary or not is defined by the tool/flavor at hand. In those cases, it's very tedious to add those extra characters in front of every line. Typically, Markdown editors are not very good text editors, not supporting macros, column-based editing, or multiple cursor features that simplify that task.

(Note: Although I try to strictly separate the LML syntax from tool support, I want to mention that I've never seen any Markdown editor that offers at least a fraction of Markdown tool-support that GNU Emacs delivers for orgdown. So that's not an argument for/against Markdown as a syntax, but it contributes to the frustration I do have when working with Markdown tools.)

In many discussions, the widely available tool-support for Markdown is taken as the strongest argument to embrace Markdown. Here, I consider the inability to properly reuse Markdown text in other tools as my strongest argument against Markdown. Reading this far, you may already have an idea why.

There is no single definition of Markdown. There is this zoo of Markdown flavors. Different tools are using different flavors. As I've mentioned briefly already, some tools even extend the syntax even more with optional add-ons that may introduce additional syntax elements. Otherwise, there would not be articles like 10 Useful #Obsidian Plugins That Won't Affect Your Plain Text Data.

They are highly problematic since it's almost guaranteed that whatever those syntax elements hold, they are not properly handled when converted to a more capable output format.

All in all, whatever you do have in Markdown syntax, you really need to carefully determine which syntax elements in what variant are in use before you can be sure that this can be reused in a particular situation. For all non-trivial documents, I would not like to do this tedious job.

Tools like the Markdown Monster may help with the most basic syntax elements. However, it can't help with any syntax extensions based on some add-ons you might or might not be aware of. Therefore, for many cases, even the best tool-support can't help you to avoid data loss when converting a not completely known/defined Markdown flavor variant into something else.

Depending on the tools at hand, the information, and the syntax elements used to format a text, the general promise of being able to reuse Markdown text is an illusion.

I consider this a form of lock-in effect although the text is human readable and stored in a text file, which - for many people - does seem like a contradiction. It is not, if you don't stick to "read by humans only".

I have put some thought into this. I was not able to come up with an idea that would add yet another Markdown flavor and yet another Markdown standard to the whole story. As a matter of fact, this is the reason why some Markdown flavors do exist: somebody wanting to define the (only) Markdown syntax to go with. I would not write this article if this would have turned out successfully. On the contrary. In my personal life, the Markdown flavors that are considered as a standard do play a minor role with the tools I use.

This is why I do think that for Markdown, the battle is lost. It is what it is. It might work for many people who stick to a single Markdown-based application or at least a set of Markdown-based applications whose flavors are more or less identical.

I don't say that this is not possible. However, this is far from an argument that (any) Markdown is a good candidate as a universal LML.

And this is what we should use instead: universal LMLs, which don't require additional effort when text is reused in a different tool that supports the same LML.

So what are good LML candidates that should be used instead of Markdown in order to avoid the downsides we've got with Markdown?

The good news is that there are many LMLs to choose from already. Many of them who are really great alternatives. Let's discuss this.

In my opinion, you need an LML whose initial form was sufficiently advanced for most applications without external syntax extensions or syntax flavors.

Then, you need an LML, which is:

1. Easy to read by humans
2. Easy to learn by humans
3. Easy to type by humans
4. Easy to process by tools

Already sounds familiar? ;-)

If you know any LML that fulfills those requirements way better than Markdown, go for it! You don't need my advice. You can actually stop reading this article at this point. It's too long anyway.

You can revisit the list of LMLs I mentioned in the section "What Is an LML?" above.

For the rest of this article, I provide some motivation to try out my personal LML choice: the syntax of Emacs Org-mode, which - in my opinion - should be called Orgdown.

Read this article when you want to learn why I coined a term for the syntax of Org-mode.

Yes, Orgdown is no official formal standard. However, it's a pseudo standard as the Elisp implementation of Org-mode defines how syntax elements do look like and are interpreted. And this is more than Markdown can ever expect to have.

I've written "Org Mode Syntax Is One of the Most Reasonable Markup Languages to Use for Text" already. However, it's fair to do the arguments for Orgdown according to the same requirements here as well.

• A: "I prefer Org-mode for my files."
• B: "Oh, I won't do that because I hate Emacs."

(They are probably talking about two different things.)

Because this seems to be a never ending misunderstanding, I - again - want to emphasize that we need to differentiate between tool support and LML syntax. In this case, you can use Emacs Org-mode to work with orgdown text. You can also choose a wide list of other orgdown tools to do so.

It even has enough advantages to type orgdown by hand, without any particular syntax support. At least most Markdown tools I know don't come with substantial Markdown support at all. Therefore, most people don't even know what to expect from good tool support anyway. KISS principle.

In case you actually do look for great tool support, life can't be much better than the Emacs Org-mode implementation together with the orgdown LML. Here is just a very, very, very short list of some things to expect when working with orgdown in Emacs:

• Syntax highlighting: the most obvious and, unfortunately, sometimes the only tool-support in various implementations
• Shortcut to create new items: headings, list items, table cells, …
• Moving items: headings, list items, table cells, …
• Navigation to particular spots: bookmarks, headings, keywords, footnotes, …
• Derive special views on the orgdown data like agenda/calendar, summary tables, …
• Advanced export to all relevant target file formats
• Import from all relevant source file formats
• Automatically align tables while you type

I can not stress enough how awesome working with text is when using Emacs and/or Org-mode is involved. I personally haven't seen anything comparable. You only truly understand after trying on your own for a longer period of time. You can get a short preview when you look at some Org-mode-related videos on YouTube and other video platforms:

• Prot: Emacs Org mode basics (48min)
• Nice Emacs Org-mode video about its basic features (1h32min)
• Some of my online videos are dealing with Org-mode related workflows as well.

With additional tools like pandoc, you can realize even more workflows where orgdown files are involved. I have created lots of non-Emacs tools that are using Orgdown files either as input or to generate Orgdown as output format. One example to be mentioned is this blog here. All my articles are written in Orgdown. My own static site generator (there are many of them to choose from!) generates the HTML pages you see here in one go. I don't need to differentiate between notes, tasks, projects or blog entries. It's a totally different way of working with a computer.

And now I'm again leaving the tool-support level and coming back to the LML level and explain why Orgdown is different and much better compared to Markdown - even if you don't consider any tool support at all.

Here are some examples where you can compare the source with some interpretation in order to judge for yourself how easy it is to read Orgdown even without highlighting, re-formatting, ...

• Orgdown1 example
  • Source
  • Gitlab preview
• This blog
  • Source: each page has a ¶ at the top right corner where you can take a look at the Orgdown source I wrote.
• The Org-mode home page has some non-trivial examples as well.

• The Org-mode manual has the most relevant information on Orgdown syntax elements, of course. However, it's more a reference than a tutorial.

• The Worg community page has some further resources like tutorials, deep-dives and so forth.

So judge yourself. For the most part, it doesn't differ much from standard Markdown elements. If you have mastered Markdown, you will most probably be delighted by the better design of Orgdown.

Changing habits is probably the hardest thing to do. The same holds true if you've overcome Markdown's initial obstacles, learned the syntax specifics of your tool by heart and typed a lot in one single Markdown flavor: learning a different LML does seem to be a hard job.

Learning Orgdown as your first LML should not be a hard problem, as it is well designed, doesn't come with the inconsistencies of Markdown and is easier to type, in my opinion. In my opinion, Orgdown is a very good choice for your first LML.

My personal recommendation is to put a cheatsheet beneath your computer monitor. Maybe a printout of the od1 example page does the trick for you. Maybe something from that list:

• (W)Org tutorials
• https://github.com/fniessen/refcard-org-mode

Within the first days or weeks, you will look up certain elements like order of URL and description, how to emphasize, and such. I recommend to highlight single elements you look up more frequently.

Then with time, you'll notice that you need that cheatsheet less and less so that you may put it into your drawer. That's when you overcome the majority of the learning curve for the syntax already.

For the same reasons as above, Orgdown is easier to type for humans compared to Markdown, there are fewer inconsistencies and a clever design. I think that you'll have not much to fear, as you don't need to worry about any incompatible flavor, like you have to do when typing Markdown.

This is where Orgdown shines.

I already mentioned the excellent authoring tool support when typing within Emacs Org-mode. It's the best LML environment there is - by far. Due to the fact that Orgdown as so many syntax elements for all sorts of use-cases, it's unlikely that you will ever going to be in a situation where you wish that there would be this or that in addition. After all, many (research) books, thesis, papers get written with Orgdown.

When it comes to reusing Orgdown text, you don't need to worry about flavor incompatibility. Just fire up your Org-mode export filters, a pandoc conversion command, any org-related import function in other tools and your text will turn our greatly.

As one tiny fraction of use-cases, just take a look at Orgdown-specific static web page generators on Worg.

With not having most downsides of Markdown, you will realize how awesome the LML idea is in general, when you don't have all this issues caused by the Markdown flavor hell. It's actually a totally new experience.

Wow, you've come far in this journey. This article is long because I tried to address all the different misunderstandings, misconceptions, mix-ups, ... I've experienced (too) many online discussions about this topic.

I've briefly introduced the LML idea and that it is totally independent of any particular LML syntax.

I summarized the general properties an LML should fulfill according to my understanding. This way, you can objectively discuss different approaches.

Then I summarized the aspects I dislike about the design of Markdown and the fact that there are so many different flavors you need to keep separated in your head.

I explained my point of view on why this Markdown situation got so out of hand.

Finally, I proposed switching to a different LML. One that doesn't come with all the downsides of Markdown LML.

As my personal favorite, I emphasized the fact that Orgdown is a brilliant LML candidate even if you will never ever work with the Emacs software.

According to my personal experience, the only clever thing about Markdown is its witty name. Almost everything else is done much better by other LMLs besides Markdown.

I know from experience that this is a very sensitive topic to many people. This results in religious argumentation beyond any objective rationale I tried to summarize here and some personal preference as well.

However, with this, you should be able to judge yourself if my arguments do contain some truth, my personal issues with Markdown are mirrored in your personal reality as well, all the listed Markdown downsides are no issue at all for you and all of your people you're sharing text-based documents with.

If I could not convince you at this point, it's good to have alternatives we both can choose from.

If I omitted a good argument, please don't hesitate and leave a comment below.

• Pro Markdown
  • Markdown and the Slow Fade of the Formatting Fetish + my comments on that
• Contra Markdown
  • Why You Shouldn’t Use “Markdown” for Documentation — Eric Holscher