Apr 17, 2023 8 min read File Formats

A Deeper Look into Markdown: Its Purpose and Limitations

Exploring the benefits and limitations of Markdown.

Unstructured Text

In 2004 John Gruber (with a lot of help from Aaron Swartz) created Markdown to address the need for a simple, easy-to-read, and easy-to-write plain text format that could be converted to HTML. Gruber states in his blog:

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Gruber also wanted Markdown to be a human-readable markup language that focused on the content itself rather than the presentation or formatting. Markdown was designed to allow users to write text that would be easily readable in its raw form (while also providing basic formatting when rendered to HTML). Gruber states,

The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions.

At its core, Markdown syntax is a form of codified text. It employs a set of symbols and syntax rules to represent formatting and structure within a plain text document. For example:

# Heading H1
* Bullet point
**Emphasis**
[Link text](https://www.example.com)

Adding structural information like this in a plain text document has sometimes led people to refer to Markdown as "structured text." Although "structured text" has a somewhat technical definition, the term can be misleading for laypeople. What is essential to recognize is that Markdown often falls short in providing the necessary semantic richness and hierarchical representation for many use cases.

Tables, for example, look pretty awful and are finicky to create beyond the simplest of examples:

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Row 1-1  | Row 1-2  | Row 1-3  |
| Row 2-1  | Row 2-2  | Row 2-3  |

To overcome the limitations Markdown requires any formatting not supported by its syntax to be created in HTML or a hybrid of HTML and Markdown. A nested table, for example, might look like this:

| Column 1 | Column 2                      |
| -------- | ----------------------------- |
| Row 1-1  | <table><tr><td>Nested 1-1</td><td>Nested 1-2</td></tr><tr><td>Nested 2-1</td><td>Nested 2-2</td></tr></table> |
| Row 2-1  | Row 2-2                       |

Despite its initial design and limited intent, Markdown has experienced far wider implementation than originally intended. At inception the target users were early web folks who had limited tools for creating simple content blocks on the web, today, however, it is mainly used by developers. It's popularity amongst developers has also lead to Markdown being implemented by developers for use cases where it might not be the most suitable solution.

In this article, we will take a closer look at the drawbacks of Markdown and why it might not be the best choice for all but a limited set of use cases.

We will break down these limitations into two use cases 1) as a human-readable format that allows users to easily write and understand 'structured' content in plain text, and 2) as a source for rendering content to other formats, such as HTML.

Limitations of using Markdown as a structured plain text format

There are limitations that arise when using Markdown even for this 'simple' purpose.

a. Inconsistent Implementations: There are numerous variations of Markdown, each with its own syntax. While this inconsistency might not pose a significant problem for human readers, as they can adapt to minor changes when reading Markdown documents in plain text and understand their structural intent, it is more challenging for machines to handle such inconsistencies. This issue mainly arises when rendering Markdown into other formats, rather than affecting human readability (see next section). Additionally, when working with multiple systems employing different Markdown syntax, users may frequently need to consult the Markdown documentation for that particular implementation while creating content. This process can interrupt the 'flow' of the writing process. Supporting a 'free flow' is one of Markdown's original design goals ("makes writing entries so much easier and fun" - Aaron Swartz), and the need to look up syntax documentation can be a drawback for users who seek a smooth writing experience.

b. Limited Formatting: Markdown's simplicity, while a strength in some cases, can also be a limitation when it comes to more advanced formatting needs. Markdown supports only basic formatting options such as bold, italic, lists, and headings. For users who require more formatting beyond the very basic, Markdown's capabilities will prove insufficient. As shown in the nested table example above, writing Markdown can soon become messy and it can be very irritating to do correctly.

c. Not an Intuitive Syntax for new/non-technical users: Markdown's syntax is not always intuitive to new or non-technical users. This can result in a learning curve for those who are new to the language, as well as difficulties remembering the correct syntax for more infrequent users.

d. Cognitive Drag when Reading: Some elements of Markdown's syntax may be unclear when reading, potentially leading to confusion for users even when they are familiar with the specific type of Markdown being used and it is applied correctly. For instance, the use of asterisks (*) for both bold and italic text may introduce ambiguity during reading or writing. This is a trite but illustrative example:

The quick *brown fox* **jumps** *over* the lazy **dog**

e. Challenges in Reading Long Texts: Markdown's minimalistic approach can pose difficulties when it comes to reading lengthy documents. The absence of varying font sizes and styles for headings, paragraphs, and other structural elements means that Markdown doesn't provide easily distinguishable visual cues about the content's organization and hierarchy.

Limitations of using Markdown to render to another format

While Markdown can be converted to other formats, especially HTML (as was the original intent), this process introduces its own set of challenges:

a. Limited Formatting: Markdown was designed for simplicity, which consequently means that it lacks some advanced formatting options. While it is possible to incorporate HTML for more complex formatting (eg. nested tables) into a Markdown document, doing so makes the content pretty unreadable and defeats the purpose of using Markdown for its simplicity for both reading and writing.

b . Limited support for rich media elements, like video: Markdown was designed to be simple and human-readable, focusing primarily on text formatting. As a result, it doesn't natively support embedding rich media elements like video. Due to this limitation, users cannot be sure if the syntax is correct until the document is rendered (which also defeats Grubers' original design aim to easily know if a text is correct before it was rendered). To address this issue, some Markdown systems employ graphical user interfaces for adding video to a Markdown document. This workaround highlights the inherent limitation in the Markdown paradigm when it comes to accommodating more complex content types. It illustrates that the paradigm itself is inadequate for modern content requirements.

c. Absense of Standardization: Markdown faces challenges due to the lack of an official specification, resulting in inconsistencies between parsers. While the CommonMark project seeks to address this issue, it has not yet achieved universal acceptance as a standard. This inconsistency poses a real problem, as the results may vary depending on the type of Markdown used and the parser employed, leading to unexpected outcomes.

d. Difficulty in styling / dynamically manipulating: When rendering to HTML Markdown does not provide a straightforward way to assign HTML classes or ids to content elements, which can make it challenging to apply custom CSS styles or JavaScript manipulations when rendering the content.

e. Real-Time Rendering Issues: When using a side-by-side renderer or inline rendering approach, where the content is re-rendered with every keystroke, Markdown can present some challenges. In such cases, the content might initially be interpreted as one semantic feature and rendered accordingly, but with subsequent keystrokes, the meaning changes and a new type of format needs to be rendered. This can lead to considerable visual fluctuations in the content as you type, which can be disconcerting for the user.

Good Uses of Markdown

Markdown can be an excellent choice for various applications where simplicity, ease of use, and readability are crucial factors. Its lightweight nature makes it ideal for quick content creation, documentation, and note-taking, among other uses. It is also a useful format when the production environment does not support other formatting methods (eg. a command line interface). In these scenarios, Markdown's strengths are evident, and its limitations become less of a concern. Here are some examples of situations where Markdown is a suitable choice:

Developer workflows: Markdown is commonly used for README files and inline code documentation by developers. Its' compatibility with version control systems like Git makes collaboration and version tracking effortless. In other words, Markdown is a a great tool for developers as it suits their workflow.
Developer friendly syntax: Developers, accustomed to writing raw syntax, find Markdown's simplicity appealing. Its straightforward nature allows them to create clear and concise instructions with ease.
Formatting from the command line: For users (mostly developers) working in command-line interfaces, Markdown offers a simple way to create formatted text without the need for dedicated text editors or cumbersome graphical user interfaces. This capability is particularly useful for developers and system administrators who frequently work in terminal environments and require a lightweight method to create structured content.
Formatting in form-based environments: In situations where users need to input formatted text into web forms, text chat, or text fields with limited formatting options, Markdown serves as a quick and efficient solution to add a little more structure to the content.
Formatting in notepads: Markdown is well-suited for note-taking in various settings, from personal notes to meeting minutes and class lectures. Its plain text nature allows for easy editing and organization, while its simple formatting options provide enough structure to make the notes easily understandable.

It's crucial to recognize that the first three use cases are primarily aimed at developers. Beyond these scenarios, the options become somewhat limited. Within developer-centric contexts, Markdown stands out as a convenient, user-friendly, and efficient solution. For non-developer use cases, Markdown remains a valuable tool for users who prioritize speed and clarity in creating simple, short-form content, or when the tools in use do not offer alternative formatting choices. Nevertheless, these latter cases are relatively narrow in scope, leading to the question: Why should non-developers opt for Markdown?

Where Markdown should not be used

There are many more scenarios where Markdown should not be used. The following are 4 very high level examples:

Moderately complex to complex documents: For documents with elaborate structures, multiple sections, or intricate content organization, Markdown's plain text formatting is not sufficient to effectively convey the structure and relationships between various elements.
Moderately complex to complex web content: When it comes to web content that demands a higher level of structural complexity, such as nested sections, multiple columns, non-textual content, or content that needs to be dynamically generated or manipulated, Markdown is not the right choice.
Publishing: For creating visually rich and beautifully designed documents, such as magazines, brochures, or books, Markdown falls short in providing the necessary styling and layout capabilities unless the user is very technical. In this case, using dedicated publishing software with powerful markup options is a better choice.
Moderately complex to complex web design: When designing intricate web pages that require advanced styling, interactivity, or multimedia content, Markdown's limited formatting options do not make it a good candidate.

In these cases, opting for alternative markup languages, tools, or software that provides more advanced features and flexibility will prove to be a better fit.

Conclusion

While Markdown is an effective and user-friendly option for basic text formatting, especially for developers working in a command-line environment, it also has drawbacks that render it unsuitable for most applications outside of this scope. Generally however, its' inconsistent implementations, syntax ambiguity, non-intuitive syntax, limited styling options, absence of standardization, and unsuitability for complex documents all contribute to it's limited utility across all scenarios.