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.<p>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: <a href="http://blog.reddit.com/2009/09/we-had-some-bugs-and-it-hurt-us.html" rel="nofollow">http://blog.reddit.com/2009/09/we-had-some-bugs-and-it-hurt-...</a><p>See the changelog for what started as a PHP transliteration and turned into a rewrite that squashed 125 (!) unacknowledged bugs: <a href="http://michelf.com/projects/php-markdown/" rel="nofollow">http://michelf.com/projects/php-markdown/</a><p>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.
Wow, I wasn't expecting my email to Jeff to end up as a front-page blog post!<p>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 <i>does</i> 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.<p>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.<p>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.<p>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.
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.<p>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 :-().<p>I hope that doesn't become the default.
I'd also advocate for accepting reversed ()[]'s on links.<p>In other words, let the user type:<p><pre><code> [something](http://whatever.com)
</code></pre>
or<p><pre><code> (something)[http://whatever.com]
</code></pre>
...and have both work exactly the same.<p>It will save a lot of trouble -- and especially when linking to a Wikipedia page whose URL contains parentheses.
Why?<p>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.<p>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'.
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.<p>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.<p>[1] <a href="http://johnmacfarlane.net/pandoc/README.html" rel="nofollow">http://johnmacfarlane.net/pandoc/README.html</a><p>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% :)<p><a href="https://github.com/jgm/pandoc/issues/519" rel="nofollow">https://github.com/jgm/pandoc/issues/519</a>
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.<p>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.<p><a href="https://gist.github.com/29dabe4b6e762ee221df" rel="nofollow">https://gist.github.com/29dabe4b6e762ee221df</a><p>[1]: <a href="http://getmacchiato.com/" rel="nofollow">http://getmacchiato.com/</a>
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.<p>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.
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).
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.<p>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:<p><pre><code> * Math mode
* Citations and Bib files
* Labels and References
</code></pre>
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.<p>EDIT: Having just investigated Pandoc, which many here are talking about, I realize this might be exactly what I've been looking for :)
(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.<p>If this gains some traction I'm sure I'll be adding support for it at some point.<p>[1]: a wonderful almost-everything-to-everything text converter <a href="http://johnmacfarlane.net/pandoc/" rel="nofollow">http://johnmacfarlane.net/pandoc/</a><p>[2]: <a href="http://www.docverter.com" rel="nofollow">http://www.docverter.com</a>
From the comments on the blog:<p><pre><code> "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."
</code></pre>
That is probably the most likely outcome, but kudos to Jeff for trying.<p>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)<p>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.
I love Markdown, and I hate Markdown.<p>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.<p>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).<p>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 <i>concept</i> 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.
A BNF grammar would be nice to start with.<p>IMHO, pandoc markdown support is the mother of all implement featuring lots of goodies (table and footnote to name 2)
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).
Here's hoping they can finally work natural _underline_ support in...<p>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.
What is the canonical implementation of markdown?<p>> 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. <a href="http://briancarper.net/blog/415/" rel="nofollow">http://briancarper.net/blog/415/</a><p><a href="http://stackoverflow.com/questions/7307480/what-is-the-canonical-implementation-of-markdown" rel="nofollow">http://stackoverflow.com/questions/7307480/what-is-the-canon...</a>
I really like the Mou text editor for Markdown: <a href="http://mouapp.com/" rel="nofollow">http://mouapp.com/</a><p>Mou + the (built in) Github theme = best Markdown editing experience.
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).<p>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.
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.<p>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.<p>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.<p>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!
What I really miss in Gruber's markdown is a way to hint syntax highlighting. For example, on Github:<p><pre><code> ```javascript
alert('woohoo');
```</code></pre>
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.<p>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.
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?<p>I don't think such a thing is feasible. I <i>also</i> 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."<p>So assuming this pushes forward, there are (to my mind) two possible outcomes:<p>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.<p>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.
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 <i>text</i> for bold text.<p>I also see no reason for <i>text</i> and _text_ to produce the same output. It just seems like a fault in the original spec to me.
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?<p>Are there any parsers (preferably in JavaScript) which currently let you toggle features like that?
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.
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.<p>rst just looks more powerful and yet still as readable as markdown.
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:<p><a href="http://jlongster.com/edit/Introducing-Nunjucks,-a-Better-Javascript-Templating-System?redirected=true" rel="nofollow">http://jlongster.com/edit/Introducing-Nunjucks,-a-Better-Jav...</a><p>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).<p>Excited to see what will come of this.
OK. But please fix one thing first:<p><pre><code> 1. hello
something
2. foobar
</code></pre>
Should not render as:<p><pre><code> 1. hello
something
1. foobar
</code></pre>
There's the start= attribute for <ol>, at least use it!
All three of the "gotcha" changes suggested here are wrong, and changing them would kill what makes markdown great.<p>The one change for good I can think of would be removing the ability to embed HTML.
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.<p>Aside from that (and implementation bugs) I've been very happy with markdown.
I love markdown. I even created my own version which I have become addicted to -> <a href="http://blackstag.com/markdown" rel="nofollow">http://blackstag.com/markdown</a>. 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.<p>I'd certainly be interested in switching over to their version, provided some of the noted kinks get worked out.
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?<p>[1] <a href="http://www.aaronsw.com/weblog/001189" rel="nofollow">http://www.aaronsw.com/weblog/001189</a>
[2] <a href="http://en.wikipedia.org/wiki/Markdown" rel="nofollow">http://en.wikipedia.org/wiki/Markdown</a>
If everyone gets on board, great.<p>If only a couple sites band together, then I see it more like this:<p><a href="http://xkcd.com/927/" rel="nofollow">http://xkcd.com/927/</a>
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.<p>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.
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.<p>You can play with it here: <a href="http://www.markdowncms.com" rel="nofollow">http://www.markdowncms.com</a><p>If there was a standardized Markdown, we would implement that for sure.
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: <a href="http://www.nimblenot.es/" rel="nofollow">http://www.nimblenot.es/</a> (yes, that was a shameless plug)
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: <a href="https://github.com/adam-p/markdown-here" rel="nofollow">https://github.com/adam-p/markdown-here</a><p>Enjoy.
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.
Please please use <> to delimit URLs instead of ().<p>This is an [example link]<<a href="http://www.example.com/>" rel="nofollow">http://www.example.com/></a>;