Why is Markdown so popular?

It puzzles me how hypes emerge among nerds. My childhood’s flamewars were about Amiga versus Atari or later VIM versus Emacs. But any of these systems worked well. Today I wanted to start working on a good looking cheat sheet. Now it’s the end of the day I spent researching and I still don’t have a solution. Inkscape is a very good tool for the design and beauty in cheat sheets. But it cannot remember styles so it’s a pain to manage non-trivial amounts of text. At least I found a way to syntax-highlight Ruby code using Pygments – but that extension was very user-unfriendly and I couldn’t imagine using that more than a couple of times in the document. Scribus is a different beast. At least it has styles and makes it easier to format text but there is no syntax highlighting and managing styles isn’t exactly user-friendly. LibreOffice is slug-slow and does not support syntax highlighting either. So I thought I’d rather use a markup language, publish the cheat sheet in HTML and perhaps pimp it with a bit of jQuery-flavored Javascript.

(However it’s ridiculous how some people keep insisting that WYSIWYG is dead. Yeah right.)

So inevitably I started searching the lazyweb for the best markup language. In 2006 I was part of the Ubuntu documentation team for a while and helped with the DocBook/XML-based workflow to generate documentation. We used to write that in plain VIM and it sucked badly to maintain the XML sources but there were no serious tools to manage DocBook back then. A few years later I used to write documentation in Restructured Text (RST) format. Although I often mistyped the syntax it worked pretty well. Sphinx provided a good framework with automatic references to my Python code.

Then out of curiosity (and the death of my favority Python-based “Pylons” web framework) I started to learn Ruby. Sphinx did not really work for Ruby code so I needed something else. And as I was working with GitHub I had to learn Markdown syntax. It was very basic and seemed to be a thin layer of markup upon HTML. Markdown looked similar to Restructured Text and I wondered why someone reinvented the wheel. But only today I start to realize how confusing Markdown has become. As Markdown was very limited someone came up with Markdown Extended and added semantics. GitHub found that neither Markdown nor Markdown Extended suited their needs to they use “GitHub flavored Markdown”. So did StackOverflow. Three different kinds of Markdown? That can’t be good.

Next I was looking for a half-decent editor. Some nerds insisted that Sublime Text is the only good editor because it has extensive Markdown support. I don’t mean to bash Sublime Text – I have bought it myself. But it’s not any more capable than Komodo Edit and its Markdown support is hardly better than VIM’s.

At last I found StackEdit and hoped that I had finally found a working tool to write documentation – after all its web-interface is really nice. But it can only sync to Google Drive, GitHub or Dropbox. Do I look like I put my data on a public cloud? But that wasn’t even the biggest problem. That code that StackEdit creates is yet again some different flavor of Markdown. Well, they claim it’s Markdown but it isn’t. Try to export it and run it through a Markdown converter – half of it will just look broken. I liked it’s [TOC] command to create a table of contents – a feature I sadly miss in Markdown. No, it’s not working either with Markdown nor Markdown Extended converters. Nor will your documentation work offline if you use all their features because they load CSS and JavaScript directly from their website. I admire what they have created but it’s not a pure Markdown editor.

At the end of the day I learned that there are several flavors of Markdown that are all differently limited. What puzzles me is that the majority of programmers seems to have jumped on the Markdown bandwagon and some claim it’s the best markup language for documentation because the majority of nerds use it nowadays. I’m sorry – I don’t recognize why I should rely on it.

[At least I don’t feel totally left alone with my frustration.]

10 thoughts on “Why is Markdown so popular?

  • 2014-02-19 at 20:25

    I cannot speak for all developers, but I suspect a LOT of this is because they all started using it to create their own HTML content, so when they decided to allow users to write markup, Markdown was the logical choice since they were already using it on their backend.

    The other problem is what else would you use? Creole is really the only other choice and it’s just not sitting there in an easy to use package like Markdown is. reStructuredText could be a realistic choice, but I suspect that all the anti-Python people won’t use it because well … it’s basically part of Python.

  • 2014-03-03 at 15:42

    I’m pretty ignornant of the different markup languages out there, but I’ve used DocBook (found it useful, but a lot of work) and have begun familiarizing myself with GitHub’s Markdown flavor. I’ve also used near daily Redmine for several years have become pretty familiar with Textile because of that. I found some of the formatting choices to be pretty odd coming from my experience working with MediaWiki, but now I think nothing of them. Most of the popular programming languages also have support for Textile.

    I haven’t tried to generate other content from Textile text files directly, but if you haven’t come across it yet it might be worth looking into it.


  • 2014-03-07 at 12:16

    StackEdit (I’m the developer) has multiple purposes. One of them is to publish converted markdown (HTML) in user’s blog, so one doesn’t have to care about Markdown conversion and different flavors. StackEdit offers different kind of flavors (Mardown Extra, GFM, LaTeX mathematical expressions…) but all of them can be customized or disabled in StackEdit’s settings (see Extensions tab) so you can go back to classic markdown.
    About offline editing, StackEdit uses HTML5 application cache, so that JS/CSS resources are not downloaded if you have already run the application in your browser. basically, in any browser, stackedit.io is available offline after loading for the first time. Try it!

  • 2015-01-03 at 12:15

    I agree. I have no idea what markdown hype is all about. Vi on iterm worked a ton better than any of the editors – I tried just about all of them. But at the end of the day just did it in Word and then rewrote in markdown just so everyone can read in GitHub wiki.
    Everything that editors did to make life easier is replaced by type this character and that and let human do the work of a machine. Makes no sense whatsoever

  • 2015-03-01 at 21:01

    I have no idea why markdown even exists. It was supposed to create a bridge between writers and coders. It fails in every way. The content that writers write still has to turn into html to appear on the web. Writers don’t want to learn to code. Any code. At all. They want to write. If something needs to be a headline, they don’t want to write little symbols that get in the way of reading their content. They simply want to designate it as the headline. Markdown just complicates everything to do with writing creatively. And as a creative writer I have no use for anything that gets in my way.

  • 2015-06-17 at 10:36

    I like Markdown and find it excellent. I’m not a programmer, but deal with a lot of text. Over the years, my text has been in MS Word. Apple’s Pages and RTF files. All of these are no good for long term storage, nor very flexible. Markdown allows me to use plain text files that can be easily converted into just about any format I need. But, the content remains plain text. Here’s the important part. Markdown enables the plain text to retain a formatting. This is really important. This means I can sync it with Dropbox and access all of my writing on any device. Markdown makes my formatted text platform agnostic. This is a massive step forward. It reduces document bulk caused by proprietary formats and gives maximum flexibility whilst ensuring that my text is secure and usable for years to come.

    I find OS’s tend not to search the content of Word files stored in older versions of Word. Apple’s pages is a joke and even it’s own programme will not open files stored in older versions. Plain text removes all this hassle and markdown enable the formatting not to be lost.

    This is why I love markdown!

  • 2016-02-23 at 20:56

    I use Docbook and I have used Markdown quite a bit. I prefer docbook because my Emacs is setup with my custom macros. I have written my own scripts for syntax highlighting for HTML. I use Pygments. For DbLaTeX output I have minted package and for Epub not much requires to be done just use different stylesheets and compress the output which is handled in Makefile.

    Markdown is good for simple tasks not for like a thick book. I use Markdown for simpler tasks like one page notes etc.

  • 2016-03-23 at 23:37

    I work for a big corp. They use Word and Sharepoint for document creation and management (yes they are Stoners (stone-agers)). I’ll soon be pitching GitBook Enterprise as a solution for them.

    You could throw as many Vim/Emacs users as you want at an enterprise and none of them would stick. I have not found a document solution that competes with the dumb-easy document creation/version control/access that GitBook provides…

  • 2017-10-12 at 10:23

    I completely agree with you !!! The Markdown concept is really nice but its implementations are much too incomplete and inconsistent. In the end of the day, either you learn to live with those problems, or you end up implementing your own lightweight markup system (Pendown) to fill those usability gaps. In my case I chose the second option. Obviously that meant converting all my Markdown files to the new syntax, but at least that was worth the effort. Personally I type my text directly inside a HTML file with any plain text editor inside the “xmp” tags, and I press F5 to see the result in the browser. If I want to print the document, I add “~~~” page breaks and that’s it. And if I like the result I generate a standalone HTML file from the same text. Not very sophisticated, but at least this gets the job done, and bye by the silly Markdown inconsistencies with images, lists, etc…


Leave a Reply

Your email address will not be published. Required fields are marked *

By continuing to use the site, you agree to the use of cookies. more information

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.