
Whats Wrong with Markdown - sciurus
http://www.adamhyde.net/whats-wrong-with-markdown/
======
ahoge
> _Markdown (.MD) is a text format that lazy people use to write HTML._

Markdown is a markup language for relatively simple structured documents. You
can convert it to HTML, but you could as well convert it to something else.

> _However that is where the use case ends. .MD is not a useful format for
> many other cases unless you want to prove to the programmers that you too
> can do tricky stuff in plain text. For the rest of us it has little value._

It's used by Reddit and some content management systems. Regular users don't
have any problems with it. It's a lot easier to use than HTML and also more
convenient to use than RTEs.

Markdown isn't for writing HTML. It's for writing the actual content.

I wrote about 100 articles in "raw" HTML. I surely don't miss those days. It
was error prone and the tags added very distracting visual noise.

~~~
Zarel
I'd disagree that regular users don't have any problems with it.

One very common problem I've seen is a conversation like "How old are you?"
"21." which Markdown interprets '21.' as a list and renumbers from 1, leading
to: "How old are you?" "1."

Another problem is that single linebreaks are ignored. Things like song lyrics
and ASCII art get messed up, and some people even use single linebreaks for
paragraphs. And even if you do use two linebreaks for paragraphs, there's
still the problem that copy/pasting text will eliminate paragraph breaks since
they're copy/pasted as one linebreak.

I could go on, but the point is that Markdown is honestly not a very user-
friendly way to format text on a discussion website.

~~~
glomph
I agree with this. In 90% if cases where it actually formats anything on
reddit it basically gets it wrong in terms of the users intentions.

------
EpicDavi
This article is just condescending and gets nothing accomplished. Its like me
writing an article titled "Whats Wrong with Cars", where I list my complaints
about cars: "People who don't drive cars won't know how to use them", "People
use cars for purposes other than the creator intended them for", "Cars are
Non-Standardized (Stick Shift, Automatic, etc)".

It's just annoying that he/she isn't providing any solutions and is just being
a Negative Nelly. Why not write something like: "Whats Wrong with Cars and How
We Can Fix Them". All I got from the article was "Cars suck, all the people
who use them are just 'cool aid' drinkers".

Also there are numerous typos, such as: "...it woudl look like this:"

~~~
adamhyde
Thanks for the tip. I added a few things this afternoon and didn't spell check
:)

As for negative nelly, the post right after the markdown one is about an
alternative (for a very specific context). But no matter, you're probably
right, it might have been better to add a few alternatives to the end of the
article.

------
russellbeattie
The root problem here is that every HTML WYSIWIG editor (from MS Word to
TinyMCE) uses their own special blend of tags when creating HTML. There's only
a handful of tags that are generated by Markdown, the problem is that editors
often don't use standard tags (e.g. <span class="bold">) or they try to do too
much and enable every feature that exists in HTML. This causes an absolute
mess where one editor can't really parse another's output. (Sometimes the web
based ones have trouble dealing with their own markup - turning HTML into a
write-only language akin to regex).

Markdown is just a horrible solution to this problem. Rather than 'Common
Markdown' there really needs to be 'Common Markup' which strictly limits the
tags WYSIWYG editors use. This would enable true interop and solve the real
issue for most people who could - like the author pointed out - see the
formatting they were using.

Think of it as the equivalent of ASM.js for markup - only the core tags (the
ones Markdown uses) would be used, and only in a specific way. That would
speed up parsing, processing and display and none of us would have to remember
if adding a link uses () or [] first again (I always get it backwards).

~~~
npongratz
> ... none of us would have to remember if adding a link uses () or [] first
> again (I always get it backwards)

I also often forgot, until I read this paraphrased explanation [0]: when we
write, we are much more likely to parenthesize than "bracketize" (as in this
parenthetical), so the square brackets [] go first when making a link. This
makes it easier for the parser.

[0] I read this in a comment on HN, but sadly I cannot find the comment, else
I would give proper attribution.

------
egypturnash
Markdown has basically kinda won the Plain Text Format War but man sometimes I
really wish it had used the "enclose text between slashes" format for
/italics/. Enclosing text between asterisks is for __bold __. Enclosing text
between two asterisks before and after is for... what? Who writes that out in
plain text areas? Nobody. Nobody except Gruber.

~~~
wingerlang
> Who writes that out in plain text areas? Nobody. Nobody except Gruber.

I do this. Reading through my recent comments on [Website X] concludes that I
use it as kind of an "italics" tag even though there IS markdown on that very
website. I guess it becomes more pronounced.

~~~
adamhyde
I think tho that Markdown hasnt won the plain text battle - plain text has.
Only a very small percentage of plain text docs are markdown...so small it
wouldn't even count...

~~~
ahoge
Reddit, Stack Overflow, GitHub/BitBucket (readmes, tickets, wikis), and it's
also used by a couple of CMSs, blog platforms, and static website generators.

Virtually all of the text I write is Markdown. Even this very comment is
written in a subset of Markdown (and so is yours).

~~~
adamhyde
Yes and notice how few have used it even here. Most replies are plain text.

~~~
ahoge
Paragraphs and emphasis are frequently used here.

~~~
adamhyde
paragraphs are plain text :)

~~~
ahoge
No, they are not. It's not directly spit into an element with white-space:
pre-line or white-space: pre.

It's converted into paragraphs. Just like stuff inside asterisks is converted
into emphasis.

~~~
adamhyde
sigh. plain text paragraphs cant be claimed to be invented by markdown. sorry.
good try tho.

~~~
ahoge
Invented? You are missing the point.

The comments are written in a markup language (Markdown, UBB, whatever...)
which is then converted to HTML.

It's transformed and not displayed as-is.

~~~
adamhyde
Thats like saying BP invented oil. To claim a plaintext only comment, sans
markdown syntax, as markdown is a big stretch to make. But I understand you
will want to make that stretch inorder to justify the magic utility of the
format. Thats a big whatever from me.

Anyway. Im not going to argue this further. Agreed to disagree.

------
RubyPinch
> Markdown isn't designed for creating HTML

reasons:

* a third party tool produces different results from other third party tools

* the chosen third party tool works from the command line

* because un-official docs say so

its document markup specifically to be rendered to html, its not html
abstraction, if it was html abstraction, it would be looking like haml instead

\- - -

"![]()" doesn't look like an image, "![the motions of several
cogs](/imgs/several_cogs.gif)" does, and would be really hard to mistake for
anything else

thats like complaining about the use of brackets in C by just saying,
"`{([])}` looks unreadable, doesn't it?"

\- - -

"Markdown is good for limited use cases. Use it for README files on github."
and yet you just spent an entire blog post complaining about that exact series
of use cases

zero alternatives mentioned to complaints raised, pre-emptive insults against
those who might have issue with a poor article

------
Pxtl
I'll agree markdown has some strengths and weaknesses. The image syntax is
terrible, and even the link syntax is a little iffy. But the bullets and the
bolding? Yes, it's excellent, it does exactly what it needs to be. Whenever I
need a user to give me rich text for something, I tell them about Markdown. No
worries about all the font and styling screw-ups from a word document where
the user has pasted text.

"I need the user to give me plain text but they also need bold, hyperlinks,
and bullets" is the use-case for markdown. It does this fine. It could do
things better, but it does its job fine.

I have had users get annoyed, however, that _underscore_ doesn't underline.

------
pbreit
This post was pathetic from the very first sentence to the very last. It's one
long stream of lack of understanding starting with the insulting "lazy people"
opening.

------
JohnHammersley
Great post - I would stress that for me, one of the big limitations of
Markdown is that it just doesn't do everything LaTeX does.

So although it might be slightly easier to get started with, it doesn't let
you do everything you need (as a scientific writer).

~~~
aikah
> Markdown is that it just doesn't do everything LaTeX does.

That's not the purpose of Markdown. Markdown is a quick language to write HTML
formatted content,nothing more.It's supports a limited set of tags. It's
popular because it's simple ,unlike LaTeX. It's popular because it's easy to
write a Markdown parser. Simple tools are always popular.There is nothing more
to it. A rant against Markdown is unnecessary.It was designed for a
single,limited purpose.

~~~
JohnHammersley
It wasn't meant as a rant against markdown -- just my observation that, for
me, I found its simplicity limiting rather than helpful (I appreciate I could
have made that clearer in my initial comment though)

------
KrisAndrew
I agree with the author in general. However, I would write an article about a
more general and insidious fashion (fashion repeats itself). That fashion is
"I hate typing" or, alternatively, "typing less makes me more productive."
Guess what; it doesn't. Here's why.

If you're using programming slang to make yourself more productive, then
you're not programming. You're a boiler-plate code generator. Therefore you
could be replaced by a program or DSL that a more adept programmer could
write. Stop using slanguages and start thinking about what and how you're
coding. You'll become a better programmer. Quit trying to fool yourself that
syntactic sugar and shortcuts are a valid development paradigm. You'll become
a better project manager.

I abhor things like CoffeeScript and Markdown and various metalanguages,
because they are speciously productive at first. You type less and get the
same result. Great! However, most coding actually requires some thought and
the logic and structures don't simply fly off your fingers. It comes slowly
and these slanguages stop being useful at this point. So you take the time and
effort to learn a modified, non-standard syntax that stops paying off once you
get to the core of your task.

I hate to think of how many wasted programming man-hours non-standardized
formats have produced.

~~~
camillomiller
I think that the original post and your comment both miss the point in a big
way. You are upset at __all the people who use markdown and think they are
coders __. Do you really think such a sample of people exists? Where exactly?
Nobody can say that with a serious face and anybody who 's into learning
markdown has at least enough knowledge to know that.

Use case for markdown: when I build website (by hand, writing pure HTML-CSS-JS
on my text editor of choice), adding the copy can be a chore. If I write it in
markdown, or ask people to write it in markdown, or reprocess whatever they
send me in a markdown editor with html output (I.e. Byword), I save a ton of
time by producing a very simple html text block I just need to copy and paste
where needed.

Second use case: when I wrote my degree thesis I chose to do that with a
normal text processing software (Pages on the Mac). When I had to put it
online, I simply copied it inside a markdown editor coupled with a previewer
(Marked) and I quickly wrote a couple of scripts to convert footnotes
(supported by hyper markdown). Half a day later I had my chapters in a format
that I was able to quickly turn into html blocks for my website and convert to
ePub with Pandoc. Markdown saved me hours of work.

Third use case: whenever I write a post for the web publications I work for, I
write it in markdown with Byword, because it gives me a good distraction-free
writing environment and the ability to send my editors (that being myself,
sometimes) a perfectly fit HTML a version of the article. When I write
articles, I want to focus on writing the article, not writing even the
simplest HTML.

Last, but not least, the guy seems to willfully ignore the plethora of very
good markdown editors (with incredible support to HTML conversion) out there.

This is why the article sounded more like a bitter rant, than a thought
critique.

~~~
KrisAndrew
It's a critique, impassioned and curt albeit; and here's the most powerful
metaphor you'll hear in regard to the topic of non-standardized formats.

Non-standardized formats/languages are the jive
([http://en.wikipedia.org/wiki/Glossary_of_jive_talk](http://en.wikipedia.org/wiki/Glossary_of_jive_talk))
of the development world. It sets you apart from the general population (of
programmers) when you use it. It primarily effects obfuscated communication to
a smaller group. The specific form of jive will fall out of fashion a few
years after you learn it. There is very little value in committing it into
your brain other than for 'funsies'.

(In regard to Markdown specifically: there are tons of WYSIWYG HTML editors
out there. Use those and copy/paste the HTML text. It requires no learning at
all. Markdown was pre-emptively made useless over a decade ago.)

------
philgr
He lost me in this paragraph:

> The original purpose of .MD is that it can be read without converting it to
> another format like HTML (...) .MD is designed not to be rendered for
> display, it is meant to be the display.

And this is the first paragraph from Markdown's introduction[1]:

> Markdown is a text-to-HTML conversion tool for web writers. Markdown allows
> you to write using an easy-to-read, easy-to-write plain text format, then
> convert it to structurally valid XHTML (or HTML).

Keywords here: "for web writers" and "convert it". Let me say it again: this
is the first paragraph you read when you look for Markdown.

[1]:
[http://daringfireball.net/projects/markdown/](http://daringfireball.net/projects/markdown/)

~~~
adamhyde
The link you are referring to is for a perl script to convert markdown to
HTML. It is not markdown, the syntax, referred to in that article. You would
have understood that if you read the next paragraph

"Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a
software tool, written in Perl, that converts the plain text formatting to
HTML. "

The article was about the former, your comment confused it with the later.
Cheers.

------
StephenGL
Adam I completely agree. Markdown is fantastic _at something_. That something
is non-complex documents. What has happened since is that techies have taken
that non-complex use case for the tech and made the logical leap that it is
somehow a leas complex tool for complex cases. In other words "average users
will understand this". The average user likely will for the most basic case
and then will be thrust upon a poorly standardized, often needlessly complex
hash of a markup extension set for anything more complex. All of this energy
at the expense of HTML gaining more users and or web based WYSIWYGs being
refined to the point of awesomeness.

------
KayEss
The only real problem markdown has is the use of () around links, because both
of those can be in the link (i.e.
[http://en.wikipedia.org/wiki/URL_(disambiguation)](http://en.wikipedia.org/wiki/URL_\(disambiguation\))
). It really should have picked something like <> which can't be in the link
itself.

EDIT: the parser on this site seems to think that > is valid in a URL.

------
BruceIV
I thought the only really legitimate gripe he had was the non-standardized
interpretation of the edge cases, and once we get a number of decent
CommonMark implmentations / refinements to the spec, we should be able to
handle those fairly soon.

I use Markdown to take text notes; it's quick to write, and especially with my
text editor's syntax highlighting it looks decent too.

------
Jonhoo
First of all, I reject the premise of this article:

> Markdown (.MD) is a text format that lazy people use to write HTML.

This is just blatantly false. Markdown was never intended to _replace_ HTML.

Second, the author points how how "The quick _brown fox_ __jumps ___over_ the
lazy __dog __" is not very legible. I completely agree. However, this is
contrived example that you are unlikely to encounter in practice. Just as it
would be unlikely someone would mix bold and italics so closely in "real"
formatted text.

The author then goes on to say that

> Lets face it, even Programmers don't like reading raw Markdown and so in the
> most popular .MD repository of them all - github - the Markdown files are
> rendered in the browser as nicely formatted HTML.

As a programmer, I actually really enjoy reading Markdown files. While it is
true that it can be made more visually appealing for inclusion in a website
like what happens on GitHub, it is great to have a somewhat standardized
format that makes it pleasant to read those same files when you _aren 't_
browsing the files online. While I would bring up browsing files from the
command-line here, the author seems to have a strong dislike for those of us
who dabble in the black magic that is the shell.

All this aside, it is true that Markdown is not the right tool for everyone,
and that the toolchain does not necessarily make it easy for beginners to get
started writing all of their documents in Markdown. However, try to make
someone open a Word document _without Word_ , and see how easy that is. The
lack of (beginner friendly) tooling is definitely not a sign of a poor format.

Finally, the author ends with

> However, if you have heard that there is this cool format available and it
> cures all your textual needs and it is just really really easy to use and
> really really quick...then think about the elixir you are being offered and
> re-read this document before slurping away...
    
    
      a) it is not a new format
      b) it never claims to cure all your textual needs - it aims to make it easier to create formatted text, where previously there was none
      c) it is, without a doubt, really really easy, and really really quick, because any plain text document is valid Markdown. All Markdown does is attempt to standardize some (already fairly common) methods for applying *simple* formatting to that text.
    

While the author bashes Markdown's lack of standardization, the cases that are
brought up by CommonMark are more important for implementors than for writers,
and "regular" users will likely find the informal language description more
than satisfactory for common usage.

TL;DR: The author is hating on Markdown, mostly due to incorrect assumptions
and seemingly a personal dislike for plain-text formats.

~~~
adamhyde
hi

Argh. My reply got burned by the server downtime. Just to say I dont have
anything against the shell and plain text- I produced (facilitated) the
production of numerous books around this topic including
[http://www.flossmanuals.net/command-
line/](http://www.flossmanuals.net/command-line/)

Glad you like reading markdown. I don't think that is a majority position
though and I see markdown being promoted to a larger community at times that
really wouldn't find it useful or nice to use.

~~~
godDLL
Any plain-text based format is, in the end, maximally at least as readable as
plain-text. Any kind of markup in it will generally diminish readability.
Markdown is very close to being just plain text, but with a very short path to
HTML markup -- you just start typing HTML in.

So yes, people will enjoy reading Markdown in at least as much as they do
plain text. And yes, the implementation quirks will be annoying for anyone
using it. But I don't see how all these add up to a larger argument against
Markdown.

------
sic1
"You mad bro?" comes to mind.

Successful rants provide solutions at the end. Otherwise, its just that, a
rant that has no real meaning at all other than allowing you to vent - like
this post.

Feel better (I do).

~~~
adamhyde
Yip. Feel much better :)

------
adamhyde
hi, Adam here, I wrote the article. Really interesting comments. Just for the
record, I am in favor of the command line tool, and I have also posted
numerous articles on better alternatives :)

~~~
k_
No offense meant, but your blog seems like a punchbag you use whenever you're
mad with a technology or it doesn't fit your use cases. Going through some
random articles feels like hearing someone bitching about random things when
in bad mood. I don't see much value in that: [1] [http://www.adamhyde.net/why-
github-is-bad-for-open-source/](http://www.adamhyde.net/why-github-is-bad-for-
open-source/) [2] [http://www.adamhyde.net/markdown-
ugh/](http://www.adamhyde.net/markdown-ugh/)

I'd suggest some things here:

* Do not post; wait. I don't know what was going on when you wrote [2], but you were clearly not in a mood to write anything constructive. Maybe you should have skipped [2] and only write your second article about markdown (not that I really agree with it either (see below), but at least it is developed).

* I don't really see the point in complaining alone. Maybe you should look for alternatives, and post them along with your complains. Or if you don't know any and don't want/have time to look for one, ask people (I don't know if you can easily add things like discuss on Ghost). For [1], I think you would like GitLab, for example.

Honestly, after reading your article about markdown (the long one), I don't
feel like reading any other of your articles. Not that it's bad, but I waited
the whole article for some things that never came[ _], and ended up feeling
like I wasted my time there: I just listened to someone complaining about
something (mainly about being bad for doing things it 's not really meant to
do), and nothing else. So now I expect to experience the same with any of your
articles (and I'm probably wrong), and I may be missing some great things. [_]
I was expecting some kind of "solution". Alternatives? Anything?

~

About the article:

You complain about markdown, but use Ghost for your blog (or can you write
blog posts with something else on Ghost? Didn't see any from their home page).
You never mention any alternative.

Maybe because there isn't many that are:

* easy to read without being parsed, with most of the syntax being somewhat explicit

* can be used to produce "clean" html

* widely used (with some flavors but mainly the same syntax)

And that's markdown (to me at least). It's not here to replace html, MS Word,
etc. More like replacing bbcode and other ugly syntaxes. You sound like you'd
rather use plain html, but do you? Would anyone rather use plain html than
markdown (when available) for writing simple formatted text? (well yes, some
would.. xD)

Markdown could greatly benefit from standardization, though. That was the one
valid point in your article, imho. It's sad but I haven't seen many big
differences anyway, except: * some space differences (line breakings, etc.),
but no change in the meaning of the syntax * lists must be preceded by an
empty line on some parsers * custom syntax for additional parsing (images,
etc.) but well, that's not really a problem with markdown, more like a problem
with ghost-flavored (or anythingelse-flavored) markdown

It's not perfect, and still wouldn't be even if standardized (but would be
much closer); but I see no better alternative. And neither do you, seemingly.
(so no, I did not find your "numerous articles on better alternatives" =/)

~~~
adamhyde
haha :) yeah, the last few weeks scratched a few itches, thats for sure! But
on the whole Im a positive chap and the posts are positive or (gasp) tongue in
cheek :) Don't take it so personally! Thanks for your points, hope you do read
some more of the blog but no worries if not.

------
droob
Whats how do trolling

