
The Future of Markdown - dko
http://www.codinghorror.com/blog/2012/10/the-future-of-markdown.html
======
blasdel
John Gruber's original Markdown.pl is one of the worst small programs I have
ever read, completely riddled with outright bugs and misfeatures that
continually bite its users in the ass. It's awful even by the already low
standards of hand-written many-pass regex-based spaghetti-parsers.

Nobody should be using the original script, and unfortunately many of the
other implementations out there are direct transliterations that replicate all
of its absurd errors, like where if you mention the MD5 hash of another token
in the document, the hash will be replaced with the token, because it uses
that as an inline escaping mechanism! Reddit got hit with a XSS virus that got
through their filters because of it: [http://blog.reddit.com/2009/09/we-had-
some-bugs-and-it-hurt-...](http://blog.reddit.com/2009/09/we-had-some-bugs-
and-it-hurt-us.html)

See the changelog for what started as a PHP transliteration and turned into a
rewrite that squashed 125 (!) unacknowledged bugs:
<http://michelf.com/projects/php-markdown/>

The worst part is that he outright refuses to either disclaim or fix his
implementation, and so far he's repudiated everyone else's attempts to do so.
He's a terrible programmer and a worse maintainer, he really still thinks the
documentation on his site is comprehensive and canonical. As much as Jeff
Atwood leaps at every chance to play the fool, there's no way his directorship
can be anything but an improvement.

~~~
dandelany
I'm so tired of this mentality that says basically, if you release something
for free on the internet, you are obligated to maintain and support it for the
rest of your life. Gruber created this program, for free. You are under no
obligation to use it. Don't like it? Here's your money back. It may be true
that the code is shit. If you think so, don't use it.

Like other responders, I worry that this mentality causes fewer coders to
release their projects, for fear of backlash like this post. Think about it:
Your feelings toward Gruber are incredibly negative and hostile, and in fact,
you would have better feelings toward him if he had kept Markdown to himself
and never released it at all. Does that seem fair to you? If the ill will
generated by people like yourself outweighs the good will generated by those
who appreciate the code I release, or if I fear that it might, what motivation
do I have to release my code?

~~~
alanh
The problem is not that Gruber doesn’t want to maintain Markdown. If that were
it, perhaps it would be easier to move on without him.

It’s that he thinks the best option is to do nothing. He claims the title of
BDFL without playing the role.

See his first reply to the Markdown mailing list in nearly three years:
[http://six.pairlist.net/pipermail/markdown-
discuss/2012-Octo...](http://six.pairlist.net/pipermail/markdown-
discuss/2012-October/thread.html#2695)

~~~
blasdel
You have it absolutely correct

He enjoys the credit for being the creator of something used by millions every
day, but is entirely unwilling to take the responsibility that comes with that
creation being a very public mess.

It works for his usage, but all the ambiguities and undefined behaviors affect
a huge number of people, and his only response he's made for eight years has
been to retain sole moral authority and refuse to use it.

~~~
grey-area
_It works for his usage, but all the ambiguities and undefined behaviors
affect a huge number of people, and his only response he's made for eight
years has been to retain sole moral authority and refuse to use it._

You gain moral authority by actually _doing something_. If you use markdown,
and wish to propose a better markdown than markdown, go for it, I'm sure lots
of people will be pleased, but bear in mind that lots of people will whine
about any bugs as well, and expect you to work for them for free and spend
significant resources and time fixing edge cases which don't matter to you
personally, just because you released the source.

If you're ready for that though, of course go ahead and create a better
markdown, or help with this proposed spec, Gruber certainly can't stop you. It
doesn't really matter what Gruber says, what trolls on a mailing list say, or
what you say on this forum about his responsibilities, whether he is self-
appointed dictator for life etc (though I'd dispute that), what counts is
putting the work in, which is often surprisingly difficult - far more
difficult than criticism.

~~~
matthewowen
Of course you can do that. I think people's problem is with Gruber's
unwillingness to lend any support to those efforts to create a less buggy
implementation.

Right now, the canonical markdown implementation isn't very good. It's hard to
change what the canonical implementation is without Gruber's support. It
doesn't even require much from him - just his blessing.

He isn't under any obligation to do this. No-one thinks he is. But it would be
a good thing for him to do.

~~~
grey-area
Frankly, I don't think what Grubber says matters here, and I see why he
wouldn't want to engage all the trolls who are _enraged_ by his inaction.
Markdown works for him and he prefers it simple if somewhat vague/buggy, if
you need something different, build it.

If someone wants to write a spec, a better parser or a better markdown full
stop, there is absolutely nothing to stop them. The problem is, people would
rather bitch about why no one else is doing anything and complain about gruber
than actually do the hard work necessary. Do the work first, then look to
gruber for canonization if you must, though by that point his views on the
matter would be irrelevant.

------
dgreensp
Wow, I wasn't expecting my email to Jeff to end up as a front-page blog post!

The point here is that Markdown doesn't have a spec, nor do any of its
variants to my knowledge, so I was proposing to come up with some Markdown-
like language that _does_ have a spec. Under discussion here is the more
ambitious (but also appealing) plan of writing an official spec for Markdown,
the same way JavaScript got a spec in the form of ECMAScript that we now
identify with JavaScript itself.

A spec is a long, tedious, human-readable document that explains the behavior
of a system in unambiguous terms. Specs are important because they allow us to
reason about a language like Markdown without reference to any particular
implementation, and they allow people to write implementations (Markdown
processors) independently that behave identically. The Markdown Syntax
Documentation is not a spec (it's highly ambiguous), nor is any implementation
(not human-readable; some behaviors are probably accidental or incidental and
difficult to port perfectly). The hard part of writing a spec is codifying the
details in English, and secondarily making decisions about what should happen
in otherwise ambiguous or undefined cases.

My motivation for working on a Markdown spec is first and foremost avoiding
"bit rot" of content, which happens when we write content against one Markdown
implementation and then later process it with another. We don't have this
concern with HTML, JSON, or JavaScript, or at least we know what bounds to
stay within to write code that will work on any implementation. This is
achieved through specs, even if only implementers ever read them.

I would love pointers to Markdown processors that are implemented in a more
principled way than the original code, for example using standard-looking
lexing and parsing passes, but that still handle nested blockquotes and bullet
lists together with hard-wrapped paragraphs.

~~~
bitcartel
Why are people still interested in Markdown - what problem is it solving and
for whom?

It's 2012 and we have HTML 5 compliant WYSIWYG text editors. We no longer have
to write plain text littered with special codes, for the purpose of running
through a parser, to produce HTML which looks nice on a web page. Maybe it
made sense a decade ago when web forms had terrible editors, but not anymore.
I think Joe Internet writing blog posts and forum replies would agree with me.

For developers, a README file in plain text looks great everywhere, and avoids
any Github vs Bitbucket vs Assembla display issues. If you need to write
structured documentation for a system, there's probably already a designated
markup language you're supposed to use, so Markdown doesn't help there.

~~~
keithpeter
_"Why are people still interested in Markdown - what problem is it solving and
for whom?"_

I understand the question and wonder why it attracted down-votes. The
executive summary of my answer: light markup is used in places other than text
areas on Web sites.

Many of us use Markdown to keep formatted text in, and, ultimately, to
generate valid html markup from. Markdown is _not_ just for textareas in Web
pages. Whole books have been marked up in markdown.

Markdown files are just text files with 'explicit' markup within them and so
will always be accessible/editable/processable in the future. Markdown is
'flexible' in the sense that it allows alternative markup for the same output,
and is 'light' in the sense that a limited range of styling and block formats
are available. Compare that with LaTeX which shifts with each tex-live
release, and which means that markup written some years ago may not format
without hand editing on a modern LaTeX release.

There is the reference implementation available from Gruber's site, and, as
others have mentioned, pandoc implements markdown in a way that can be
extended. I'm dubious of the need for an 'official' specification; I rather
like the scrappy streetwise nature of Markdown.

~~~
JadeNB
> Compare that with LaTeX which shifts with each tex-live release, and which
> means that markup written some years ago may not format without hand editing
> on a modern LaTeX release.

What? Certainly details of individual packages may change, including addition
or removal of functionality, over time, but I don't even know what it means to
say that "LaTeX shifts". The underlying markup language for LaTeX, which is
the same as that for TeX, is very flexible, but has had the same flexibility
since at least 1982, if not 1978.

I understand the idea that built-in extensibility leaves a platform, to some
extent, to blame for its plug-ins; but many people in this discussion have
proposed building some sort of plug-in architecture for Markdown, too.

------
X-Istence
I might be the only one, but I actually prefer Markdowns handling of a single
"enter" without spaces at the end to mean that the paragraph is not finished.
It makes writing blogs and various other stuff in Vim much simpler, and I can
more easily reformat text to wrap at 80 characters, and have better control
over it.

Could I soft-wrap in my editor? Sure, but that would mean that the text files
sitting on my hard drive now have very long strings in them making it harder
to grep, making it harder to add to git (change a single character, entire
line is now a diff :-().

I hope that doesn't become the default.

~~~
jomar
I guess there is a distinction between

* people typing markdown in text files, where you want to split paragraphs into word-wrapped lines of a sensible length, and consecutive non-blank lines form paragraphs just as they always have in text files;

* and people typing markdown into text entry boxes on web pages, where you would like pressing the <enter> key to actually mean something.

These two situations probably prefer a different default.

~~~
X-Istence
Then make the form that the user enters data into be either parsed
differently, by pre-processing it, or have some javascript magic that
automatically adds the extra two spaces required to make it work.

This way if the user presses <Enter><Enter> then the JS can remove the extra
two spaces and it will still be valid markdown.

------
raldi
I'd also advocate for accepting reversed ()[]'s on links.

In other words, let the user type:

    
    
        [something](http://whatever.com)
    

or

    
    
        (something)[http://whatever.com]
    

...and have both work exactly the same.

It will save a lot of trouble -- and especially when linking to a Wikipedia
page whose URL contains parentheses.

~~~
AngryParsley
I feel your pain. Parens in links made me never forget %28 and %29. But I
think your solution causes more problems than it solves. The biggest issue is
that it's not backwards-compatible with current markdown. For example, in a
citation following parentheses:

    
    
      Blah blah blah (side note)[1](http://url1).
    

Your markdown generator could output

    
    
      <a href="1">side note</a>(http://url1).
    

or

    
    
      (side note)<a href="http://url1>1</a>.
    

The latter is current behavior, but your suggestion makes the grammar
ambiguous. Most parsers are "greedy", so the former is more likely to be
output. Unless you specified more complex behavior, people would have to go
back and escape their parens near links.

~~~
thaumaturgy
I've just finished writing a hyperlink parser; getting it to handle your
specific case would be totally do-able.

I think your overall point still stands -- there would be ambiguous edge cases
-- but if Reddit comments are anything to go by, they really wouldn't be any
worse than the current confusion, and making ()[] interchangeable would clear
up a lot of the common problems that users have with making links.

~~~
AngryParsley
To fix the ambiguous grammar, we need to add a url parser to markdown? This is
a perfect example of how changes that seem simple to humans can have enormous
impacts on software complexity. As you said, introducing that complexity
wouldn't help in many cases:

    
    
      Blah blah blah (side note)[1](#ref_1).
      Blah blah blah (side note)[1](ref_1.html).
    

I don't mean to be hostile, but just because something is "doable" doesn't
mean it should go in the spec. Adding things to a standard imposes costs that
feature-proposers rarely consider. It forces programmers to write more code to
support that feature. More code means more bugs. These bugs annoy users and
cost valuable programmer time. Multiply these costs by the number of times the
standard is implemented and you can easily end up with millions in lost value.

Vanilla markdown doesn't require a url parser. It doesn't have ambiguous
grammar. It's small. It's simple. And that's a good thing, because markdown
parsers have enough bugs in them already.

~~~
thaumaturgy
1\. URL parsing is a solved problem. Since I so frequently have my competence
questioned on HN, I have to conclude that if I can do it, anyone can.

2\. There are a number of people in this thread, and many many many more on
Reddit and on other forums that use markdown, that have had a specific UX
problem with markdown which we can solve. The solution will not solve _all_
possible problems, but it will solve many of them.

3\. I subscribe to the Linus Torvalds camp of software development, which is
that software exists to solve user problems.

4\. While the trade-off between additional code complexity (and better overall
user experience) versus simpler code (and poorer overall user experience)
isn't always justified, in this case I think it is. I mean, HN parses URLs for
you and makes them clickable -- would you really support removing that as a
feature, in favor of having simpler code, and having to copy & paste links
into your browser?

5\. This particular feature rather nicely lends itself to extensive testing so
that you can make sure you've covered most of your edge cases. If we decide
not to implement solved, testable features out of fear that some other
programmer might not implement it correctly or test it thoroughly enough, then
I don't know what to say about our industry other than that it's going to come
to a standstill.

I'm afraid that's all the energy I have tonight for arguing about things I
don't really have any influence over on HN.

------
kaptain
Why?

Why get all angry at John Gruber? As many have already noted, he created
Markdown for himself and released so that others could use it. AFAIK he didn't
put any license/restrictions on it outside of calling himself BDFL. Whatever
his skills as a programmer, writer, or his role as Mouthpiece of Apple, the
vitriol is unnecessary (but absolutely fanscinating to watch). My panties
bunch up naturally, no need to allow my feelings regarding Gruber to bunch
them further.

Why get his approval? In the same spirit that Gruber created something for
himself, you should just create something for yourself. I find it hard to
believe that Gruber was the first person that conceived the idea of user-
friendly text-markup. The new standard could just be inspired by Markdown and
that would be a win-win: a respectful nod towards Gruber as well as the
ability to move towards something 'better'.

~~~
fusiongyro
It's consensus-building. If the creator of Markdown says the successor
technology is Rockdown, everybody who deploys something on Markdown will get
hate mail: "why aren't you using Rockdown? Gruber says it's the future." If
that doesn't happen, Rockdown is just a peer to Markdown—an improved,
specified peer but not anointed. It leaves the window open for people to say,
"well, I like flavor-X Markdown better than Rockdown, so that's what I use."

~~~
kaptain
If consensus-building is one of the goals, then I would agree with you that
Gruber's blessing is important. But one of the goals of Markdown is to
provided easy-to-use markup for text. Whatever the next iteration of this
looks like, I think that people will get on board if it provides a clear
advantage over Markdown as it exists as well as other markup formats. With or
without Our Dear BDFL's blessing.

Only geeks will complain about whether the successor of Markdown is deployed.
Others, the majority of whom user-friendly markup is aimed at, won't care.

If enough people get behind this, it won't matter that Rockdown is a peer to
Markdown. With good tools and support, Rockdown has the potential to exceed
Markdown, even if it's just providing a better canonical parser and
documentation since it's pretty clear from most of these comments that this is
where Markdown is lacking.

~~~
fusiongyro
You're missing the point, and you're missing it hard. Look at CSV. Do you want
a repeat of that fiasco? That's a format with literally one feature, and yet
in the wild it comes in so many varieties you must guess and configure with
every CSV parser. We're in a unique situation here in that the progenitor of
the format is alive and can appoint a successor to avoid that whole problem.

"But one of the goals of Markdown is to provided easy-to-use markup for text."
This is in no way contradictory to the aim. The idea here is to standardize
Markdown, not to replace it with XML.

"I think that people will get on board if it provides a clear advantage over
Markdown as it exists as well as other markup formats." The clear advantage is
that the parser won't have to guess what you meant and thus get it wrong. The
clear advantage is that when you enter copy text from Github and paste it in a
Reddit comment box it will come out looking the same. The clear advantage is
that in ten years there is a flag for "Accept Standard Markdown only/Accept my
weird extensions" to establish a baseline. The clear advantage is that your
files won't have an expiration date. The clear advantage is that you won't
spend months closing tickets and replying to emails entitled "Why is my
formatting all fucked up?"

"Only geeks will complain about whether the successor of Markdown is
deployed." Yes, and only geeks care about standards, because only geeks
understand the immense difficulty that is supporting a family of mutually
incompatible formats and protocols and therefore only geeks understand what
standards actually do for them. Users may not care, but when shit breaks they
have this unpleasant habit of blaming us and our work, and I find it frankly
insane that any reasonable programmer could resist an effort to make their
life and the lives of their comrades easier, practically for free.

"If enough people get behind this, it won't matter that Rockdown is a peer to
Markdown." Have you ever worked with scientists? There is code in my codebase
written in Fortran 77—and that code was written two years ago. Not everybody
is interested in upgrading on your schedule. In fact, in many places, obeying
the standard is the standard practice, and there is absolutely no interest in
performing time-consuming comparisons to figure out independently what is
technically superior to what or even what the options are. Standards are
intrinsically valuable to these organizations, and you will inevitably find
yourself tasked with dealing with them. You're essentially saying "Why declare
a standard when we can just rely on word of mouth and let people figure it
out?"

I hate to impugn a fellow HNer, but I really can't abide this sloppy, half-
assed, incomplete thought. This initiative is obviously the right thing to do,
or at least try to do. If you disagree, I curse and damn you to ten years of
supporting incompatible highly-similar formats, after which I am certain you
will see the utter pointlessness of it and the ease with which it can be
averted and agree with me.

~~~
kaptain
I'm not sure what point you're referring to that I'm missing. Here's my point:

People don't need to wait for Gruber to make a standard; Gruber doesn't hold
enough power to prevent the adoption of a Markdown-like standard. The adoption
of the standard will correlate with the value that it brings.

I am not saying the rest of the stuff you think that I am saying; I was just
responding to your argument.

    
    
      This initiative is obviously the right thing to do, or at least try to do.
    

I completely agree with this statement.

Feel free to impugn me. It is your right to; actually, it is your obligation
to if the situation calls for it.

------
dfc
I really hope that they borrow a lot if not everything from pandoc[1]. My only
real complaint with pandoc is the table formatting, but I think fiddlosopher
is adding org-mode like table support.

If you have not taken a pandoc for a spin I highly recommend you do so soon.
In addition to being a great markdown dialect the pandoc tool set is the swiss
army knife of text formatting. It is amazing how many formats pandoc can read
and/or write.

[1] <http://johnmacfarlane.net/pandoc/README.html>

EDIT: I spoke too soon, Fiddlosopher continues to impress. I just checked the
open issues and a little less than a month ago he added "limited org-table
support." Based off of the rest of pandoc "limited" probably means something
like 85% to 95% :)

<https://github.com/jgm/pandoc/issues/519>

~~~
NullSet
I cannot second this enough. Pandoc Markdown has some nice little tidbits,
oddly contrasting to the above, the table syntaxes(yes there are more than
one) are pretty darn useful.

------
SeoxyS
I'm the author of a Markdown text (prose) editor[1], and can attest to Jeff's
statement that all Markdown's parsers suck. The official perl regex-based
implementation is a joke. Sundown is great, but only works for cross-
compilation to other markup languages; it doesn't work for syntax
highlighting, which is what I'm more interested in.

I ended up writing my own in Objective-C. It's not very pretty, and it doesn't
use a formal grammar (just a lexer + custom grammar code), but it does the
trick. I took a few liberties with the spec: throwing in GitHub-flavored code
blocks.

<https://gist.github.com/29dabe4b6e762ee221df>

[1]: <http://getmacchiato.com/>

~~~
naner
Did you know of Discount[1]? Reddit switched to that from markdown.py a couple
years ago. It is written in C and BSD licensed.

1: <http://www.pell.portland.or.us/~orc/Code/discount/>

~~~
Evbn
I fixed a bug in discount-for-Reddit once. It is some of the cryptic C one
sees.

------
StavrosK
I'm not that psyched about automatic return-based linebreaks. Everyone thinks
they should use linebreaks to align their text, and the system should just
ignore all single line breaks.

The current behavior of Markdown solves this problem very well. I don't want
the newlines I enter for non-wrapping editors to remain in the generated HTML.

~~~
dfbrown
I agree, I am having trouble thinking of a situation where specific line break
positions would be important to me in regular text that isn't covered by some
other markdown structure such as code blocks or lists.

~~~
stan_rogers
One word: poetry. Traditional break behaviour (new para) is great between
stanzas/verses; not so much between lines. (It's also the primary reason why
the <br> tag still exists in HTML.)

~~~
graue
If you end a line with two spaces, the line break after it is kept. Not
intuitive, sure, but it works.

Perhaps an alternative "profile" could be specified that preserves all line
breaks, and sites focused on poetry or song lyrics could use that profile.

~~~
stickfigure
That hidden feature is so thoroughly buried that I didn't even know about it
until I read your msg - and I've been writing markdown for years. For
mainstream users, it might as well not exist.

Thanks, btw :)

------
wreel
I found that I've moved on to reStructuredText. It doesn't seem to be marketed
as much as Markdown (the only reason I know about it is because of Sphinx) but
I feel that it's a bit more capable. Simple tables are exceptionally easy and
it handles URLs with parens in it just fine (a common pain when trying to link
to Wikipedia articles with Markdown).

~~~
rogerbinns
I use rst for everything due to using Sphinx heavily. Trivial tables are easy
in any markup, but non-trivial ones are a pain. I use table mode in emacs, but
we can't require everyone to use emacs.

I hate its URL handling.

And of course it needed Sphinx to make it work across more than one source
file which means we now have two dialects.

I do wish everyone would just agree on one syntax and be done with it.

~~~
tadhg
Regarding the URL handling, I also used to hate it, but wrote a tool to make
it easier to deal with; details are here if you're interested (despite the
title, the relevant tool is not Vim-only):
<[http://tadhg.com/wp/2012/10/07/tools-for-writing-
restructure...](http://tadhg.com/wp/2012/10/07/tools-for-writing-
restructuredtext-in-vim/#restructuredtext-references>);

~~~
rogerbinns
The bit I hate is that I have no desire to have a global list of URLs and
manage them. So instead I have to put a double underscore suffix after every
url otherwise you get bizarre error messages. eg `foo <foo.com>`__

------
eob
As a heavy LaTeX user (phd student; can't escape it), I'm convinced that there
is a small enough subset of LaTeX that actually gets used day-to-day that
someone could figure out a way to shim it into something like Markdown.

And then, for the LaTeX that you can't shim in, just have some escape hatch
that sends fragments out to a renderer. If I could only have:

    
    
        * Math mode
        * Citations and Bib files
        * Labels and References
    

Then I'd be willing to go through a lot of extra pain to get all the weird
tables and precise image placements that are inevitable in a 2-column ACM
format.

EDIT: Having just investigated Pandoc, which many here are talking about, I
realize this might be exactly what I've been looking for :)

~~~
bookweevil
Have you tried reStructuredText?

rst2latex has worked very well for me. The current version has math mode. I've
occasionally had to write some custom LaTeX to get things like natbib to work,
but it's largely been problem-free.

------
zrail
(shameless plug) I wrapped Pandoc[1] in a web service and added on nice PDF
exports and called it Docverter[2]. It will convert basically anything plain-
text, including Markdown, into almost anything else plaintext, HTML, RTF or
Docx. I also added rich PDF exports that go through a HTML intermediary.

If this gains some traction I'm sure I'll be adding support for it at some
point.

[1]: a wonderful almost-everything-to-everything text converter
<http://johnmacfarlane.net/pandoc/>

[2]: <http://www.docverter.com>

------
engtech
From the comments on the blog:

    
    
       "I'm reminded of the guy who decides that there should be 
        one standard because there are n divergent implementations. 
    
        So he goes and writes his own. Now there are n+1 divergent implementations."
    

That is probably the most likely outcome, but kudos to Jeff for trying.

The idea of Markdown is great, but I found the implementation of links is less
than obvious. (haven't tried it in 4 years, so there was probably other issues
that I had that I've forgotten)

The problem I inherently always end up having with "parses to HTML" syntax
conventions is there are always warts where the syntax is harder to remember
than the HTML it is supposed to parse to.

~~~
fusiongyro
You can hardly blame links for that. There was no widespread hypertext format
before HTML for conventional renderings to appear in. Most of the rest of
Markdown has analogues in earlier plain text formats and is fairly visually
suggestive.

Common Lisp managed to unite several divergent implementations of Lisp
(MacLisp, InterLisp, Lisp Machine Lisp, etc.) under a single common
specification. This was possible because the Common Lisp standard was not
created by some third-party out of dissatisfaction with the other guy's stuff
but by significant representatives from all the big camps. The desire was for
better interoperability, not imposing ideals on the competition.

I think this effort, if Gruber supports it, is likely to succeed simply by
incorporating most of the community. In fact, it could be even easier, because
one of the principle motivators for the divergent implementations of Markdown
is simply to create concrete specs around a concrete grammar. This doesn't
mean there won't be divergences (Scheme, Clojure, OpenLisp, etc.) it just
means that those divergences will be principled ("we reject the size", "we
desire modern FP techniques") rather than accidental ("we used this regex
instead of that to tokenize emphasized text").

------
antirez
I love Markdown, and I hate Markdown.

I love it because the world needs an easy-for-humans way to format in pure
ASCII without any tool. It is much simpler than using even the most well
designed GUI. You can even write books with it, and you can focus on content.

But I hate Markdown. I hate it because it is superficially good: a lot of
Markdown seems to make sense at a first glance, but if you look at it more
closely you see that a lot is broken in its design (IMHO the fact that the
reference implementation is broken is the minor of the issues).

It is surely possible to fix it. However it's better to have a broken Markdown
now that no markdown at all. The fact that Github and Stack Overflow and
Reddit are using it makes it absolutely obvious how useful and great the
_concept_ is. The actual design, implementation, and specifications can be
fixed now. So kudos to the original inventor, but it needs a second pass from
people that can give it a more coherent shape, with clear behavior, minor
surprise, and parsing in mind.

~~~
blacksmythe
Markdown is fantastic as a first draft of something, when you want to focus
almost solely on content.

For subsequent revisions, it makes far less difference to me what format the
text is in.

(edit: for that reason any deficiencies in Markdown don't bother me)

------
christiangenco
Why not just move to Pandoc[1]?

1\. <http://johnmacfarlane.net/pandoc/>

~~~
Ingaz
Why not just move to docutils?

------
_pdeschen
A BNF grammar would be nice to start with.

IMHO, pandoc markdown support is the mother of all implement featuring lots of
goodies (table and footnote to name 2)

~~~
swah
I convinced my team to use pandoc instead of Word for documenting a new
project, and now, because creating tables is so hard (they are not like Emacs
users), I'm considering lobbying them back to Word, or writing a preprocessor
to insert tables from CSV files... feels bad man.

~~~
_pdeschen
[https://raw.github.com/gist/3956665/d549ea53817335c868e750ca...](https://raw.github.com/gist/3956665/d549ea53817335c868e750ca6a29ee20b958eec1/Table.md)

How can this be harder than creating table with Word? Word always gets in the
way. Word _appears_ to be easier but down the road, it always end up as a
painful process.

For me just the benefit of being mergable and delegating styling at the end of
the tool chain is just plain great.

<http://johnmacfarlane.net/pandoc/README.html#tables>

Edit: rendering issues!

~~~
swah
Well, add a last row with the first column larger than the previous rows,
assume people don't know about column-mode editing, and you can imagine what
they are doing to align...

I think I'll just "preprocess" the file, looking for something like
!csvtable(filename.csv).

~~~
swah
\--- End of the story ---

Wrote the script (it worked), but some specific complex features from Word
still were missed ("how do I do a reference to a picture?") and couldn't be
easily supported by pandoc or this script.

Though for a brief time of going full-mode procrastinator and writing another
markup language...

Then I had to admit the whole thing wasn't really working and now _recommend_
we move back to Microsoft Word because it's _easier_.

A day of Total fail, and procrastination, and making everyone install MikTex,
pandoc and Python.

I hope I don't regret for suggesting we use Git...

------
starpilot
It'd be nice if it Markdown was added to HN, at least for a consistent way of
quoting that's better than using the code tag (which frequently cuts off text
for some reason in mobile Safari).

~~~
philh
> (which frequently cuts off text for some reason in mobile Safari).

Is this just because it doesn't wrap, and mobile safari doesn't display a
scrollbar? (I've never used mobile safari, but I think that's true of the
Android browser.)

Quoting with code blocks can be awful, but > is fine even if it's not
explicitly formatted.

~~~
thedufer
> Is this just because it doesn't wrap, and mobile safari doesn't display a
> scrollbar?

Pretty sure that's it. OS X (Safari and Chrome, at least) does the same thing
unless you have a mouse plugged in. The formatting is such that it doesn't
feel like it should scroll, even in the common case of characters being cut in
half. Better styling on code blocks would do wonders for this.

------
kbd
Here's hoping they can finally work natural _underline_ support in...

Edit: I've wondered whether the original Markdown didn't have underline
support because <u> was deprecated/removed from HTML. FWIW, <u> is now back in
HTML5.

~~~
phreakhead
Underlines traditionally have semantically meant the same as italics. When an
editor wanted the printer to make a certain word italic, he would underline it
in the draft.

Really, underlines are a useless decoration. That's why HTML took them out.
Not sure why they put them back in...

~~~
stan_rogers
The primary reason is to provide for Chinese proper name marks (where
underlining has a semantic meaning) and occasionally for misspellings (in
English, we'd probably add the editorial text _[sic]_ ). As a decoration, it
is useless, but there are circumstances where it has semantic meaning. (The
<b> and <i> tags were promoted back to respectability for the same reasons,
since using <em> for text that is not stressed or <strong> for text that would
traditionally be bolded without implying extra importance is just as
semantically incorrect as using <i> and <b> for stress and importance would
be. Arbitrary spans don't imply any semantic meaning. Where I would have used
<span class="foreign" lang="fr"> previously, I'd now use <i class="foreign"
lang="fr">. The <i> tag marks the text as special rather than just arbitrarily
styled.)

~~~
masklinn
> The primary reason is to provide for Chinese proper name marks

That's an improper use, you want {COMBINING LOW LINE} U+0332 for that.

------
juliangamble
What is the canonical implementation of markdown?

> The problem with writing my own Markdown parser in Clojure is that Markdown
> is not a well-specified language. There is no "official" grammar, just an
> informal "Here's how it works" description and a really ugly reference
> implementation in Perl. <http://briancarper.net/blog/415/>

[http://stackoverflow.com/questions/7307480/what-is-the-
canon...](http://stackoverflow.com/questions/7307480/what-is-the-canonical-
implementation-of-markdown)

------
nickpresta
I really like the Mou text editor for Markdown: <http://mouapp.com/>

Mou + the (built in) Github theme = best Markdown editing experience.

------
dysoco
As a non-web developer I cry every time I need to use HTML: It's really "ugly"
in some way (And I'm used to ugly languages).

But I have learned to love Markdown too, I hope in the future, distant future:
Someone will create a language that integrates HTML and CSS into a nice
Markdown-like language.

~~~
TazeTSchnitzel
HTML ugly? Nonsense.

    
    
      <!doctype html>
      <meta charset=utf-8>
      <title>Hello, world</title>
    
      <h1>Hello, world</h1>
      <p>This is a paragraph about HTML.
      <ul>
        <li>Bullet point
        <li>Bullet point
      </ul>
    

That's not ugly.

~~~
randomchars
Wait, not closing <p> and <li> is valid?

~~~
TazeTSchnitzel
Completely. You can, with a doctype, also omit <html>, <head> and <body>, too.

Not closing <li> is good, but I'd avoid it for <p>.

------
nkwiatek
I'm not a huge fan of the current Markdown mark. I'd encourage the creator
(dcurtis) to push it, because currently it feels like a first-stage idea — or
perhaps, an execution without an idea at all.

There are many questions — "What is Markdown?", for starters — that feel
unaddressed by the mark. Instead, we get the brute force approach: splitting
up the word into smaller word parts, which is what you do with a word if you
don't know what it means, or you have to gesture it in Charades.

Rather uninspiring for an idea so beautiful that Jeff and others can get so
excited just thinking about it, but what else can you expect from such a mark
whose approach is so stubbornly literal? I take that back — only one word part
actually gets to be represented literally... the other only managed to become
a letter, in a moment I can only imagine involved the creator muttering "good
enough". He must have found this mark uninspiring as well, given that he
sought to put a box around it.

At least consider that the down arrow on its own is an overloaded concept,
particularly on the web. Without context — and a mark should not need context
— M↓ could read like a hotkey or command of some kind. This kind of ambiguity
is utterly unnecessary — you're making a mark; it can be whatever you want it
to be. Push!

------
olalonde
What I really miss in Gruber's markdown is a way to hint syntax highlighting.
For example, on Github:

    
    
        ```javascript
        alert('woohoo');
        ```

~~~
bergie
There was some discussion about allowing even more metadata than just the
syntax highlighting hint for fenced code blocks in the Literate CoffeeScript
thread:

<https://news.ycombinator.com/item?id=4608165>

------
antidaily
I can't be the only one who loathes Markdown.

~~~
citricsquid
What's the reasoning behind your loathing?

~~~
ScottBurson
I can't speculate on antidaily's reasoning, but I can tell you why I don't
like this way of doing markup. (I thought _I_ was the last one.)

First is the lack of standardization. Asterisks traditionally meant boldface,
I thought, but in some of these systems they mean italics. Some use
underscores for italics, while others use slashes. And those are just the
common conventions; the less frequently used ones tend to be even less
standardized.

Second is the fact that the more conventions these languages implement, the
more likely I am to emit one unintentionally, and then have to figure out how
to escape the input so it's treated literally, if the language even supports
that. (Note for instance the long-standing Lisp convention of putting
asterisks around special variable names.)

Thirdly, the syntax rules of these languages are often ill-specified and
incorrectly implemented, making it difficult to tell at times how to get the
effect I want.

EDITED to add: if you're wondering what I would suggest as an alternative to
Markdown-style markup, this is an example of the kind of thing I prefer:
[http://nbsp.io/development/doccy-a-mid-weight-markup-
languag...](http://nbsp.io/development/doccy-a-mid-weight-markup-language)

The syntax is uniform, but much easier to type than bare HTML.

------
matthewowen
If you've ever been involved in producing content management systems for non-
technical users (typically involving TinyMCE/CKEditor etc etc) then you'll
probably welcome this as much as I do.

Dodgy HTML, content pasted in from Word (with crazy styling intact), and a
general encouragement for users to see text content in terms of styling rather
than structure are all things that it will be delightful to see the end of.

------
kibwen
How would one go about taking a project with a large corpus of non-standard
markdown (e.g. Github, Reddit) and converting it to any standardized form,
assuming that a standard is chosen that is not 100% backwards-compatible with
all existing markdown flavors?

I don't think such a thing is feasible. I _also_ don't think it's feasible for
any proposed standard to simply look at the largest users and say "okay, we'll
accept the idiosyncratic extensions of all of these differing flavors in an
unambiguous way."

So assuming this pushes forward, there are (to my mind) two possible outcomes:

1) A backwards-incompatible standard emerges. No existing project adopts it,
but new projects do. It gains legitimacy only once Github, Reddit, et al fade
into obscurity.

2) A backwards-compatible standard emerges. Every large existing project
adopts it, but the standard is so full of cruft and TIMTOWTDI that in ten
years it gets usurped entirely by a challenger that emphasizes simplicity.

~~~
vilhelm_s
For Reddit, I would use the new parser for comments written after the upgrade
and the old parser for comments written before the upgrade. Note that Reddit
already puts post that are older then a month or so into a "frozen" archive
mode where they can not be further modified, so after a month the old parser
could be thrown away completely.

Not sure what to do about Github.

------
ianstormtaylor
It has always bothered me that _text_ is not underlined text, but italicized
text. Why not /text/ for italicized text. It shows exactly what it is doing.
And _text_ for bold text.

I also see no reason for _text_ and _text_ to produce the same output. It just
seems like a fault in the original spec to me.

~~~
uvtc
I think the reasons for those choices are:

* It's very uncommon to want your output text actually underlined.

* If you really do want underlining, just use <u>this</u>, since it's fine to put raw html in Markdown source.

* The most common way folks express emphasis is probably with ✱asterisks✱ (HN won't let me backslash-escape the *). A less-common alternative is to use _underscores_ (though I rarely see that anymore these days). Maybe the distant third most-common way was with /slashes/. I guess Gruber had to draw the line somewhere and just support the first two most common ways to write it. That seems reasonable.

Another reason to not use slashes for emphasis: using them might interfere (or
at least cause headaches) with writing directory names, fractions 1/2, and
"and/or" wordings.

------
jacobr
In a comment area (like on HN) it rarely makes sense to be able to add
headings. Could some features of the specification be optional, so that a
parser can be conforming even if it disabled those features?

Are there any parsers (preferably in JavaScript) which currently let you
toggle features like that?

------
kickingvegas
So, pulling an old man card: creating a formal spec for Markdown paves the way
for adding more syntax which negates the main benefit of it: a lay person can
interpret Markdown as a text file. If you want to add more syntax, we are
better off using/extending LaTeX or troff.

------
buster
Is there a reason why i should prefer Markdown over restructuredText? rst sems
to me has all i need, it has specs, it has decent documentation, it has tools,
it's not only used to output HTML but all kinds of stuff.

rst just looks more powerful and yet still as readable as markdown.

~~~
gthank
Having used them both a fair bit (though not to write novels, like some of the
people on here): Markdown source is prettier to look at. This might seem
minor, but it's the primary goal of Markdown. If I'm writing something highly
technical, I prefer RST; if I'm writing something closer to plain English, I
prefer Markdown.

------
jlongster
I'm excited about this too. I just wrote a blogging engine for node that
allows you to edit posts in a web-based editor:

[http://jlongster.com/edit/Introducing-Nunjucks,-a-Better-
Jav...](http://jlongster.com/edit/Introducing-Nunjucks,-a-Better-Javascript-
Templating-System?redirected=true)

I absolutely love the simplicity of Markdown, especially with github's
addition of code fences/blocks. It's so trival now to add code and have it
automatically highlighted. It's not nearly that simple in other formats (to
get autohighlighting I guess).

Excited to see what will come of this.

~~~
tomjen3
That site is broken on my android phone in chrome. Each time I scroll it moves
back. WTF

~~~
jlongster
It's probably the Ace Editor. Not really built for mobile phones.

------
TazeTSchnitzel
OK. But please fix one thing first:

    
    
      1. hello
      something
      2. foobar
    

Should not render as:

    
    
      1. hello
      something
      1. foobar
    

There's the start= attribute for <ol>, at least use it!

------
lmm
All three of the "gotcha" changes suggested here are wrong, and changing them
would kill what makes markdown great.

The one change for good I can think of would be removing the ability to embed
HTML.

------
Tloewald
If it were up to me, I'd simply ask that markdown add support for h3 (other
than hashes, e.g. Underline with hyphen and spaces) -- two levels of headings
is all too frequently insufficient, inline links to images be rendered as
image tags, inline links to videos etc. likewise become video tags, etc., the
way other inline links become anchor links, and some form of table support be
standardized.

Aside from that (and implementation bugs) I've been very happy with markdown.

~~~
WickyNilliams
You can have any number of heading levels. Instead of Doing this:

    
    
        Heading 1
        =========
    
        Heading 2
        ---------
    

Do this:

    
    
        #Heading 1
    
        ##Heading 2
    
        ###Heading 3
    
        ####Etc.
    

Edit: formatting

~~~
Tloewald
I know about hashes -- read my post.

------
blackstag
I love markdown. I even created my own version which I have become addicted to
-> <http://blackstag.com/markdown>. I'm fairly confident I will be the only
one to appreciate my personal version, but hey - It's the ugly child I have
come to love.

I'd certainly be interested in switching over to their version, provided some
of the noted kinks get worked out.

------
jiyinyiyong
Read this if you use Markdown alongwith Chinese: <http://ruby-
china.org/topics/6335>

------
zeitg3ist
Didn't Gruber co-design Markdown with Aaron Swartz[1][2]? Is there any reason
why everyone refers to Gruber as Markdown's sole inventor/BDFL? What's Swartz
opinion on all this?

[1] <http://www.aaronsw.com/weblog/001189> [2]
<http://en.wikipedia.org/wiki/Markdown>

------
ChuckMcM
This would be so freakin' great. Would especially love a couple of the github
things in there like '''lang that would totally be awesome.

~~~
bmuon
This illustrates the need for the Markdown language to be open to extensions.
For instance I'd like to write TeX blocks that render to MathML.

------
ddlatham
If everyone gets on board, great.

If only a couple sites band together, then I see it more like this:

<http://xkcd.com/927/>

------
TeMPOraL
Somebody please make a web-usable of Org Mode the language; it's like
Markdown, but older, richer in features (while being as simple as Markdown)
and is in daily use by many hackers for note taking, outlining, TODOs,
organizing your life, etc.

I'm very happy that GitHub has an Org Mode renderer, even if rudimentary - I
don't have to rewrite my notes and READMEs to Markdown.

~~~
unimpressive
> I'm very happy that GitHub has an Org Mode renderer, even if rudimentary - I
> don't have to rewrite my notes and READMEs to Markdown.

For that situation, wouldn't a org mode to markdown _converter_ be more
useful?

------
jeffio
We recently added Markdown as an option in our hosted reseller CMS (YikeSite)
in hopes that some of our customers would choose it over the WYSIWYG editor.

You can play with it here: <http://www.markdowncms.com>

If there was a standardized Markdown, we would implement that for sure.

------
dhaivatpandya
I love Markdown, and, this is an awesome effort! I'm working on a Markdown
editor/platform that could really benefit if this sort of stuff wasn't so
fragmented: <http://www.nimblenot.es/> (yes, that was a shameless plug)

------
adam-p
And if you like Markdown... I wrote a Chrome/Firefox/Thunderbird extension
that lets you write email in MD and then render it before sending:
<https://github.com/adam-p/markdown-here>

Enjoy.

------
madrona
Multiline support, please.

------
MatthewPhillips
This is one of the reasons I've never bought into the Markdown hype and
generally avoid using it. Semantic HTML5 tags makes to-HTML compiled languages
mostly unnecessary.

~~~
halostatue
…if you're a geek.

Most people don't need to or want to think about it.

Markdown is easily understandable by my wife (and we're using it to format her
novels), and she doesn't have _time_ to learn something ultimately as
irrelevant to her is a format that makes a computer program happy.

~~~
voyou
What is Markdown, though, if not "a format which makes a computer program
happy"? Presumably, your wife was already familiar with standard typographical
conventions like italics for emphasis and indents to start paragraphs. A good
text processing system for a computer should let the user deal with these
conventions, rather than having to learn a markup system. I'd be interested to
hear why you and your wife decided to use Markdown, and what alternatives you
considered and rejected.

~~~
halostatue
The other alternatives were essentially opaque formats (e.g., Word or Pages)
that when she & I talked about them and the amount of work that I needed to
do, she agreed.

She also _writes_ long hand, so this is a minor adaptation for her to write
like she does with emails.

The changes suggested are less natural for most people, and HTML is line noise
to most people. If she _had_ to learn HTML, my wife could do so—but it isn't
necessary for her to learn HTML. It's also easier for _me_ to have to worry
about clean-up than her to do so.

We do have points where we have to figure out how to make certain things work
(when she has lyrics, that requires a little more massaging on my part—but I
insert the bafflegab bit and she just knows to edit around it or inside it).

It isn't perfect, but the results look very good. (In fact, the second novel
looks better than the first, which was laid out in Pages and took me three
times as long as learning LaTeX to format the second novel. The only problem
with the second novel was finding a good font for the PDF version we use as a
print-ready copy.)

------
DanBC
Please please use <> to delimit URLs instead of ().

This is an [example
link]<[http://www.example.com/>](http://www.example.com/>);

~~~
phreakhead
This would completely defeat one of the best parts of markdown, which is the
ability to mix in HTML tags whenever you want, when you need to represent
something more complex.

------
alexchamberlain
An effort appears to have been started on <http://markdown.github.com/>.

------
happypeter
Markdown is really a important part of my life now, YES, it will be super cool
that the world can have one single spec for it.

------
twodayslate
What is wrong with bbcode? All the forums use it. Why are there so many
alternatives for these things?

~~~
citricsquid
I manage a large forum and we use BBCode. I recently "open sourced" our rules
(<https://github.com/minecraftforum/rules>) and during building the system you
see there I made the decision to opt to use Markdown over BBCode -- what
everyone that uses the forum is used to.

BBCode isn't inherently "bad" if you're just writing something and won't ever
edit it again but for anything that you will need to edit / review in the
future it can be a serious pain in the ass to look through.

These are the two examples I used:

    
    
        ### Title here
        This is some text [with a url](http://google.com) 
    

vs.

    
    
        [size=6][font=arial, helvetica, sans-serif]Title here[/font][/size]
        This is some text [url="http://google.com"]with a url[/url]
    

BBCode was written to be written, it's no more difficult to write

    
    
        [url=http://google.com]google[/url]
    

than it is to write:

    
    
        [google](http://google.com)
    

but when _reading_ the source (for maintaining) it... sucks, because it feels
un-natural. With the Markdown version of linking (to pick a basic example) you
can read a sentence how the person reading the processed version would read
it:

    
    
        A search engine called [google](http://google.com)
    

That reads as "A search engine called google" and then you see that google is
a hyperlink. With BBCode it would read:

    
    
        A search engine called [url=http://google.com]google[/url]
    

So first you read "A search engine called" then you see it's a URL and then
you see "google". It can get very frustrating when you're looking at huge
swathes of text written in a similar style.

~~~
twodayslate
This is an excellent answer! Thank you!

------
variedthoughts
I just like that there is a discussion going on. I'd like a spec. And one that
can grow

------
saosebastiao
Please, please, please include a specification for table creation

~~~
Ingaz
docutils have this

------
donnfelker
More Atwood link bait.

------
lorenzfx
what I really miss from markdown (and even more from reStructuredText because
I actually use it a lot) is strikethrough (which github does support)

~~~
uvtc
FYI, Pandoc uses ~~two tildes~~ for strikeout syntax.

------
rsl7
yup. i'm there.

------
DannoHung
ALIGNMENT SYNTAX

