Whats Wrong with Markdown | Hacker News Reader

Whats Wrong with Markdown

adamhyde.net

19 pointssciurus42 comments

> 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.

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.

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.

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:"

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.

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).

> ... 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.

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.

> 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.

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...

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).

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

Paragraphs and emphasis are frequently used here.

paragraphs are plain text :)

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.

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

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.

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.

> 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

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.

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.

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).

> 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.

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)

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.

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.

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) 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.)

""typing less makes me more productive." Guess what; it doesn't."

That statement may or may not be true, but its converse ("typing MORE makes me more productive") is nigh-certainly false.

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/

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.

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.

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) ). 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.

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.

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.

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/

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.

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.

"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).

Yip. Feel much better :)

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 :)

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/ [2] 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" =/)

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.

Whats how do trolling

Reply on news.ycombinator.com