Organized and translated by Python Tribe (python.freelycode.com); reproduction prohibited, sharing welcome. Markdown is the most widely used lightweight markup language on the internet. For tasks like writing blogs and comments, Markdown is great. But recently people in the technical community have started using it to write documentation. Below I list some arguments against using Markdown, hoping to help you decide whether Markdown suits you. If you’re considering Markdown, I hope you’ll also look at Asciidoctor and Sphinx; I’ve found writing documentation with them to be better. People choose Markdown because it handles some basic tasks very simply. Developers choose it because GitHub supports it, even though GitHub supports 9 different markup languages, including Asciidoc and reStructuredText. But when documentation grows from a few pages into a large documentation set, Markdown quickly falls apart and becomes a burden. Here’s why that happens.
Lack of a standard Originally, Markdown was defined by the initial implementation John Gruber wrote, but its behavior was never clearly specified. As Markdown became more and more popular, more and more sites began supporting Markdown implementations, and since those sites were written in other languages, even more Markdown implementations appeared. All these implementations differ slightly, but not in a way that’s acceptable. For example, some implementations require a leading space, while others don’t:
There are also some small issues that make Markdown hard to port between different sites and versions. Over the past few years, Commonmark has developed into a standardized Markdown. That’s good and should solve many problems, but nobody has adopted it.
Style The main reason Markdown lacks adoption is that it has kept changing over the years. At first, Markdown had very limited features, and whenever a popular tool implemented Markdown, it came with its own particular style. Sounds good, right? The problem is that every tool formed a different style, and even tools implementing similar tasks had different syntax. For example, in Markdown Extra code blocks look like this:
This applies the python class to the output HTML block. However, the same thing in GitHub Flavored Markdown looks like this:
This applies syntax highlighting to the actual rendered HTML output. Similar concept, different syntax, but both are Markdown.
Lack of extensibility Other markup languages can be extended to provide the features you need. They have mechanisms in their syntax for adding new features without violating the original specification. For example, reStructuredText has inline and block-level markup:
You can learn more about the concepts of rfc, class, and contents. As a developer using rST or Asciidoctor, I can add new markup in a simple, pluggable way. I don’t have to change how the language is parsed, and I can share those new features with other users through the standard extension mechanism. Porting those features between different versions isn’t something you can do with Markdown. Note: CommonMark is developing a syntax for extensibility, but it hasn’t been implemented yet.
Lack of semantics Although many people have added lots of extensions, none of them is semantic enough. This means you can’t write Class or Warning, only plain text. So many people embed HTML directly into Markdown:
In reStructuredText, you can write it as:
This displays properly as a Warning in HTML, PDF, or any output format you create. Semantic markup lets you separate the text you write completely from the way it is displayed. A lack of semantics causes problems, for these reasons:
- Markdown now depends on specific CSS classes in the display, which means writers have to think about how pages are designed.
- Content can no longer be ported to other output formats (PDF and so on).
- Converting to other markup tools and page designs becomes more difficult.
Note: My blog post Semantic Meaning in Authoring Documentation has a more detailed discussion of semantics.
Lock-in and lack of portability The variety of styles and the lack of semantics lead to lock-in. Once you’ve created a large set of Markdown documents, it’s very hard to migrate them to another tool, even if that tool claims to support Markdown! A documentation set made up of custom HTML classes and oddly styled extensions won’t work anywhere except in the current tool and design. At the same time, you can’t easily migrate Markdown to other markup languages (Asciidoc or RST), because Pandoc and other conversion tools don’t support your style of extensions. Many people choose Markdown because they think they can migrate to other tools or other markup languages later. Markdown is absolutely the lowest common denominator, and unless the documentation set is small enough, everything you need isn’t in the basic syntax. Any meaningful documentation needs extensions, and once you use Markdown’s various styles of extensions, you lose all the portability advantages.
Conclusion I think CommonMark is a big step forward, and if it were used more widely and gained support for extensions, I’d wholeheartedly recommend it as the way to solve this problem. I can’t endorse Markdown’s current ecosystem, and I think it largely prevents people from making documentation better. I hope we can start advancing a more standardized collection of languages, including CommonMark, reStructuredText, and Asciidoc, with full support for them across the tool suites we use. At present, Sphinx and Asciidoctor are good alternatives. They have more extensions built into the language itself and include more complete tooling for building today’s documentation. Markdown is more of a concept than an implementation. It usually means “a set of mutually incompatible extensions on top of a language that looks like Markdown.” When creating large documentation sets, it’s clearly not the right tool. Disclosure: A product I work on, Read the Docs, is based on Sphinx, so my views may be biased.
Original English article: http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/ Translator: Chris
