To Use or Not Use Markdown (md)

Introduction

Markdown is a light in line text formatting language designed for use in text editors. As such, Markdown has suffered form some limitations, ambiguities, and lack of standardization over its history.

The concept is a good one, and there are many positive features. It is the actual need/usage that has created some variations in the Markdown language that some find frustrating, and has led to some serious interoperability issues.

Historical of Markdown

Martkdown is the child of earlier plain text formatting languages that have existed since as early as 1987. Markdown was originally released in 2004. The goals was an easy use/read text formatting without being distracting or looking overly complex.

Markdown saw rapid adoption. However it also saw rapid divergence. This divergence was mainly driven by the demand for additional features beyond the what was included in the initial release. The fact that there was no universally accepted standard did not help either.

Starting in 2012, there where attempts at standardization. This actually led to multiple versions, one of which is known as CommonMark. In 2016 two standards, RFC 7763 and RFC 7764, were published that affected markdown.

Generally major sites that make extensive use of Markdown share core features, but also implement variation based on site specific needs. For example; Github Markdown, Markdown Extra, and LiaScript.

Markdown Limitations

While most standard Markdown works across sites, specific Markdown is not guaranteed to work across all programs that reorganize the language. This has made implementation of import/export filters for more complex programs, like Libre office or Microsoft Office, problematic to implement.

As of this writing there is no official import/export wizards in most major office program suits for Makrdown. However this has not stopped the Open Source Community from jumping in to fill the gap. Programs like Pandoc can be used to convert Markdown files to other formats like HTML or DocX, which can be imported into most office program suits. There are also a few plugins for office suits that can work with markdown.

However, because of variations in Markdown, do not expect anything beyond core features to work with any degree of accuracy in the results.

Markdown Core (stuff that should always work)

Below are a few examples of some basic Markdown text formatting that can be considered part of the core. These should always work when translating document formats. This is not meant to be a comprehensive list. You will need to refer to what your application recognizes.

Please refer to one of the Markdown Quick Reference or cheat sheets available on line (Markdown Cheat Sheet for example).

Headings: adding a number of Hash Mark and a space converts following text text to a heading. There is no closing tag. One to six hash marks can be used for headings H1 to H6. For example;

# This is a H1 Test

## This is a H2 Test

#### This is a H4 Test

Bold Italic Underline: Changing text is done by markup on either side. For example;

Example Use Case

This is a quick look at a sample use case I am working though now. The Obsidian application lets you use markdown in its various pages for note taking. Since Obsidian is available on almost every platform, I can sync the various pages through NextCloud. Nextcloud has its own MarkDown editor addon that can be installed. Meaning that I can also view my documentation directly in Next Cloud.

The only challenge, is when I want to convert a document into an office suit format. I need to use a program like Pandoc, as I can not simply copy and paste without redoing all the formatting, and there is no import filter.

Conclusion

Markdown can be convenient, depending on your use case. Because it is all text files, they are very small and light weight. Markdown does not suffer form some of the weird formatting issues that we see in a lot of office suits. However it is far from standard, and converting it to a standard is still a bit complex at this point in time.