Why Markdown
This post describes our reasons for using the markup language Markdown for documentation.
Context and problem statement
Writing, either for communication or making documents, is a fundamental component of any human activity. In technical writing, it includes documents like instructions, agreements, how-to guides, or explanations. What tools we use to write documentation can have a significant impact on how we write, how we collaborate, and how we share information. Following from our principles, we want open source tools that integrate well with other tools we use. For writing documentation, the tools we’ll use to write text are called “markup languages”. Markup languages are systems for writing plain text in a structured way that dictates how it will be displayed. However, there are many different markup languages to choose from, and we need to decide which one to use. The question then becomes:
Which markup language should we use as the basis for writing all types of documentation across Seedcase activities?
Decision drivers
Aside from our principles, additional drivers are to choose a markup language that is:
- Familiar to a wide range of people.
- Popular and well-established.
- Easy to learn and use.
- Plain-text based.
- Able to produce output in multiple formats.
Considered options
While HTML and LaTeX are popular and well-established markup languages, their main disadvantage is that they cannot output to different formats. For example, they can’t convert to each other’s formats, from HTML to LaTeX or vice versa. So we don’t consider them. The two options that fit our drivers are:
Markdown
Markdown, also commonly referred to as CommonMark, is a lightweight markup language with plain text formatting syntax. It is designed so it can be converted to HTML and many other formats. Markdown is often used to format README files, to write messages in online discussion forums, and to create rich text using a plain text editor.
Benefits
- It is by far the most popular markup language used by the widest range of people, not just developers.
- Integrated in nearly all major platforms, like GitHub, WordPress, Stack Exchange, and many communication tools like Slack and Discord.
- Has the massive advantage of having a powerful format converter called Pandoc.
- Many tools and libraries that use and support it, such as R Markdown, Jupyter Notebooks, and Quarto.
- It is very easy to use and learn, with a simple syntax that is intuitive and easy to remember. Even non-technical people can start using it within minutes.
Drawbacks
- There are many different versions of Markdown, though there are strong efforts to standardize it onto CommonMark.
- Because of it’s ease of use, there are some more powerful features that are not implemented in the original Markdown syntax, so extensions are needed to use features that may be needed in some cases. For instance, they can’t handle special formatting around text like a “callout” block often used on websites or in books to draw attention to a tip or important piece of information.
reStructuredText
reStructuredText is a format used for writing technical documentation, it’s popularly is largely due to it being the default format for documentation in Python projects and packages. Like Markdown, it is plain text and fairly simple to use.
Benefits
- Because it is the default for Python documentation, its use and support is widely available in the Python community.
- It is more powerful than Markdown, with more features built in mainly because it was designed with technical writing in mind.
Drawbacks
- Not nearly as widely used as Markdown.
- Is a bit more difficult to learn and to read, at least relative to Markdown.
- Because Markdown is the core to Pandoc, Pandoc can’t convert many of its features into the other formats that don’t overlap with Markdown, like those found in reStructuredText.
Decision outcome
We decided on Markdown because it is the most popular and widely used markup language, it is easy to learn and use, and it has a powerful format converter in Pandoc. We also use Quarto for creating websites and other output, which is built on top of Pandoc’s Markdown. Through Quarto we have access to many powerful features that make up for Markdown’s less powerful features, such as the previously mentioned “callout” blocks or creating multi-column page layouts.
Consequences
- We don’t foresee any major consequences to this decision.