Why Markdown Is Not My Favourite Language (2012) | Hacker News Reader

Why Markdown Is Not My Favourite Language (2012)

wilfred.me.uk

114 pointspmoriarty97 comments

Part of the problem is that people don't really grok the point of Markdown. There's a reason it doesn't support tables, or a syntax for making the kind of language used in a code snippet. The point of Markdown is to mimic the conventions of ASCII-text email, both to make writing it as natural as possible, and to make Markdown pleasant to read in both ASCII and HTML.

If you want something more featureful than Markdown, the problem isn't Markdown; it's that you're using the wrong tool for the job.

org-mode in emacs supports tables, and it's ASCII-based.

Here's an example, displayed exactly how you would see it marked up in org-mode syntax in emacs:

  |-----+-------|
  | Key | Value |
  |-----+-------|
  |  00 | foo   |
  |  01 | bar   |
  |-----+-------|

org-mode can export to HTML, and many other formats.

Org-mode is a beast. A fantastic beast, much like Emacs itself. You dive in, but there's always more to learn. Some things may be for you and some things don't. Everyone should give it a try.

A little known fact, even among most org-users: Github can render org-mode files to HTML directly if checked into a repo, thus you can write your README files as org-files.

Shameless example: https://github.com/josteink/csharp-mode/blob/master/README.o...

This alone was enough to make me drop Markdown as my go-to format for semi-formatted text-files.

A subtle killer feature here is org-babel. You can embed proper code in your text-files and have your editor (at least Emacs) understand them as such. Which makes it excellent for writing technical documentation for projects where code is involved.

> A little known fact, even among most org-users: Github can render > org-mode files to HTML directly if checked into a repo, thus you can > write your README files as org-files.

I recently stumbled across the tidbit. The Ruby library Github uses to generate it though isn't 100% though. If you want to use org-mode properties for style customization of html output your SOL.

Original project:

https://github.com/bdewey/org-ruby

  Currently, you cannot do much to customize the conversion. The
  supplied textile conversion is optimized for extracting “content”
  from the orgfile as opposed to “metadata.”

It does say that developement has moved to:

https://github.com/wallyqs/org-ruby

Which has no such note, but doesn't say anything about supporting it.

>Github can render org-mode files to HTML directly if checked into a repo

They also support ASCIIDoc, ReST, MediaWiki markup, Creole, etc.

See: https://github.com/github/markup

I really wish that other services would be like this. You enter text in a few popular markup languages and not one specific language.

org-mode tables are great, but they're only easy to type because org-mode does the dynamic resizing and border drawing for you. Markdown is supposed to be simple to type in any plain text editor.

You can still have simpler table syntax that's nice to read but easier to maintain. For my own markup language (http://breuleux.net/quaint_demo/) I implemented this syntax:

    + Name    + Occupation
    | Alice   | Accountant
    | Bob     | Baker
    | Charles | Car salesman

Headers are easier to make and the last column does not require a trailing marker. It's still some work to align columns other than the last, but that's not a requirement and I'd still much rather have a non-aligned ASCII table than nothing at all.

Yeah, the alignment of columns is a big issue. If you have 100 rows, and add another with a cell that is longer than any other cell in that column, you've got to either edit 100 rows or live with a much harder to read table.

Or use a text editor that supports region editing. I agree with you, but this isn't a complete failing of that syntax.

What happens when I add a new value that's "much longer"?

At first,

  |-----+-------|
  | Key | Value |
  |-----+-------|
  |  00 | foo   |
  |  01 | bar   |
  |-----+-------|

becomes

  |-----+-------|
  | Key | Value |
  |-----+-------|
  |  00 | foo   |
  |  01 | bar   |
  |  02 | much longer |
  |-----+-------|

but as soon as I hit TAB, it turns in to:

  |-----+-------------|
  | Key | Value       |
  |-----+-------------|
  |  00 | foo         |
  |  01 | bar         |
  |  02 | much longer |
  |-----+-------------|

There's probably a way to make org-mode dynamically resize tables as you type, without requiring the use of TAB, but I'm not sure if that's always desirable.

M-q also resizes the table; I mention this because M-q is universally "reflow whatever is under my cursor."

OK. I think where I'm going is that for anyone who doesn't use emacs org-mode, ASCII tables are a major PITA to edit. I didn't know if emacs used a different underlying syntax (that markdown could borrow), but it doesn't.

Well, anything is a major PITA for someone who doesn't use emacs…

More seriously, ASCII tables are always a major pain to edit, without the proper tools (like emacs—and I'd not be at all surprised if there's something for vim and/or Sublime Text too). That's no reason to avoid them; they are useful.

I never create tables in HTML any more. If I ever want an HTML table, I create it in org-mode and export it. It's just so much faster to create what you want.

>There's a reason it doesn't support tables

I don't see how the inclusion of tables violates the ascii-like readability of markdown. Github has implemented a table syntax that is natural to read/write and makes it easy to include tables in your document. Example: https://github.com/Defconbots/2015_target/blob/master/hw/boa...

I built a tool to convert your CSV tables to Markdown table format: https://github.com/mplewis/csvtomd

Natural to write? This:

    |Name            |Quantity|Part Number         |Distributor|
    |:--------------:|:------:|:------------------:|:---------:|
    |BAT1, BAT2, BAT3|3       |534-082             |Mouser     |

is not "natural to write"

of course is natural to write, given the proper emacs plugin.

Yep, and there's also exists plugin like that for vim. Although it doesn't exactly comply to github's column alignment markup.

https://github.com/dhruvasagar/vim-table-mode

To add to that, Markdown was created to scratch one person's itch with no real desire to support a wider community. It was put online and other people liked it and modified it, but the original site doesn't have any of this.

Is that a correct history of Markdown? It certainly seems to have been designed to be easily readable and writable for laypeople.

AFAICT Markdown codified a lot of best practices from ASCII emails and forums of years past (e.g. 20th century's). What looks like careful design may be as well a result of a long evolution.

This feels like a post-facto explanation that gives way too much credit to Gruber as a language designer.

I find it hard to assume that Markdown is extremely well thought-through considering the fact that we didn't even get a grammar for the language, just an implementation that would be considered super broken in any other language.

This implies that Markdown is designed as a language, which would have things like grammars and can be reasoned about with proofs and the lambda calculas etc.

Instead, Markdown should be thought of as a convention. A convention that allows for automated translation of ascii text into html. Further, instead of thinking of Markdown as designed think of it as evolved.

In the case of an evolved convention, we wouldn't expect formalism or even long term design. What we would expect and what Markdown is extremely good at is usefulness, high levels of adoption and ease of change. Which we do see. If your needs require formalism, or complex html features then Markdown is not the right tool for you.

If it's intended to be interpreted by computers, what's the point in avoiding precision? All a fuzzy specification does is make it probable that those interpretations will be mutually inconsistent and/or unintuitive and problematic and/or prone to crashes and security failures.

> If it's intended to be interpreted by computers, what's the point in avoiding precision?

Because markdown is for humans first and foremost, not computers. It can't be clearer than that.

How could it be for humans any more or less than any other language which is designed primarily to be written by humans and then interpreted by computers?

Markdown is designed primarily for humans in both those tasks. Interpretability by computers is second to interpretability by people.

that is disingenuous considering that Markdown the spec is offered alongside markdown.pl.

If it's intended for humans first and foremost, then why offer the transpiler? After all, it already looks like ASCII e-mail. The overriding directive is human-readability, not unparsability (which do not go hand in hand).

Actually the markdown page on his site mentions exactly that as markdown's intention.

> 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. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

Worth adding that it's said that since 2004, when archive.org first noticed the page.

"Markdown is two things: (1) a plain text formatting syntax; and (2) a software tool… that converts the plain text formatting to HTML. […] 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… the single biggest source of inspiration for Markdown’s syntax is the format of plain text email."

http://daringfireball.net/projects/markdown/

I don't think it's far-fetched to say what tptacek did since it's dang close to what Gruber has always said about Markdown. Note that phrasing: it's not a language, it's a "plain text formatting syntax."

What parts of Markdown are closer to conventions of ASCII-text email than the equivalent Creole? Two spaces at the end of a line? List renumbering?

I am in a position where I know a little of Markdown and a little of reStructuredText. Considering the little time I have and I have to learn a language I would want to learn something that is extensible. Isn't that a valid reasoning?

Markdown. Is. Not. A. Language.

Markdown was never intended to have any particular standardized syntax -- it was simply a script that took a common syntax used for a long time when formatting plain text and convert it to formatted HTML. The attempts to standardize it are misguided, as there is absolutely no need for that -- there are numerous existing standards for precisely that, starting with ReST which follows a pretty similar syntax (in fact, any attempt to standardize Markdown will end up with something very similar, as it has to solve all the same issues).

>Markdown was never intended to have any particular standardized syntax

At some point it was intended to be standardized or else we wouldn't have a standardized version of markdown syntax.

But there isn't a standardised version of Markdown. There's John Gruber's original syntax, and there are dozens if not hundreds of variants.

When some enterprising people declared they had created "Standard Markdown" the original author got very upset: http://blog.codinghorror.com/standard-markdown-is-now-common...

Markdown does not have standards, it's just a collection of base formatting conventions a lot of people like.

> There's John Gruber's original syntax, and there are dozens if not hundreds of variants.

All of the variants exist due to the many undefined edge cases in the original syntax, and not further development by Gruber to 'officially' resolve ambiguities. Some of them became their own standards (e.g. MultiMarkdown) others just became undocumented behaviours of certain Markdown parsers and/or generators when handling edge-cases with no defined 'official' way to handle them.

> When some enterprising people declared they had created "Standard Markdown" the original author got very upset:

This seems to have more to do with the name being 'Standard Markdown' and seeing it as an attempt to usurp 'ownership' of the 'Markdown' name. Said author didn't flip out over variants like MultiMarkdown.

> Markdown does not have standards, it's just a collection of base formatting conventions a lot of people like.

The efforts of people to standardize it are efforts to resolve this idea, and make Markdown more formal.

Since when does something have to have a standard syntax to be a language? I mean, if you said "it's not a programming language" because it's not really executable in even a limited sense, I'd get that, but to say it's not a language -- a means of communicating information -- is just absurd. There's no standard BASIC, and there are almost certainly hundreds if not thousands of variants of it, but no one would say it's not a language because of that.

No, I meant a "markup language". And you're right -- Markdown is not "a means of communicating information"; it's a script that converts one form of information to another.

Markdown isn't a means of communicating information?

Only partially. Technically, it is simply a conversion mechanism that converts one form of formatted text (the "Markdown" syntax) to another (HTML). Now, since the original format has never been formally specified, instead only being loosely defined by years of practice in email and Usenet messages, Gruber had to specify some constraints for his script to follow, but this is far from a standard.

If we assume there is a standard, it's not called "Markdown", as Gruber heavily opposes that. On the other hand I'll agree that, if we extend the meaning of the term "Markdown" to cover a stantard like CommonMark, in that case yes, Markdown is a means of communicating relatively minor elements of information -- such as emphasis or lists -- as any other markup language.

Newer markdown stuff here: http://commonmark.org/

Gruber did not want them to use the word markdown so they changed to commonmark. And they are trying to standardize with a spec. I would also consider it along with your other alternatives.

CommonMark doesn't really fix much given it's not so much a proper spec as a set of tests, and most big users (who wrote the spec!) aren't actually using CommonMark anyway.

> most big users (who wrote the spec!) aren't actually using CommonMark anyway.

I'd say this is partially due to inertial. Reddit and StackExchange for example, have communities that have been writing in their variants of Markdown for years at this point.

I don't like any of them. Markdown, ReST, various wiki/forum dialects of "simplified" text formatting. They are all as complicated if not more complicated than just writing HTML. They all have a bunch of rules and special cases. I'd rather just write in HTML which I already know.

I don't understand the motivation for any of these "alternative" markup formats. Normal non-technical people want Word (or at least, some kind of WYSIWYG text entry). I've been on projects where they tried to get non-developers to use ReST and it was an abject disaster. The tech writers revolted and refused to use it. So then a developer had to be sidelined to convert their Word documents to ReST so that we could produce HTML.

Yeah HTML is not perfect, but neither is any of these other markup languages. If you like one, fine, but don't wonder why none of them has really caught on outside of small niches of highly technical people.

> They are all as complicated if not more complicated than just writing HTML. They all have a bunch of rules and special cases. I'd rather just write in HTML which I already know.

I find that Markdown is significantly easier/faster to write than HTML and, more importantly, easier to read in its un-rendered form. To me (and presumably lots of other people, given Markdown's ubiquity) it's well worth learning the relatively small syntax.

Edit: Here's a quick comparison with a README.md from one of my projects:

Rendered: https://github.com/cespare/reflex/blob/master/README.md

Markdown: https://raw.githubusercontent.com/cespare/reflex/master/READ...

HTML: https://gist.githubusercontent.com/cespare/ad6c41aa28583cac8...

Three things I notice from this example:

- The verbosity of an XML syntax with HTML is annoying, particularly the need for closing tags. <code>xyz</code stands out as particularly verbose (compared with `xyz`).

- Having to escape certain characters like & makes this HTML sample harder to read (this is more of a problem with technical/code documents).

- Automatic linkification prevents stuttering: <a href="http://example.com">http://example.com</a>

I haven't seen it used outside of Rails apps, but have you ever tried Slim? I understand there's a similar tool for Node.js called Jade.

http://slim-lang.com/

  table
    tr
      th Col1 Header!
      th Col2 Header!
    tr
      td Col1 Value...
      td Col2 Value...

Renders to HTML.

Slim/Jade/HAML etc are templating languages, they're not designed for writing text at all - they're almost the opposite of markdown et all.

I wouldn't say they're the opposite of Markdown, but that's not really the point I was getting at anyway. The poster I was replying to was saying that two of his issues with using HTML to write documents were the verbosity and the escaping. Slim solves those two issues.

Ah, apologies, point taken. Note that most of that style of templating language include markdown filters as well - so you drop :markdown in, then just write a block of text, works really well.

So much this.

Normal non-technical people understand that you click a bold 'B' and you get bold text, you click an italic 'I' and you get italic text, you click a little list icon and you get a list, and so on.

contenteditable has its quirks, sure, but modern browsers mean it's no longer the brainmelt it once was. Real WYSIWYG entry is achievable and almost easy. Markdown has one great usecase (producing documents that are viewable both as plain ASCII and as 'compiled' rich text), but it's not a tool for Joe Normal.

Non-technical people learned WYSIWYG and they can learn something else too.

1. Users don't have the manual, and if they did, they wouldn't read it.

2. In fact, users can't read anything, and if they could, they wouldn't want to.

http://www.joelonsoftware.com/uibook/chapters/fog0000000062....

~10 years ago I introduced Textile markup at our student newspaper and they're still using it. Nobody complains about it. Some people write in Word first and then add the tags, but most writers just use the tags right away.

You're free to argue that these markup languages all suck, but this idea that it's impossible to get "normal people" to learn even a little bit of syntax, is preposterous – what about twitter #hashtags and @replies?

I'm a software developer, that is to say a technical person, but I don't really know HTML (well, other than a few basic tags) because, like most developers in the world, I don't do web development, and what I do know of HTML, I don't particularly like, certainly not for writing.

On the other hand, I find Markdown (or ReST) easy to learn, to write and to read.

As to being a niche, there are probably around 20M software developers in the world (probably only 10-20% of them doing web), and several times over of other kinds of technical people. So even a markup language that only targets technical people who are not web developers would be addressing a few tens of millions of people. A niche for sure, but far from a small niche. These markup formats certainly cater to many more people than, say, Ruby or Python.

I agree, I beauty of markdown is any layperson can read it while HTML in-spite being easier for web-developers is not the best tool to write documentation.

Not all markdown text is written with the intention of being converted to HTML. Pandoc can convert markdown to .pdf (via LaTeX), .doc, a slide-deck (using either LaTeX-Beamer or one the HTML presentation tools) etc.

Compared to LaTeX, markdown markup is less obtrusive: a single asterisk/double asterisk/double backtick interrupts the flow of text less than an \emph{} or \textbf{} or \textit{}. Since there's less noise, it's easier to proofread and edit the source document. [The same is true for HTML vs. markdown]

Compared to LaTeX, markdown markup is less obtrusive:

Indeed, I use pandoc for making LaTeX beamer presentations and it generally provides the goodness of Markdown and LaTeX combined. Slides can be made far more quickly than in LaTeX. E.g.

    # Some section slide

    ## Slide title

    * Bullet point one
    * Some math: $a^2 + b^2 = c^2$

At the same time, one can e.g. immediately insert fragments of TikZ using the relevant \begin{...} \end{...} block and it just works.

I've been using Textile for ages, and it's much better than Markdown for just about anything _except_ footnotes (in MultiMarkdown) and pieces with multiple references to the same URL.

In particular, Textile has great table syntax, which I use extensively in pages like http://the.taoofmac.com/space/infoviz (markup at http://the.taoofmac.com/media/infoviz/index.txt). But over the years I became so used to Markdown (largely thanks to the profusion of editor support it spawned) that I mostly gave in.

Still, Creole might be a good addition to my next CMS/Wiki: http://github.com/rcarmo/sushy (already supports Textile, Markdown and ReST).

the first wiki I wrote used textile, I added wikipedia-style links and it was about perfect. I still can't understand why markdown overtook it in popularity.

Alternatives: asciidoc.

Maps easily to docbook, and has a heap of extra features.

This. All the benefits of markdown (and similar), with a decent toolchain, version control capabilities and exporting to various formats.

And it's also relatively close to markdown (biggest change is links).

The asciidoctor project also has browser extensions for rendering which are really nice. For the lazy: http://asciidoctor.org/

Github can render asciidoc. Do they use asciidoctor.JS?

I found the lib was rather big :/

Since getting ReText, a simple Markdown editor which can export to PDF, ODT and HTML, I notice I want to make many documents in it instead of using LibreOffice. As long as it doesn't need imagery but just normal text with formatting (chapters, bullet points, perhaps code examples, etc.), it's much easier to create and keep in version control. It's super light, in a text-based format no program will ever have issues with (try the "open" docx format in LibreOffice) and when sending it to others I just attach a pdf export.

Markdown as a spec may not be nailed down 100%, but as a practical thing to use it's very handy. There are implementation differences between StackOverflow and ReText, but those are details.

Markdown and all the other Markdown-esque formats need to be consigned to the history books.

No really. It is almost 2015 and we are still typing symbols on each side of words in text boxes when we want to emphasize something. Are we cavemen?

(Following was added after initial posting)

Technology has moved on. We should no longer need to remember which combination of magic symbols we need to make a bulleted list or whatever.

There are often helpers to insert those magic symbols. That's great, but then why keep showing us the magic symbols? Do you want me to care that s represent italics? Will including this second cause this fragment to be italicized? How do you show an asterisk without it meaning intalics? Grrr...

>Are we cavemen?

Well, essentially, yes.

What do you suggest we use, then?

One of those text-entry boxes with buttons for emphasis, list items, etc.

Hacker News seems to have a weird fetish for its 'minimalist' UI ... probably because it has a higher than typical ratio of users who spend time behind a terminal, and due to some underlying belief that the lack of bells and whistles keeps the normies away. If they added a rich text editor there would probably be a riot.

But to be fair, at least markdown is a lot cleaner than bbcode.

I should probably point out before someone else does, that my own blog, hackensplat.com, is one of those very websites I'm complaining about. In my defence, its just a blogger.com hosted site and I'm using their comment system.

I want forms to either accept plain text and allow angle brackets and stars, or accept HTML and provide an interface that hides the HTML tags. We only need Markdown and their ilk for the last generation of websites (including mine) that are behind the times.

Or maybe people who write code for a living a) don't find it difficult to remember that fencing text with asterisks gives you italics and b) fencing text with asterisks is far, far faster than taking your hands off the keyboard and playing swoopy/pointy/clicky with a mouse.

There are in fact programs that don't run in the browser.

Schocking, I know. But wait, there's more! Some programs don't even use Javascript!

Your point?

His point is that your cute little text entry boxes with buttons don't work in those situations.

> It is almost 2015 and we are still typing symbols on each side of words in text boxes when we want to emphasize something.

That's called markup. It's what HTML is; it's what any plain-text format is. And it's a good thing: it's interchangeable and archiveable.

HTML is great, mostly because it actually does the job and knows its place.

Markdown and their ilk are all trying to be sorta-not-quite-HTML, but fail precisely because they are not HTML.

To me, one big issue is that you cannot use markdown to present everything, for example, one cannot use it to produce something like <pre>`d`<pre>, I mean he cannot use ``d`` to do that, right? Also you cannot write

```

```markdown

## HEADER

```

to produce a fenced code block which contains a markdown source code for code block.

Also, different markdown editor use different markdown parser. So, same source code will be rendered differently in different editor.

Can we get a (2012)?

Markdown is many different things to many people. I love Markdown, but I mean the GitHub Flavored Markdown. Using plain Markdown would be very weird for me. So discussing flaws of plain Markdown seems pointless to me since I don't use it due to a much better variant being available.

Does anyone else prefer txt2tags [1]? It also works.

[1] http://txt2tags.org/features.html

I do; of all the lightweight markup languages, it seems like only txt2tags has a sane representation of HTML links. [1] http://en.wikipedia.org/wiki/Lightweight_markup_language#Lin...

Ugh, that's the syntax of TVTropes. What a mess, I never know if the title comes before or after the link, and whether to wrap with 1 or 2 square braces.

[ @JetSpiegel ] Challenge:

(1) write an 8-page (or more) document with 32 (or more) hyperlinks in it in both txt2tags and any other format.

(2) Print out the plain-ASCII source files.

(3) Wait until you forget the whole text of what you've written.

(4) Re-read it (both versions) somewhere without access to a computer/phone/tablet. (e.g. the bathroom)

You will understand why txt2tags makes more sense:

(1) Less markup [i.e. fewer characters] than Markdown, Textile/Texy, AFT, reST

(2) Text-first, unlike AsciiDoc, MediaWiki, PmWiki, Org-Mode, BBCode. Text-first leads to better/easier readability of source ASCII IM(NSH)O.

(3) Unlike POD, has a syntax for named links.

2 years later, how's creole doing, anyone know? Has it developed (in any sense of the word) much in two years?

Yes, Markdown is really bad. I really wonder why it's so much more popular than Creole, Textile etc.

Revisit your starting assumption?

It looks like the famous Bjarne Stroustroup quote holds true for markup languages as well as programming languages.

"There are only two kinds of languages: the ones people complain about and the ones nobody uses."

This article is great. I really never understood the preference of Markdown over rST. Also, little do people know that github supports rst https://github.com/github/markup

But looks like Creole as well, which i didn't know :)

As far as I can tell the only advantage rST has over markdown is that it's better defined. I rarely find that I prefer the rST syntax to markdown.

I frequently write documentation with sphinx, over 30 pages long. rST is a blessing for me. Markdown doesn't even get near.

It's fine for some 20 line README on github but that's about it.

I'm with you there in that I couldn't imagine writing 30 pages of markdown. For something like extensive documentation, I could imagine rST winning, particularly since there is a standard syntax for extending it.

I still mostly use LaTeX for documentation though.

You should give sphinx + latex a try. I have my own cookiecutter template for docs and it's never been easier and fast to write some good looking documents.

wikicreole.org don't work without www. Right link is http://www.wikicreole.org/

That's what I came to the comments for.

wikicreole webmaster, please do configure your DNS thoughtfully, and OP please check your links before posting.

Reply on news.ycombinator.com