Hacker News new | comments | show | ask | jobs | submit login
Standard Markdown (standardmarkdown.com)
1167 points by hglaser 1117 days ago | hide | past | web | 366 comments | favorite

This is really great, but I don’t understand why everything has been made privately. Following the first post [1], people were waiting for a move, and as far as I know, it was a complete silence during two years, not even a “we are working on it”.

A Markdown Community Group [2] has been created on w3.org, and people have started to push some effort in it [3][4][5], but it has been totally ignored since the beginning, despite the communication attempts.

Maybe I don’t have all the informations, but it looks like a waste to me, and I find it disrespectful for the people who worked on the project. All of this could have easily been avoided with a simple communication about the status of the project.

[1] http://blog.codinghorror.com/the-future-of-markdown/

[2] http://www.w3.org/community/markdown/

[3] http://www.w3.org/community/markdown/wiki/Main_Page

[4] http://lists.w3.org/Archives/Public/public-markdown/2014Mar/...

[5] http://lists.w3.org/Archives/Public/public-markdown/2014Jul/...

I think you make an excellent and valid point.

On the flip side, developing a spec---for something as popular and accessible as Markdown---out in the open is an extraordinarily difficult task. I think one can definitely make a case for it being the right thing to do (and I mean that in more than just the ethical sense), but I also think one can make a reasonable case for not wanting to travel down that road either. I think it can be so difficult that there would be a very real possibility that it would never get completed.

(I'm sincerely not trying to be combative. I know I'm not really addressing your point---that they didn't even provide a status update---but I just wanted to provide a tiny perspective on the other side of the coin.)

I definitely see your point of view. Design by committee is enough to wear down the most passionate person. However, maybe they could have said a simple "We're actually working on a spec and two portable implementations (JS, C) based on the original article," and that might have gone a long way to prevent people from wasting their time.

But they tried to contact the guy and never obtained an answer. I'd vote to call it MarkAbove!

They've also unfairly appropriated the name "Markdown" and declared it "Standard", which Gruber is (rightly) not too happy with.[0][1]

[0] https://twitter.com/justin/status/507304506007515136

[1] https://twitter.com/markdown/status/507341395137658880

I can understand his point of view on the matter. He created something that is loved by millions, and he feels that this project is trying to wrestle ownership from him.

On the other hand, he created something. He released it to the wild, and then he didn't aptly respond to the need for it to change. His response to "Markdown needs work" is basically "Whatever! It's my project, you're not the boss of me!" How can he seriously be shocked that people would go around him to try and develop a spec that made more sense?

As to using "Standard" in the name, if Reddit, StackExchange, and Github all agree to use this Markdown spec, I think that there could be a reasonable argument that it is standard. In reality, they are wrestling ownership of Markdown away from Gruber. In a couple of years Gruber's Markdown will probably only be useful for historical purposes. Why? Because he failed to respond to the real needs of his users, so those users with the largest stake took matters into their own hands.

He's not shocked, he's upset something is calling itself "Standard Markdown" yet he, the creator of Markdown, did not have any involvement.

There's nothing wrong with making a standard, just don't appropriate the name.

> just don't appropriate the name

So, is it the use of "Standard" or "Markdown" that's the issue here? I don't see people complaining that "MultiMarkdown" is appropriating the name, for example.

"Standard". I don't think Gruber has a problem with "GitHub-flavoured Markdown".

But he was asked to participate and didn't want to. It is not as if they did the work in secret.

It doesn't matter that he was asked to participate and didn't want to. What matters is whether he did or didn't give specific written permission that they could use the name Markdown. It's set in stone on the license.

> What matters is whether he did or didn't give specific written permission that they could use the name Markdown. It's set in stone on the license.

If you're going to paste the very same argument multiple times all over this discussion, you should at least first make sure it is correct.

It's been explained several times now that this is not how that license works. It doesn't work (not binding) to specify trademark-related things in a copyright license. And anyway a copyright license only affects those bound by the copyright on the work: The work, being the code of Gruber's perl markdown parser. Which this group hasn't used at all. Usage of the name "Markdown" is something which has nothing to do with copyright but trademark law. Trademark law works very differently, definitely not by just writing up a license (like copyright) and simply said: The name Markdown is not trademarked (currently, and given its usage, also probably not in the future).

The license is to a specific work of software and applies to derivative works of it only.

Naming conventions specified in the software license don't apply to 1) non-software works such as a spec or 2) independently derived software works.

There's a great deal else concerning copyright/trademark confusion here: https://news.ycombinator.com/item?id=8271548

> It's set in stone on the license.

Markdown-related projects have been using "Markdown" in the name for years (in violation of the license). Gruber has yet to get upset at "Github flavored Markdown" or "MultiMarkdown" for example. Methinks that it has less to do with the name, and more to do with their motive of becoming the new de facto Markdown spec that has Gruber up-in-arms.

   "github flavored markdown" sounds like a fork.
   "standard markdown" sounds like ownership. Not
   my project but shitty
"standard justin" on Twitter [1]

   That. Exactly that.
John Gruber in response to the above tweet [2]

[1] https://twitter.com/justin/status/507304506007515136

[2] https://twitter.com/gruber/status/507305771265454080

And that's his good right. Calling it "Standard Markdown" when he explicitly chose not to participate is just as childish a move as this: http://www.notmarkdown.com

There was an obvious, demonstrable need out there for implementation consistency. Gruber didn't step up to help resolve confusions, so he has no right to complain when other people do the hard work.

> There was an obvious, demonstrable need out there for implementation consistency.

I hear this sentiment a lot but I just find it unconvincing.

Over the past decade, Markdown became the lingua franca for transforming plain text to HTML. It did this entirely on the back of Gruber's spec, implementation, and the community that developed around the project. It hasn't had a formal spec this entire time and it's done just fine.

Are there some undefined behaviors in the original spec? Sure. But it was just designed to handle the most common situations, not everything.

While Markdown is certainly used widely and is based on Grubers original specification, the practical real-world usage is a lot more complicated that just relying on the original specification.

Reading Atwoods issues with original Markdown[1] (which is significant given his extensive experience in products that rely heavily on Markdown), it is quite clear that Markdown as a format has prospered almost in spite of the original specification.

[1] http://blog.codinghorror.com/the-future-of-markdown/

That's an argument in favor of them making a spec, not an argument in favor of them using the name "Standard Markdown."

They could have called it any number of other things that don't make the same claims that "Standard Markdown" does. Off the top of my head; Common Markdown, Clean Markdown, or better yet don't actually use the Markdown name, simply imply it such as Forkdown or Sporkdown.

Maybe they can call it "Standardized Markdown" which would be both more descriptive and accurate.

That doesn't really address the main objection to the name "Standard Markdown" unless you already know what the problem with the name is (and thus the implications of the slight difference.)

It would be best if the team would just go another route entirely.

To be honest, I think this industry wide devotion to Markdown is hilarious, since to me it's a pretty garbage way of solving an easily solved problem. The main/only thing in its favor is its ubiquity.

What percentage of all Markdown written is on GitHub, Reddit, or Stack Exchange? What percentage of rendered Markdown served to users is from those sites? Tough to estimate, but I would say it's certainly a majority. Surely any flavor of Markdown agreed upon by those sites can make a pretty strong case to be considered "standard."

Out of curiosity, what do you think is the better "easy" solution to the problem Markdown is trying to solve?

Standard implies "normal" or "default" as well as "standardised".

Whatever you may think of Markdown (that is markdown as created by Gruber), it surely isn't unreasonable to suggest that if any version can make that sort of claim, it should be the original.

How would "Common Markdown" be any better than "Standard Markdown"? Doesn't it sort of imply the same thing?

(btw I'm in the camp that thinks "Standard Markdown" is just fine, though I do hope they get the formal specs nailed down a bit more solidly on the ambiguities discussed upthreads, preferably with some kind of formal grammar)

To the people voting down, please explain why you disagree. I am genuinely interested.

Well taking something someone else created and rereleasing it using relatively the same name while insinuating it's the official or standard version is what's known in the industry as a dick move.

Imagine if you forked GTK and named it "Official GTK" and then blamed GTK for not doing what you wanted them to, so its obviously their fault that you needed to steal their name.

Imagine if you took a look at all the incompatible implementations of 1970's and 1980's C and blamed them for not being compatible, and created a fork called "ANSI C".

That'd totally suck, wouldn't it?

Generally with language standards though, the major players involved are all part of the standardization process. A slightly different example might be Microsoft developing an incompatible version of Java and calling it Java (until they got smacked into calling it J++ instead).

Honestly, I'm of the opinion that they can call it Standard Markdown if they want to and there's nothing wrong with that. Gruber's opinion is worth something for sure because of his authorship of the original, but there's a statute of limitations. He doesn't think Markdown needs anything more than his Perl script, but the rest of the internet has disagreed pretty strongly for long enough now that it's fine to treat him as absentee.

I realize that the "S" in ANSI stands for "Standards", but I think it is obvious to anyone who cares that the things which come from ANSI are produced by a non-profit national standards committee ( http://en.wikipedia.org/wiki/American_National_Standards_Ins... ). As the Wikipedia page says, ANSI "oversees the development of voluntary consensus standards for products, services, processes, systems, and personnel".

I don't really see this as a valid comparison to what the folks behind "Standard Markdown" are doing. I agree with others that the Standard Markdown name was a poor choice. For me at least, it feels like they are saying "We're taking over now". I don't know if that indeed was their intent, but that's the way it comes across to me. I think they should choose a different name.

For the record, I really don't have any skin in the game here, as the controversy doesn't really affect me much.

> I think it is obvious to anyone who cares that the things which come from ANSI are produced by a non-profit national standards committee

Which the "non-profit national standards committee" is just a collection of folks representing firms in the industries to which the standards apply.


Ha! Hadn’t heard of that number before.

Some background here for those interested: http://daemonforums.org/showthread.php?t=6563

And for those who don't follow links: this was the phone number advertised by BSD Unix, a fork of AT&T's Unix, when BSD launched its own commercial distribution.

The resulting legal battle came to be known as "the UNIX wars", and resulted in a legal finding that AT&T had little to no effective copyright ownership of the BSD codebase (a few minor files IIRC). This decision was issued under seal, later broken in the subsequent SCO vs. IBM lawsuit of the early 2000s.

The contretemps has been argued as among the reasons Linux emerged and became as popular as it is: it was a de novo, fully independent, largely POSIX-compliant reimplementation of the UNIX environment that was good enough for those who wanted that sort of thing.

It is kind of a dick move, and sadly this sort of thing (specifically, not respecting existing name usage) appears to be becoming more and more common. And sadly outrage from the community seems to be ineffective at preventing this stuff. Look at Google pilfering the name "Go" for their new programming language[1].

Yeah, it was a slightly different situation, but still, there was a name collision and in the end nothing was ever done about it.

[1]: https://code.google.com/p/go/issues/detail?id=9

I don't see how the two situations are similar at all.

Google didn't appropriate the syntax or standard for the original Go, they just used the same (extremely common) two letter word.

And I don't really see the problem there, there are a multitude of hobby and dead languages with names that may be duplicated in the future.

I don't see how you can not see that the two situations are similar. Note: similar, not identical. Google stole a name that was already being used in the exact same domain (programming language). Nobody said they borrowed the same syntax or anything, that isn't the point.

And I don't really see the problem there

And that is the problem. People don't care about somebody just coming along and arbitrarily usurping a name somebody else is already using. Of course they may see it differently one day when the shoe is on the other foot. But for now, there seems to be a trend where people don't care about resolving name collisions... and even more so if they're a rich entity like Google or Apple.

Apple and Swift.


Eh what? It has been industry practice for the last ten years to implement a Markdown parser and call it "Something Markdown" or "Markdown Something".

Standard Markdown is just that, it's Markdown but standardized. It's exactly the right name given what it does.

"Standard" carries with it a significant heft in meaning, especially authority, that "Something" else is unlikely to carry. Authority that is illegitimate without the original author's involvement.

I think the lack of the author's involvement in _anything_ in the last 10 years has cost him any authority he would have had.

Some names are descriptive, some are prescriptive. Just deal with it.

He told them no, which is still involvement.

He didn't get "involved", he just said get off my lawn!

Ouch! He's defintely not happy, but I think there needs to be some more structure around the format. I love using Markdown, but it's annoying finding out what quirks work on different parsers. For example, GitHub supports hyperlinked images, but Designer New's comments don't. I think the spec has too many open ends and needs wrangling. I'm just not sure if this was the best way to go about doing it.

Either way, they're forcing his hand. He's been sitting back while others have been simply trying to get a spec.

If he wants to be grumpy, cool. GH, SO, and Reddit will forge on. If we wants to litigate, cool too; bring it on.

Those 3 communities have large overlapping userbases. This baby is being born, Gruber or not, and nobody will remember in n years about the current kerfuffle.

> Either way, they're forcing his hand.

Which I think is good. Long overdue, maybe even.

It's good something like Markdown exists, and it shouldn't have had to flourish despite not having an unambiguous formalized spec.

> If we wants to litigate, cool too; bring it on.

He's got nothing to litigate about. The trademark claim on "Markdown" had no place in his copyright license, nor does that copyright license affect this specifications project in any meaningful way (because they don't use the copyrighted work).

That's why the only valid argument so far has been over the implications of the word "Standard" in "Standard Markdown" being a "dick move" (which is a personal POV, which is fine, which I also happen to disagree with).

>If we wants to litigate, cool too; bring it on

That would be a quick way to shut it down. Just threaten to sue anybody who _implements_ it.

And how would that work? Let's assume I wrote BrainFuckStandardMD, the implementation for Brainfuck. I would base it solely on the spec published as Common Markdown. I would not in any way use the copyrighted code as basis for my implementation, so it is not derived from it. I don't use the name markdown, so that even the ficticious claim to a trademark would be void. On what grounds would he sue me?

I don't disagree. I think they shouldn't have called it "Standard Markdown", though, as that's appropriating it. "Community-flavoured Markdown" or something would be far better.

I don't think having a standard will in any way reduce the variance of implementations and which implementations (custom or otherwise) sites choose to use. Some wont want to support images. Some won't want to support inline html.

Hell, just look at C compilers!

Since when competition has become disrespectful? This is simply a degree of fault tolerance, ensuring that at least one of the two working groups would succeed.

I can't understand why private either. Asked Atwood directly at: http://talk.standardmarkdown.com/t/markdown-test-suites/158/..., let's see what he replies.

Goddammit, let's all take a vacation.

Is there a formal grammar defined? I don't see one here. They mention peg-markdown which does use a formal grammar - or at least, multimarkdown does, which is the one I've looked at.

Here's the link to MultiMarkdown's grammar:


It's littered with implementation code, but with this stripped out it would make a good basis from which people can write parser generators from (that don't depend on the specific implementation details of MultiMarkdown's internal representation).

As far as I'm concerned, a formal definition should be an absolute requirement for any official spec. The "spec" as presented simply looks like a large collection of examples, informally specified in prose.

What's really needed is a grammar you can use for parser generators, corresponding to a schema for an object model.

It's late here, I may have missed something, so feel free to correct me if if this is the case ;)

So, to summarize, we have a new standard with the name "Standard" in it without a formal grammar definition. Oops.

Unit tests are not enough.

Here is a thread titled "Standard Markdown Formal Grammar": http://talk.standardmarkdown.com/t/standard-markdown-formal-...

And now we have this: http://xkcd.com/927/

> The "spec" as presented simply looks like a large collection of examples, informally specified in prose.

Which is exactly what Markdown's spec consisted of:


And this is the root cause of all the ambiguities that have resulted in incompatibilities in different implementations.

This project seems to be repeating the same mistakes, albeit with more clarity in the description and a more extensive set of examples.

I generally agree with the sentiment that this is going to just add more confusion, but since I've recently been writing a bunch of Markdown docs and exploring different static site generators, I've found that most link back to Markdown.pl as their "source" and despite that, each is using a different middle-man Markdown parser which has different output.

It's one thing to say, for example, that you support Markdown, or MultiMarkdown, or Pagedown style, but another when you just say Markdown and link back to the original, and produce different output. This seems pervasive, and a Standard Markdown that is "one Markdown to rule them all" would be helpful.

Of course, others have pointed out that this spec lacks a formal grammar, and that it also lacks a number of other Markdown elements, so it would need to become a lot more well defined and a lot more mature to be useful.


I wrote http://markdownshare.com/ and found it a nightmare to pick a Perl module to handle the formatting, and know what was included and not.

I welcome a standard, although this particular "standard" seems inadequate - due to lack of grammar and test-suite.

How other than prose would you define it? I expect you know what you're talking about and I want to understand.

Rather than prose, the syntax for a machine-parsed data format is often defined as a formal grammar, using BNF or similar notation: https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form

For example, this is how CSS syntax is defined: http://www.w3.org/TR/CSS2/grammar.html

or JSON: http://json.org/

or HTTP: https://www.ietf.org/rfc/rfc2616.txt

The closest Standard Markdown provides is the re2c "source" that gets converted: https://github.com/jgm/stmd/blob/master/src/scanners.re

I agree that a universal PEG would be great, perhaps this is the project to base that grammar on.

definitely raise that on http://talk.standardmarkdown.com

Here is the thread about creating a formal grammar: http://talk.standardmarkdown.com/t/standard-markdown-formal-...

Will do.

I'm currently trying to get a project started to convert between various file formats typically used for writing/word processing (https://github.com/uxproductivity/DocFormats). Markdown is one of the languages I hope to add, and I've been planning to use the Multimarkdown grammar. But if I can make a convincing argument on the list for using something like this, it will make things a lot easier for everyone hopefully.

> a project started to convert between various file formats typically used for writing/word processing (https://github.com/uxproductivity/DocFormats).

sounds bit like Pandoc: http://johnmacfarlane.net/pandoc/

It's very much like Pandoc, but with two (three?) major differences:

1. Uses the Apache License (Pandoc is GPL). The code for this project is part of a commercial, closed-source project (and needs to continue to remain part of this project) so sadly this rules out Pandoc on legal grounds. I've also had interest from others in seeing such a library unencumbered with the GPL restrictions.

2. It's written in C, not Haskell. The commercial product (UX Write) runs on iOS, and I'm not aware of any Haskell compilers for iOS. I think there are some efforts underway, but at least when I began this two years ago C seemed the natural way to go.

3. It does non-destrctuctive updates, meaning you can make a change to the target file, and then update the source based on the modifications. Doing so will leave any elements in the source document which were unable to survive the translation intact. I'm not sure if Pandoc does this.

> I'm not aware of any Haskell compilers for iOS

Use GHC. http://www.infoq.com/news/2014/04/ghc-7-8-1

> 1. Uses the Apache License (Pandoc is GPL). The code for this project is part of a commercial, closed-source project (and needs to continue to remain part of this project)

You can release code as GPL and still use it in your own proprietary projects, because you retain copyright. You just need to ensure you have a contribution agreement that assigns copyright to you. The risk is that somebody will fork your work and then you couldn't switch to the forked version.

I'm aware of that, but I suspect people will (rightly) be wary of assigning copyright to my company, granting me rights over their contributions that they themselves aren't able to exercise (since doing so would require incorporating code licensed from me under the GPL).

We're currently putting together a proposal to make this an Apache Incubator project and I hope to have it developed as a community effort there. Thus everyone will be able to use it in their own open- or closed-source products if they wish (which will increase the attractiveness of the project for some, who would otherwise avoid GPLd code due to its viral nature). And then no company/individual has any special rights over others who have contributed.

Have you had any interest from others in seeing your commercial project unencumbered from legal restrictions?

That would open up your options considerable.

> Have you had any interest from others in seeing your commercial project unencumbered from legal restrictions?

I have, yes. But currently it's my only source of income, and I need to maintain said income, otherwise I will not have the resources to devote to development of the app (both the closed source parts and open source parts).

If I could make the same amount of money (or more) by open sourcing the entire app, I'd happily do it. I know that theoretically at least, there are strategies to do so, and actually I'd like to take this approach if I can find one that works. If you have any suggestions I'd certainly like to hear them (and yes I'm serious).

I'm a strong believer though in the "hybrid" approach, whereby parts of a product are open source (and used by other products), and other parts are kept proprietary. KHTML (now known as WebKit) is a perfect example of this. If it was GPL, there's no way Apple could have built Safari on it, and the project would have continued to struggle as it had been for some time and probably gone nowhere. But because it was under a license that allowed Apple (and later Google) to build a proprietary product on top of it, both companies had a strong incentive to take the library and improve it. Granted, it was LGPL (not Apache), so they were legally required to contribute their changes back to the community.

A proprietary product that brings in money that can, in part, be used to fund development of the open source components of an application is something I see as a good model. But certainly there are others that could be made to work.

For HTML to Markdown this works in Pandoc, because HTML elements are valid Markdown. Haven't tried with other target formats.

One option if you can run Haskell code somewhere is to use the Pandoc library, which will produce an in-memory structure that you can manipulate as the user makes edits.

I wonder if this has anything to do with it:


That's gotta just be a flaw in the implementation, if the title of the issue ("Exponential parsing") is accurate.

Any PEG can be parsed in linear time and space.

TL;DR Packrat trades guaranteed linear memory usage for worst-case polynomial time; the worst-case almost never comes up in non-contrived input, so it's a reasonable implementation decision to go with the less memory-hungry naive implementation.

Depends on the algorithm; the naive recursive algorithm takes worst-case exponential time, while the packrat algorithm guarantees linear time.

However, for most sensible[1] inputs, the recursive algorithm runs in linear time and constant space, while packrat takes about the same time, but with linear space usage.

[1] Where "sensible" is defined to be "amount of backtracking is bounded by a fixed small constant, as is grammar nesting depth" - conditions that hold for most human-generated files matching useful grammars (I've been working on a new PEG parsing algorithm; it doesn't work so well, but the results I've been getting in testing about the existing algorithms are quite interesting.)

I don't know much of these things.

I was thinking more that maybe some aspect of markdown was not easily expressed using a PEG (it's the same implementer behind both the parser in Pandoc and this project) .

Keeping track of indent levels is not easy with PEGs but can be dealt with by pre processing

I might've missed something. Where do indent levels come into play? AFAICT Markdown has no concept of indentation.

IIRC, lists and code blocks depend on indentation to decide where they begin/end, and I think what level they're at.

I think code blocks don't track indentation. A code block is just a bunch of lines beginning with 4 spaces (or blank lines) and the rest (when >4 spaces) are treated as leading spaces.

I think you're right about lists though.

Nicely done, and needed! But pretty much everyone I know who has used markdown has wandered into the swamp that is known as 'tables of despair'.

Michael Fortin's syntax is pretty useful and quite close to the spirit of Gruber's original efforts. (who hasn't done ascii tables with | and - right?) Until tables are 'standard' I do not hold out a lot of hope for widespread adoption.

That said, I really love taking it Markdown to this next level. And am moderately amused by the recurrence of the themes over time. I'm a old RUNOFF user from back in the day.

I'm actually kind of happy that tables are complex

With the use cases for markdown, table seem inappropriate.

What I mean: tables are good at representing arbitrary data, particularly sets of data stored somewhere.

Maybe it would be better to simply describe the data with json embedded in markdown and delegate representation to something else.

The counter argument is that simple tables are simple. And as silly as that sounds, a typical expository essay might easily include a 2 x 2 'table' to explain some principle (I call them McKenzie tables since every presentation from those guys seemed to include one or more). Or simple columnar data like the current price of the Macbook pro line, or any number of things that are represented easily and efficiently in a simple table. That is why I like Fortin's syntax something like:

   | widgets  | quality level | cut-off point
   | :------- | :-----------  | :------------
   | frobs    | 98%           | 90%
   | bolts    | **65%**       | 70%
   | splangs  | 85%           | 80%
Reads easily in text and markdown's easily as well using multimarkdown (my current go to implementation). Use your CSS to style the selectors tbody, thead, and colgroup and you're off to the races.

The problem that I see with that is it makes editing a table very difficult. Sure, if you know exactly what you're going to put in a table, then it might be worth it to draw all of those lines, but as soon as you need to go and edit the content of a cell, or remove a column or something, you might have to go and edit unrelated parts to maintain your formatting. It also seems like it'd be a real pain to parse. I'm not sure I know of a better solution, except to suggest that markdown might not really be suited for tables, and it's better to just use HTML for that part.

Not quite related, but if you haven't seen how emacs and org-mode handle ascii tables, it's pretty amazing! It will reflow automatically, and tabbing works just like you would expect in a spreadsheet application.

In Github-flavored markdown, the spacing is optional. So it's actually easier to edit than an HTML table. Though a WYSIWYG editor is still beneficial for these kind of things.


It's amazingly easy to run into simple writing tasks that require tables. E.g. if I write a simple product review, I might want to produce a comparison table rather than describe differences in long-winded and opaque prose.

We're trying to move our news writers to use markdown to author articles, but without tables, it will be pretty hard.

Having you tried kramdown? I find it well implemented & has table support. We use it at our compamy.


Kramdown is awesome! Love the way it allows you to easily add only the parsers you need. Plugs right into my Rails app as well.

I'm super excited that JGM (of Pandoc) is heading this and has some cooperation from Github and Reddit (both the largest users of Markdown that I'm familiar with). This is something I've hoped to happen for a long time.

To an interested outsider the appearance of MacFarlane's name in the list gave this instant gravitas. As the builder of pandoc he has to have the widest, most detailed knowledge of markup syntaxes of about anyone.

Given that, the lack of a formal definition is even more surprising: why did they not spec it in Haskell? Formal, unambiguous, and as a side benefit, executable.

> Github and Reddit (both the largest users of Markdown that I'm familiar with).

StackOverflow? (who're also on board via Atwood)

Atwood hasn't been associated with StackOverflow for over 2 years: http://blog.codinghorror.com/farewell-stack-exchange/

That said I'm sure he has valuable experience with Markdown and is almost certainly using it again in his latest venture.

Ben is listed on the site and works at Stack Exchange right now.

And Atlassian, sort of. When they feel like it. BB uses Markdown, but most of their other stuff is something else entirely.

Now if anyone can get the Facebook Phabricator Phriction wiki pholks to use it... They invented one just their own, differing on even the most basic things.

How about a minimal set of asciidoc markup that gives people whatever warm feeling they get out of markdown, but has the benefit of being pretty consistently specified, allowing you to set variables (like multimarkdown), and allowing you to create finished documents in the same style in which you created your scratch documents?


I'm probably tone-deaf on something here, because I simply don't understand the appeal of the format.

edit - asciidoc talk: https://plus.google.com/114112334290393746697/posts/CdXJt6hV...

> whatever warm feeling they get out of markdown

The warm feeling I get is that it's the syntax I use all day on reddit and GitHub. The syntax could be a mixture of Perl, non-printing characters, Emoji, and a Turing-complete sublanguage, and I'd still use it.

Familiarity trumps all other merits. The easiest language to learn and use is the one I've already learned.

Is reddit the secret here? I didn't know that reddit took markdown input (not a reddit user.)

Asciidoc works on github, too: http://asciidoctor.org/news/2013/01/30/asciidoc-returns-to-g...

edit: Thanks Titanous - I assumed it was an optional text filter or something for general use.

I don't know that reddit's a secret, but it certainly uses markdown.

Which is key among the reasons I _vastly_ prefer composing longer-form content there than on G+, which has its own bastardized, incomplete, inconsistent, buggy, poorly-parsed tagging format.

Though I do wish that Markdown used the G+ syntax for bold vs. italic:

    *This is bold*
    _This is italic_
I find markdown's doubled-character syntax ugly, and have my own convention of:

   _Markdown italic, ALWAYS_
   **Markdown bold, ALWAYS**
Visually it's far more distinctive.

Asciidoc (and the myriad of other markup languages that are supported in their file rendering) is not supported in comments/issues/pull requests, only "GitHub Flavored Markdown".

The appeal is twofold: a lot of engines now understand it and it is (relatively) easy to write by hand. (Except for the bloody links, writing the HTML for them is much easier than the equivalent markdown, I do it infrequently enough that I always mix up the brackets or the order (or both...).)

The way to remember it is just that you're parenthesizing the URL. Naturally, you might write it "look at this thing (http://example.com)" - in Markdown, you do the same, but with brackets to indicate where you want the link to show up. "look at [this thing](http://example.com)"

I don't buy for a second that <a href="http://example.com">this thing</a> is more intuitive than that, even if you disagree about the specific brackets used.

"a href" isn't intuitive, but it's memorable.

Yeah, honestly, I think more verbose formatting is much easier to remember than a bunch of punctuation.

The way I remember it is that it looks like function call. so () is at the end thus [] must be first :)

[this links looks like function in most languages](link function argument)

I understand the herd effect - so I put it in user-facing projects that I'm working on - but I don't understand what's driving the herd. Specifically, I don't see any advantages over asciidoc and find it awful to work with.

edit: I do understand this project, though. It'll get rid of the horribleness in implementing markdown, at least.

> I don't see any advantages over asciidoc

Reddit uses Markdown. GitHub uses Markdown. HN (sorta) uses Markdown. Wordpress, Tumblr, and Discourse all use Markdown. If I used Markdown for my own User-Generated-Content Textareas™, people might already know it.

If I use Asciidoc, I may as well be using SGML. It's just another (nice!) syntax you're forcing people to cram into their brains.

I'd never heard of asciidoc before this thread. I suspect asciidoc suffered from being associated with docbook? And perhaps it's just that Perl was much more popular for writing forums in than Python, at the time.

Actually, as a C++11 user, it's a lot like a lambda declaration: [capture](parameters){…}. Certainly the brackets are in the same order. The similarity between lambdas and Markdown URL's is actually a nice feedback loop when I'm doing C++11 code.

Square the circle! [] () Just like the old geometry problem. :)

Nice mnemonic. I'll try to remember that.

Gruber's first (that I know of) public response to this:


His tweet on the @markdown twitter account:

> “Standard Markdown” is neither.

Just look at the @markdown timeline, though. That is one of two tweets ever made. The last one was "23 May 2011". It is a bit passive agressive, IMO, to not stay in the conversation and then all of the sudden express your opinion. Not that he doesn't have a right to, but this project is at least a step forward. If he has specific vision for the project he is responsible for leading it.

Gruber also mentioned it recently on one of his talk show episodes. I cant remember which episode, but as I recall he was not a fan of the effort at all and thinks it is not necessary.

Episode 88. Just listened to it. Discussion starts around an hour and 15 minutes in. Some interesting points made but even Gruber admits some standardization may be necessary. I'd guess he's more upset that they're calling it "Standard Markdown" instead of something less authoritarian. Something more tongue-in-cheek like "Unofficial Official Markdown" may have gone over better.

The question should be why does he feel so threatened by this? Its because its a flushed out better "standard" version that everyone will use. Let the best version win.

I'd say "annoyed" rather than "threatened," and I think it's in part the name, yes. I see a lot of "naming variants '$foo Markdown' is common, what's the beef" responses and I get that, but Standard has very different connotations from Multi- or Github-Flavored or other past versions. I'm not sure that simply naming it something else would have solved this issue, but I don't think it would have hurt to pick something more like "Formal Markdown" -- which captures the notion that you're trying make a formalized standard without explicitly saying "this is the standard."

But I suspect it's also in part simply that Atwood and company never said in public "we are doing this." They just announced it as a fait accompli. Yes, two years ago Atwood and Gruber tweeted at one another briefly and Gruber said he wasn't interested in formalizing the spec. But that's not really an attempt at having a discussion, and it sure as hell isn't an announcement of a project.

I think a formalized spec for Markdown is a good thing. But the way this was handled was still kind of a dick move, and I don't think it had to have been.

What’s Markdown™? it is nor hand, nor foot, Nor arm, nor face, nor any other part Belonging to a man. O, be some other name! What’s in a name? that which we call a Standard By any other name would smell of squeamish ego

It's amazing how similar this is already to the RSS/Atom format wars:

Widely read blogger independently develops a simple file specification that addresses a real world problem. Simple file format becomes a de facto standard. Developers gripe about ambiguities in the specification. Effort to create a formal, standardized specification is launched. This new effort is publicly denounced by the original specification author.

I don't really see the point of this. Being vague is one of the biggest strength of Markdown.

Markdown is being used by very different products to fulfill different requirements. Having no specification means you can inspire yourself from Markdown and just do your own thing, which is what is relevant.

Markdown is being used by comments systems, issue trackers, documentation programs. Those have very different needs, and having a liberal non-specification is what helped Markdown to be popular.

Coming with a new standard, not called "Standard Markdown" (which I think is very presumptuous, even for a big company) and providing new features (arranging/aligning images, variables, include, mathematic notation...) would have been much more productive.

I mean, who cares of those little differences? When I edit a comment or something, I just hit the preview button (or see the preview real time). I'm not going to learn a specification, and if markdown has to look different on stackoverflow or github or <insert doc system>, so be it.

Markdown is also mean for people who have no idea what a "syntax error" is, I know the specification is meant for implementations, good, but if I want to write an implementation, I want it to be fast and this kind of complicated spec is exactly what prevent me from writing something lighting fast.

I'm really sorry, I don't want to insult your work (which is great), but it looks like a waste of energy to me.

Except it sucks when I have to go to the docs for the 10 different flavors of markdown 10 different sites I go to use (assuming they have docs). I also have to spend time documenting my own site when I incorporate markdown.pl versus markdown.py versus some other markdown implementation.

Markdown has become popular enough that a complete, unambiguous spec is good for end-users. If you are building a little text entry thing for your mp3 catalog app, sure, it's nothing to worry about. But when you are github and stackoverflow and google, and end-users are authoring documents, knowing the behavior matters.

Yeah, but it doesn't define how markdown will be rendered.

For example, on github, to get a decent paragraph title, I must use #### (h4), on some other site that might be h1 or h2 to get the effect I want.

I understand the need to define the grammar precisely, but for me Markdown is highly tighten to the site it will be rendered to.

I'm not against a specification, but I feel this is a lot of work (and again I'm not saying it's badly done) that feels unnecessary.

Taking your google example, they might deviate from the syntax because their comment box is too small. I really don't want to argue, it's just some feeling, it might not be rational, and by all means I'm not saying I'm right. I was expecting (and waiting for) specifications for tons of things, but not markdown.

You're assuming you would never want to use the same markdown on different sites. As soon as that happens you discover all sorts of weird cases and ambiguities.

I don't think this standardization is meant to stop sites from adding their own extensions, it is to make sure that the core markdown always looks the same, no matter which site/parser is being used.

Actually I think there are some reason to have slightly different markdown flavors depending of the context. Take the "indent 4spaces for code" thing, on a social website this might have a completely different meaning.

You will say, OK then, but this is not markdown, you'd be right, it'd be some markdown inspired markup, and that's my point, this specification might be relevant to github, and it is, but don't call it standard markdown, call it anything else.

Markdown wasn't designed for the purpose "standard markdown" is giving to it now. Alright, do something new, get traction, but putting markdown in a box doesn't seem to be the best approach to me.

There's room for extensions, but as for base functionality, I for one do not enjoy trying to remember whether a given site uses [links](http://like.this) or [links|http://like.this] or preformatted text ``like this`` or {{like this}} or <pre>like this</pre>...

    > I mean, who cares of those little differences? 
    > When I edit a comment or something, I just hit 
    > the preview button (or see the preview real time).
That's actually a common example of when those little differences matter: when the client-side markdown implementation (preview button) doesn't line up with the server-side implementation (render).

There's nothing to lose by having a standard. Most markdown libraries I've used let you configure between various flavors of markdown. I'd love to enable "Standard Markdown mode" on two different implementations that need to produce the same output and be done with it.

think of standard markdown is an interface. you still can `implements` it and add more specific feature.

I was a bit harsh, let's see what it becomes.

I still feel that if you write a standard, you should cover some important missing features, like:

- Referencing other parts of the document - Image caption (figures), and figure references

Of course, this list should be discussed, but there is room for improvement.

I'm finding some bits odd.

Such as this: http://jgm.github.io/stmd/spec.html#html-blocks

The tags listed are not a complete list of section elements (missing `address` and `nav`), nor the grouping elements (missing `main`), nor the embedded content elements (missing `area`, `audio`, `iframe`, `img`, `param`, `picture`, `source`, and `track`), and doesn't scratch the form elements (but yet the "HTML blocks" include `form`, `fieldset`, `textarea` and `progress`).

The tags listed also include child elements, rather than just the topmost parent elements that were listed in the original Markdown syntax: http://daringfireball.net/projects/markdown/syntax#html

So we have a list of arbitrary HTML elements that have been declared as "HTML blocks", some of these are not really "blocks", and some are clearly other things, and some things that perhaps should be included are not.

And reading through why this list exists creates a sense that the implementation difficulty (of having to produce a balanced tree) is dictating how Markdown must now be experienced by the users.

Example 99 is a great example of surprising a user by not doing what they think will happen and leaving them with a game of "Guess why it's not working.".


It's dawned on me why this is the case.

Gruber's Markdown has this goal: http://daringfireball.net/projects/markdown/syntax#philosoph...

> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

That's it... that's the single big idea that drives the philosophy of Markdown.

And how about Standard Markdown? http://standardmarkdown.com/#how

> one of our major goals is to make Markdown easier to parse, and to eliminate the many old inconsistencies and ambiguities that made writing a Markdown parser so difficult.

Markdown and Standard Markdown have very different goals.

One is designed to make it easy for end users to read and write content for the web, the other is designed to make it easy for developers to parse and process content for the web.

The purpose is no longer the same, a subtle shift has occurred.

By fulfilling the second goal you make it easier for users to write the same kind of markdown on different sites or copy-paste between sites, thus fulfilling the first goal.

When it's decision time, one of those goals will override the other.

For a lot of cases it may be true that fulfilling the second fulfils the first. But crucially, not for all cases.

They are not equal goals, one does not fully imply the other (in either direction). Yes, a better balance could be struck than today... but if the second goal is trumping the first... the users will suffer.

This spec is not strict enough.

Okay, that came out wrong. While I understand why one would want any input to pass (web comment from non-technical users), I have experienced several failures (wrong emphasis, missing link, weird unintended brackets…) just because the original markdown.pl didn't warn me about some obvious mistake I made.

We need a strict mode, where paragraphs cannot be interrupted, where fenced code blocks must end by a fence (not just the end of the file), duplicate or missing references must be signalled… That, and many other precautions could turn Markdown into a serious and reliable document format.

Besides, this tolerance is complicating the grammar. I don't mind context sensitivity nor ambiguity (parser generators can now deal with both), but I do mind the sheer size. If you ask me, a formal spec (one that can be treated as a DSL and translated mechanically into a parser), should not take more than 300 lines. More than that is probably too complicated to implement, or even use.

So it seems like this spec covers a minimum implementation, "basic" markdown. I think extensions to (footnotes, tables, definition lists etc.) should also be standardized, even if their implementation remains optional.

On the discussion forum (http://talk.standardmarkdown.com/t/the-inevitable-markdownex...), a project lead said they are leaving that for later:

> Extensions can come later. This project has the limited goal of standardizing “core” markdown features. There’s plenty to worry about there before we go to extensions.

Yeah, I'm going to just go ahead and say that Fletcher's MMD has been my "standard" for years. Yes, yes, Github flavored is fine. You can adapt it. But since Gruber doesn't want to set a more specific "spec," I default to what I grew up on. And in this case, the last 7 years of my life have been spent writing 95% of everything I publish (keep in mind, this is how I make my living) with MultiMarkdown.

A for effort though.

I'm a little surprised at the level of negativity in the majority of the comments here. I understand our cultural need for criticism here, but the critics here have touched almost everything (and note that the most insubstantial of claims have bubbled up to the top of the comments here):

    Naming [2] [5]
    Closed (initial) development [1]
    Lack of formal grammar [3]
    Lack of tables [4]
    Just use another format (e.g. asciidoc) [6]
    Ambiguity is a feature [7]
Can we please take a moment to appreciate the achievement here? As opposed to fulfilling our own sense entitlement?

Markdown is a popular language with an ambiguous, poorly specified spec and buggy default implementation (so buggy that the vast majority of Markdown users have probably never used it, if they even know it exists). Now, we have a much more well-specified English language spec that explicitly addresses the challenges of the grammar, with a test suite that does a much better job of covering the corner cases, and much better default implementations. These improvements are by no means perfect, but they are improvements.

Yes, we need a formal grammar. Yes, we need tables, and other features. Yes, the naming is unfortunate, though frankly I don't feel sorry for Gruber given that Atwood posted a public letter calling for change two years ago. Yes, these are all issues. But it is an achievement nevertheless, and let's celebrate that.

And then we can get back to work.


More generally, I think we have issues with entitlement here on HN. Frankly, we have no fundamental right to either the original Markdown or this new version. But when posts like this come up, we hack away at them as if we had a right for better, as if the authors should be working to please us personally. We need to stop acting like we have a right to sentence judgement over what others release as open source.

[1]: https://news.ycombinator.com/item?id=8265469

[2]: https://news.ycombinator.com/item?id=8266370

[3]: https://news.ycombinator.com/item?id=8264828

[4]: https://news.ycombinator.com/item?id=8265299

[5]: https://news.ycombinator.com/item?id=8266073

[6]: https://news.ycombinator.com/item?id=8264895

[7]: https://news.ycombinator.com/item?id=8266121

The problem is that there's no formal grammar and the spec of "Standard Markdown", while being more specific than John Gruber's, is still full of ambiguities.

Some examples of ambiguities:

1. It does not specify precedence. For example, if a line like "~~~" (or "[ref]: /url") is followed by a setext underline, is that a header, or is that the start of a fenced code block (or ref definition)?

2. The spec says: "Code span backticks have higher precedence than any other inline constructs except HTML tags and autolinks". It says as an example that "<a href="`">`" is a HTML tag. What happens for different placement of backticks, like "<a `href=""`>" or even "`<a href="">`" is left unspecified.

3. What is the precedence or associativity of span-level constructs? For example, does "<asterisk>a[b<asterisk>](url)" result in "a[b" being emphasised or "b<asterisk>" being linked?

Thing is, a specification-by-example like this would have to keep an ever-growing list of corner cases and give examples for each of them. To get completely unambiguous, the list needs to be very long, and when it gets very long, it becomes unwieldy to handle for an implementer of the spec.

Hence the need for a formal grammar, which is the shortest way of expressing something unambiguously. But it's not possible to write a CFG for Markdown because of Markdown's requirement that anything is valid input. So the next best thing is to define a parsing algorithm, like the HTML5 spec. (Shameless plug: vfmd (http://www.vfmd.org/) is one such Markdown spec which specifies an unambiguous way to parse Markdown, with tests and a reference implementation.)

So if "Standard Markdown" is NOT unambiguous and wouldn't be, then it's not a "standard", so calling it "Standard Markdown" is not quite proper.

If you think there are ambiguities, please comment at http://talk.standardmarkdown.com. This is meant to be a provisional spec, up for comment. There is undoubtedly room for improvement.

The C and javascript implementations use a parsing algorithm that we could have simply translated into English and called a spec. (That's the sort of spec vfmd gives.) But it seemed to us that there was value in giving a declarative specification of the syntax, one that was closer to the way a human reader or writer would think, as opposed to a computer.

Re (3): we have an asterisk which can open emphasis. So, to see if we have emphasis, the rules say to parse inlines sequentially until an asterisk that can close emphasis is reached. The first inline we come to is [b*](url), which is a link. There's no closing asterisk, so we don't have emphasis, but a literal asterisk followed by a link.

Re (1): I believe you are right that the case of a referenc e definition before a setext header line should be clarified. However, the other case seems clear enough. ~~~ starts a fenced code block, which ends with a closing string of tildes or the end of the enclosing container. The underline would be included in that code block either way.

Re (2): I believe the talk of precedence may be misleading here (I thought it would be useful heuristically). The basic principle of inline parsing is to go left to right, consuming inlines that match the specs. This resolves all of these cases. Perhaps the talk of precedence should be removed.

I am no stranger to formal specifications. I wrote what I think was the first PEG grammar for markdown (peg-markdown, which came to be used as the basis for multimarkdown and several other implementations). PEG isn't a good fit, especially for block-level parsing. It almost works for inline-level parsing, but there are some constructs (like code spans) that can't be done in PEGs. It might be worth specifying inline parsing in a pseudo-PEG format to avoid worries like those you've expressed.

jgm, thanks for your comment. I have a lot of respect for your work in Markdown parsing (especially your PEG grammars and Babelmark2), which I find useful and valuable.

I understand what you have now is a provisional spec, but I have reason to believe that a specification based on declaring constructs and defining by examples is never going to get completely unambiguous. A lot of the ambiguity in parsing Markdown lies in the interplay between different syntax constructs. A spec like yours doesn't address them at all, so they remain as ambiguities. All examples of ambiguities I gave involve the interplay of different constructs (more on them below).

> The C and javascript implementations use a parsing algorithm that we could have simply translated into English and called a spec. (That's the sort of spec vfmd gives.)

It's debatable whether translating your code to English is "simple" without talking about memory addresses, pointers and arrays. In any case, vfmd is _not_ such a translation (I'm not saying that you imply that it is). vfmd was first written as a spec, then tests written to match the spec, and then implemented, followed by more tests. (However, the spec did get fixes during testcase development and implementation.)

> But it seemed to us that there was value in giving a declarative specification of the syntax, one that was closer to the way a human reader or writer would think, as opposed to a computer.

I agree there is value in making an easy-to-read syntax description. However, making a readable specification for document-writers and making an unambiguous specification for parser-developers are opposing objectives. The document writer asks "What should I do to get a heading?", while a parser developer asks "How should I interpret a line starting with a hash?". Your spec is good if you target only document writers, but falls short as a spec for parser developers, because of the ambiguities.

In vfmd, I addressed this by creating two documents - one for document-writers and one for parser-developers - that are consistent with each other.

On the specific examples:

> Re (3) ... the rules say to parse inlines sequentially until an asterisk that can close emphasis is reached

Yes, but where does your spec say that an asterisk can not close emphasis if it's contained within a link? As it stands now, going by the rules in the emphasis part of the spec (section 6.4), it should be treated as emphasis, and going by the rules in the link part of the spec (section 4.7), it should be treated as a link. The spec is silent on corner cases where multiple constructs overlap: Does the leftmost construct always win? What happens if it's not a well-formed link? What if three syntax constructs interleave?

> Re (1): ... ~~~ starts a fenced code block, which ends with a closing string of tildes or the end of the enclosing container. The underline would be included in that code block either way.

Going by the setext headers section of your spec (section 4.3), I'm not at all sure why a "~~~" line followed by a "===" line is not a setext header. Yes, your implementation interprets it as a code block, but your spec is ambiguous on how this _should_ be interpreted.

> Re (2): ... The basic principle of inline parsing is to go left to right, consuming inlines that match the specs. This resolves all of these cases. ...

If the basic principle of inline parsing is to go left to right and if all inline constructs should be parsed like that, then "[not a `link](/foo`)" should be interpreted as a link (which is contrary to Example 240 in your spec). Clearly, code spans should have a higher priority, but that needs more than a couple of examples to define correctly.

This principle is also looks contrary to your reply to (3) above, where you say "<asterisk>a[b<asterisk>](url)" is a link, not emphasis.

As noted above, the problem with a declarative spec for Markdown is the ambiguity (which is quite similar to the ambiguity in defining Markdown as a CFG, for example). As long as the spec is declarative, there will be multiple ways of interpreting an input (which, ironically, was the problem that parser-developers found with John Gruber's original Markdown syntax description too). Problems like this cannot be completely solved by providing examples because the combinations between the different constructs are too many to list as examples in a spec.

I only listed these items to illustrate the bigger problems in the design or style of the spec itself. Even if these individual items are addressed, there will always be more coming up, so I don't think it would make sense for me to keep finding and reporting ambiguities to your Discourse forum.

Your comments (coming from someone who has actually tackled this surprisingly difficult task) are some of the most valuable we've received; having them on the Discourse forum would be great.

We considered writing the spec in the state machine vein, but I advocated for the declarative style. It may be worth rethinking that and rewriting it, essentially spelling out the parsing algorithm. As you suggest, a parallel document could be created for writers.

I'll need to study your spec further to see what the substantive differences are.

Thanks. Really happy to see that you're open to a complete rewrite of the stmd spec (to a possible algorithm-based style).

I'll be happy to open a post in talk.commonmark.org on the ambiguity problems caused by using a declarative style for the stmd spec. I'll do that once the forum is back (I can't seem to access it right now).

In parallel, I too will try to work out what the syntax differences are between stmd and vfmd. Meanwhile, please see: http://www.vfmd.org/differences/ (in case you haven't already).

I (for one) can't wait to see what the two of you can do together. I highly respect the work you've both done around Markdown, and I think you could easily accomplish your goals (of a consistent and sensible Markdown parsing rule-set) as a team.

> But it's not possible to write a CFG for Markdown because of Markdown's requirement that anything is valid input.

Honest question here: how do CFGs prevent you from parsing anything as valid input? E.g. AFAICT this CFG in BNF accepts anything as valid input (including no input!)

    <s> ::= <x> EOF
          | EOF

    <x> ::= CHAR <x>
          | CHAR
Isn't it just a problem of crafting a proper grammar which covers all cases? I can see why HTML needs other parsing strategies, but it should be easy for Markdown since everything that is not a non-paragraph is a paragraph (or a blank line, i.e. a paragraph separator).

Also, isn't there a compromise between HTML's crazy parsing strategy and a CFG? A formal grammar, even if not context-free.

True, we can write a CFG that can accept any input, but not one that can parse Markdown.

Actually, I should have said it's not possible to write an _unambiguous_ CFG for Markdown.

Say we need to parse emphasis in span elements. "_a_" is em and "__a__" is strong, but "_a", "a_", "__a" and "a__" are normal text. If we write the rules for all these, we end up with a grammar than can generate the same string in many different ways. To determine whether an "_" is the syntax qualifier of an em or just part of normal text, we might have to look ahead an arbitrary number of characters, and potentially till the end of the input. This is why it's not possible to write a useful (or unambiguous) CFG for Markdown, and this is because of the requirement to not throw an error on any input.

> Also, isn't there a compromise between HTML's crazy > parsing strategy and a CFG?

PEGs have been written for Markdown and they work because PEGs are inherently unambiguous, but use backtracking instead. But those PEGs don't handle nested blocks cleanly.

My own HTML5-ish Markdown spec (http://www.vfmd.org/vfmd-spec/specification/) is not as crazy as HTML5's, but admittedly, is not trivial to implement either.

Interesting reply.

> But those PEGs don't handle nested blocks cleanly.

What's the problem exactly?

With PEGs, it's not possible to express nested content, so we have to collate for example the blockquoted content of blockquotes and process them separately. Per my understanding (and I might be wrong here), part of the problem is that PEG includes tokenization, so it's not possible to handle blockquote-levels in the tokeniser separately.

More details on PEG for Markdown: - from the author of the PEG grammar, who's also the spec-writer of "Common Markdown": http://talk.standardmarkdown.com/t/standard-markdown-formal-... - from myself: http://www.vfmd.org/introduction/#prior-work

Also, I wrote an expanded explanation of essentially what I said about CFGs and Markdown: http://roopc.net/posts/2014/markdown-cfg/

well, they are working on it. Rome wasn't built in a day.

It wasn't, but this is not a good way to build it either because (from my previous post):

> A specification-by-example like this would have to keep an ever-growing list of corner cases and give examples for each of them. To get completely unambiguous, the list needs to be very long, and when it gets very long, it becomes unwieldy to handle for an implementer of the spec.

I mean, they've explicitly disclaimed that this is version 1.0, but they've also explicitly claimed that this is complete, which it doesn't seem to me. This spec is extremely repetitive (0-3 spaces is okay, 4 spaces is too much) and doesn't actually follow a "top-down" approach which would resolve things like precedence. What they've released is something more like a testing suite.

Even more troubling, they skipped the chance for some basic innovations which will probably ultimately result in a Standard Markdown 2 spec. So, for example, they are defining Markdown as a mapping to HTML, rather than a mapping to an internal tree structure which can then be serialized to HTML.[1] If you make that change in perspective, then you can have Markdown for other languages too: not just HTML but also literate code in an arbitrary language, for example.

Another innovation which should probably work its way into Markdown as it becomes more of a file format is metadata. It's a little hard to remember, but acceptable metadata tagging was one of the killer features of MP3s, leading ultimately to their global rise. We don't have a good metadata expression for text files, and Markdown's embedded link references are, essentially, a sort of metadata already. Do this before it gets to the W3C so that we can start off a document with a simple

    @author: Chris Drost 
because once the W3C gets a hold of it that's likely to become something more messy like:

    @author[http://www.w3.org/TR/markdown/2/] "Chris\u00a0Drost"
Another nice change would be an implementation-dependent $extra sigil$ for inline text.[2] Some LaTeX math sites use Markdown with precisely this extension for inline equations; it might be nice to say "this is mapped to a $ node, but the meaning of that is dependent on the tree-reader; the HTML reader simply prepends and appends a literal dollar sign to the text without embedding it in a tag."

[1] This isn't a huge change in the language but it's a huge change in perspective. The main decision needed to fix this is to say that the "embedded HTML blocks" should have a special sigil at the beginning which is not the < character of the first tag; those "raw" blocks are then held separately in the Markdown tree, and the serializer to HTML passes the raw blocks through without HTML escaping or embedding in another tag.]

[2] Why not just use backticks? We could, of course. One problem here though is that there is no good way to distinguish those literate-code blocks which are commentary and those literate-code blocks which are code to be executed. If you don't fix that now, it will probably be fixed in SM2.

They worked on it for two years before going public.

So you equate criticism with entitlement. Too bad.

Criticism is valuable. If I release anything into the public, I expect criticism. Heck, I even look forward to being criticized because it means people care about what I did (even if I did it wrong!)


"Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission."

It's a total breach of license, and on a fairly standard BSD too.

I'm seriously getting tired of copy-pasting this, and surprised that ya'll are defending this whole thing. but I guess I shouldn't.

Anyway, I better jet before I start trolling. In the end, I'm ok with making a better markdown, but completely opposed to breaking the law.

Interesting point, but it fails a number of crucial tests:

⚫ The spec isn't code. More to the point, it's not a derivative work of Markdown itself. The BSD license applies to the licensed work as a whole. What it doesn't apply to, specifically, is other works which refer to the original. That is: copyright is not trademark, and you cannot embed an effective trademark license within a copyright license.

⚫ Works (parsers, libraries, etc.) based on the Standard Markdown spec which do not incorporate any of Gruber's original Markdown code are themselves not derivative works of Gruber's original BSD-licensed work, and again, are not governed by the license.

⚫ There are a number of things copyright doesn't apply to: functional works (SEGA v. Accolade), simple compilations of facts (Feist v. Rural Electric), and APIs or standards (I'm aware of a few cases involving these, though I don't recall specifically if any are precedent). Specifically, however, a copyright license cannot cover facts or functional design. It only applies to a specific expression of an idea. Paraphrase that idea and you're scott-free.

So while you raise an interesting point, it's moot here.

IANAL but that license term only applies to derivatives of the Markdown code.

Markdown is written in Perl. Standard Markdown has released implementations in C and Javascript. It seems unlikely that they are using Markdown code, therefore I don't think they are bound by anything in the Markdown license.

Yep, that license seems to apply to the code.

Now we get into the question of whether an abstract API can be copyrighted -- we all assumed no, although the Oracle v. Google case (about Java), suggested an abstract API could be copyrighted. With, most of HN thinks, fairly disastrous consequences if that holds as law, although I think it's probably going to be litigated more.

I frankly doubt Gruber was assuming that his abstract (poorly specified!) API for Markdown could be copyrighted. And almost everyone on HN seemed to think it would be disastrous if that were the case regarding Java; it would be somewhat hypocritical if the same people think it somehow ought to be the case regarding Markdown.

They are bound by the fact that it's about the name 'Markdown', the code/spec is irrelevant, hence the words 'Neither the name "Markdown"...". Discussions about code/spec/philosopy are irrelevant and would be deemed as such in court.

It's too bad because I actually really like this, but I think it's not going to take off because of all the courtroom drama.

You can't just write whatever you want in a license and bind people who aren't using/modifying/distributing your software.

So is any fork of markdown that uses the word markdown count as a violation of the BSD license until you get written permission from gruber himself?

<em>Markdown is a popular language with an ambiguous, poorly specified spec and buggy default implementation...</em>

That never hurt Perl... :-) Sorry, couldn't resist.

Your sentiments are well-taken.

No one "owns" Markdown, and quibbling over words is unproductive.

There is a concept: "a simple in-line markup language that is easy to write and maps clearly to HTML". One instance of that concept is a specific, buggy, ill-defined language called "Markdown".

"Standard Markdown" is another instance of the same concept. This is the way English works: adding modifiers to words that designate one instance of a concept to designate other instances of the same concept.

Getting to an EBNF grammar from the spec would be awesome, but the spec is a great place to start. All spec generation is tendentious, and it is common to have multiple people highly invested in the generation of different specs for the same nominal standard. Politics, as Aristotle tells us, is the master art. This is why.

"This is the way English works: adding modifiers to words that designate one instance of a concept to designate other instances of the same concept."

So you think anyone would think it was totally cool if someone released things called 'Standard Excel' and 'Standard MacOS'? That wouldn't get by without criticism, why should this?

I think you can draw an analogy to trademark law here. I know we're not talking about anyone registering trademarks and suing each other here, but when it's good, law tends to reflect common practice, and I think trademark law actually does that pretty well. I think most reasonable people look at the way trademark law treats issues like this as being more or less how they think the issue should be treated.

That is to say, you can't really spend a decade or two letting "Markdown" sort of mean whatever people want it to mean, and only then cry foul for the N+1 person to use the term. "Excel" and "MacOS" have not been genericized (is that a word?) to the same extent that "Markdown" has.

It's right in the darned license for markdown:

"Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission."

Legalities aside, this is a dick move that goes directly against the license.

As for your genericization argument, what do you think are the first 2 results in Google for markdown? And the wikipedia description (3rd result) includes both the syntax and the 'tool'. Popular != Generic

Popularity has no relationship with being generic. The classic case, Kleenex, has the entire first page of Google hits referring to the product of the same name, but it's still a generic mark now. Even if popularity did matter, Google isn't necessarily the best way of measuring that, and if forced to guess, I'd say the percentage of markdown files processed by Gruber's perl implementation is very small.

Also, if the problem with "Standard Markdown" is the use of the term "Markdown", then the license is relevant. But that means that everyone else (Multi-markdown, Markdown Extra, Github-flavored Markdown, Python-flavored Markdown, Markdown Python, Markdown PHP, etc. are all equally guilty of a "dick move". I don't see anyone arguing that calling it "XXX Markdown" is a problem. It's calling it Standard Markdown that they have a problem with, and the license doesn't really address that without also addressing everything else.

I do get the reaction to some degree. I would stop short of calling it a "dick move", but maybe it's a bit tone-deaf admittedly. I just think that the horse has left the barn on taking offense that someone implemented something sort of like what you called "Markdown" and called their version some form of "Markdown".

> Also, if the problem with "Standard Markdown" is the use of the term "Markdown", then the license is relevant. But that means that everyone else (Multi-markdown, Markdown Extra, Github-flavored Markdown, Python-flavored Markdown, Markdown Python, Markdown PHP, etc. are all equally guilty of a "dick move".

Gruber is OK with "Github flavored Markdown" because the name makes it sound like a fork. "Standard Markdown" does not sound like a fork. See my earlier comment in this thread for a cite to Gruber verifying that this is his problem with the name.

Maybe we're just too immersed in our own terminology, but to me, "Standard X" (e.g., Standard ML) refers not necessarily to the notion that "our version owns the concept of X" but that "our version of X is standarized". Common Lisp took a slightly different term, but that really reflected their goal with building the language spec -- they weren't after any old standard, they specifically wanted to incorporate common features from the bunches of different Lisp implementations. Calling this "Common Markdown" doesn't quite capture the right meaning, I think.

The thing that makes this weird in that context is that I can't think offhand of any examples where the inventor of "X" has been opposed to the idea of doing anything about the mass of incompatible versions floating around. Usually, you have a language, there are a few implementations, and then everyone gets together to nail down what an "official" version should do. My gut is that at some point, if after a decade of pleading, the maintainer of an "official" version is not stepping up, the community is OK to go on without them, but clearly there are arguments on both sides there.

> So you think anyone would think it was totally cool if someone released things called 'Standard Excel' and 'Standard MacOS'?

I don't think anyone would dispute that both Excel and MacOS are, in fact, trademarks established through bona fide use in commerce and which have not been genericized, and which, therefore, currently serve to clearly designate the origin of particular commercial products.

I don't think the same consensus exists with Markdown. In fact, I suspect if there was a general consensus that "Markdown" had some clear meaning, whether or not it was to designate the original of a particular commercial product, the "Standard Markdown" project wouldn't exist.

The important thing is that you managed to feel superior to both camps, that's what matters. Criticism is criticism, take it for it's merit, not because it hurts people's feelings.

I can't help but think about http://xkcd.com/774/ when I read this comment

Well, you are using the same tactics to feel superior to them all.

Sorry, that accusation expires after one use per conversation.

At least someone understood the reference... :-)

Never underestimate HN's lack of humor ;)

How a group (of whoever they are) claim they're the standard about something in nowadays without even caring about localization ?

2 years of 'complete specs' without a mention for RTL and how it should be supported/written in markdown....

A bit disappointed tbh... even though it's a nice initiative...

What would they have to do differently for RTL languages? I thought that RTL is already abstracted by Unicode or something. Won’t something like the following just work automatically?

> انا اسم [روري](http://roryokane.com/)

No. It won't just work, it's even shown on your comment how awful it is.

To understand what I mean, try to inspect your comment, add `dir="rtl"` to the <p> tag of the Arabic text...

Since when does ASCII text support RTL?

I thought the whole point of Markdown was to define a mixed-mode formatting that looked OK in ASCII and could be prettified in other contexts like HTML.

Since when Markdown was just about ASCII text ? then we can't write French, Arabic, Chinese using markdown ?

my whole point is to define a syntax indication in the specs on how RTL elements should be identified when converted to say HTML. when converted, THAT element (or the whole document) would contains dir="RTL" attribute in its tag.

for example, something like this:




would convert to:

<p dir="rtl">Foo



Prettifying won't help... RTL elements/document should be indicated in markdown

I mentioned this on twitter to @defunkt (https://twitter.com/_beid/status/507269600401440768)

I don't agree that it should be defined in markdown, RTL languages should be detected by the parser and be outputted within a block-level element, P is good, with dir="rtl" as you mentioned.

I really disagree, RTL should be defined in Markdown,.. as the ZEN of Python says:

"Explicit is better than implicit."

this is a case where indicating RTL should be done explicitly, letting the parser/browser or whatever do the work still won't help. Why?

think about a mixed text of one sentence/line where there's only one word in Arabic at the beginning and the rest of it is Latin... the browser/parser or whatever will think of it like LTR text because the sum of latin words > sum of Arabic words. which is False.

A live example of this is Facebook. it does actually a Layout detection based on the content's language in comments. but it sucks in many cases. try to write a comment in Arabic with a mention of someone's name (the name in Latin) to see what I mean.

so IMO, neither dir='auto' nor the parser can detect this implicitly, we still don't have the AI for smarter detection, even if we have, there are cases where you want RTL regardless of the content. thus it SHOULD be defined in Markdown.

actually you could just add dir="auto" and let the browser do the detection.

Please see my comment above...

Where does ASCII come into it? UTF-8 plain text supports RTL fine. The point of markdown is formatting that looks ok in plain text and can be prettified into HTML. It ought to work when that text includes RTL.

It's not about ASCII, it's about where that ASCII is presented whether it's terminal emulator like mlterm or a text box in a sane OS like Ubunutu. RTL languages can be detected and viewed correctly without any additional information.

Addendum: I'm using 'ASCII' only because in this context we are talking about 'plain text' and not the actual 7-bit ASCII. UTF-8 encoding is a given when talking about RTL languages.

I modified the renderer to output React DOM instead of an HTML string if anybody's interested


It seems like an obviously missing thing is a page that describes how users should write markdown, in a few sentences. Otherwise you are just going to get incorrect summaries of the spec.

You certainly can't point users to the spec, which is incredibly lengthy.

Soooo submit a pull request, then?

The most surprising thing in here is the ire toward Gruber. Even if you disagree with someone who writes a piece of software, they don't owe you anything. You use and benefit from their work, and you are angry when they don't agree with you? What a bunch of whiny, entitled nonsense.

Gruber has stated he wants to keep it ambiguous. You may disagree. But Gruber owes you nothing, and you are in his debt if Markdown has been useful to you. Draw inspiration from his project and make your own.

This reminds me of a similar issue that happened within the Scala community. David Polak, the creator of the Lift framework (which is used in production in many top sites), had originally worked hard to create the framework (along with others) and make it production worthy.

Later, he realized that the releases of the framework he had created were happening without his involvement. But, instead of accusing the community, he said something remarkable which only multiplied my original respect for him:

    I never "left" the Lift community. 
    Yes, I have other project and work in different languages. 
    What I did was cease to be Lift's benevolent dictator for life. 
    Lift has grown way beyond one person and the fact that
     the 2.5-M4 release was done without me is a strength, not a weakness.

Because, that's the spirit of open source. When you release something to the public, for public consumption, then you must understand that someone is eventually going to fork it up and assign it a different nomenclature, sometimes even a nomenclature that you may not like. In this case, this particular project had no standardization and a part of the community decided to just standardized it. If you don't like this standardization, then simply don't use it. Use what resonates with you. If you feel the standardization has some flaws, then fork it and fix what's wrong. IF people agree with you, eventually they will end up using your fork. It's as simple as that.

What is funny is to see John Gruber who appears to be butthurt about this, when his contributions have grown negligent (https://news.ycombinator.com/item?id=8266574), inconsistent and his recent focus has been more on other (personal) things.[2]

This reminds me of Luca Pasani[3], who released the much popular WURFL repository as open source in a liberal license first, then one fine day, cried foul because other people (including companies) were using it for profit (in accordance with the license), deleted all online repositories and instances of the project released under the old liberal license [4], then re-released the project with a comparatively restrictive license.[5]

In my opinion, releasing something for open, public consumption means you have to develop an honest mindset of accepting that other people WILL benefit from your creation eventually. If you don't get that right, then open source is probably isn't for you. (And crying foul later, is a double standard, if you do)

[1] http://stackoverflow.com/questions/12424617/comparing-lift-w...

[2] like writing controversial Apple articles at daringfireball.

[3] http://en.wikipedia.org/wiki/Luca_Passani

[4] http://en.wikipedia.org/wiki/WURFL#License_update

[5] http://yro.slashdot.org/story/12/01/09/169216/wurfl-founders...

Thanks for this, you've pretty much said most of what I'd have to say on the subject. The only real question is the enforceability of the license clause on naming of derivative works. Though of course, a spec (which doesn't quote the BSD code itself) isn't a derivative, nor are other implementations based on that spec. Gruber is attempting to turn his copyright license into a trademark license, which given a decade of genericization and non-defense is fairly likely to fall if tested in court.

I forsee a possible recursive acronym of the form Foo is Not Markdown in the not-too-distant future.

Or a Mozilla / Phoenix / Firebird / Firefox contretemps.

Gruber really should put on his big-boy pants though, IMO, and thank those who've picked up his ball and run it further down-field from where he'd abandoned it quite some time back.

> Gruber really should put on his big-boy pants though, IMO, and thank those who've picked up his ball and run it further down-field from where he'd abandoned it quite some time back.

Yes. Very much so. Personally I'd have been honoured if something I came up with gets big with sites like these, picked up and carried on by smart people like these. Especially if it kept the same name, because Gruber will always[0] get to say: "Markdown? I invented that". That's the big-boy pants part of it: Gruber has that claim. Being "the inventor of Markdown" is pretty much the biggest claim of value Gruber has anyway, not that perl-script his copyright-license pertains to. And it's that value which only gets bigger thanks to this project. IMO it doesn't even make sense to complain about somebody else running with an idea that you haven't touched in years, yet has grown huge on the Internet in the mean time.

[0] https://en.wikipedia.org/wiki/Moral_rights_%28copyright_law%... (in large parts of the world, anyway)

I've only had modest successes in tricking other people to implement my own work and ideas, but where I have, it's been a positive:

⚫ Hey, I thought of that.

⚫ Hey, other people thought it was useful and/or a good idea.

⚫ Hey, they did the work (or took over the work) for me.

And often on top of that: "oh, someone's added a new idea / cool feature / process improvement that I hadn't even considered".

Sure, sometimes people goof stuff up. Shit happens. But I've pretty much always got other things that are keeping me occupied.

It's pretty much set in stone in the license.

"Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission."

No ifs, and, or buts. It is what it is. It didn't meet that condition. It's in breach of copyright. http://daringfireball.net/projects/markdown/license

So John has an option to pursue legal action. Bring it on. I'm happy they're forcing the issue.

Soon enough, no one will care. GH, SE and Reddit have enough mass to have their flavour/spec dominate in terms of user base and adoption.

Does that mean every fork of markdown must have written approval from gruber until he kicks the bucket?

it seems weird to have HTML as a non-optional part of the spec in two separate locations, and then "Because we might be targeting a non-HTML format"

it would make more sense to just have some way to dedicate a block of text to not be parsed in any form.

regardless, I'm 99% sure I'm intentionally missing the point here, as I can imagine reddit's, github's, stackoverflow's, et al.'s implementations would not support html tags at all (and anything for a personal site would have less restrictions on usable html tags). So in practice, it is going to be optional to some degree for implementers. but it seems weird to have that implied, when the handling of info-lines for codeblocks is explicitly left ambiguous

Thanks, this has been long coming and sorely needed.

This sounds like a great idea in theory, but the execution seems to be a little scratchy.

It sounds as though this is very much a unilateral decision from one of the many sites that use Markdown to standardise it, masked by what seems to be a call for other companies with an interest in Markdown to join.

It seems a little questionable to me for John Gruber to have been ignored in this process. Afterall, he made Markdown and it probably would have been a better idea to take his rather ambiguous spec, develop it into a proper standard, and then call that version 1.0.

No doubt Jeff Atwood deserves some credit for trying to initiate a standards process for Markdown, but I think he's doing it the wrong way.

Github, Reddit, Stackoverflow. Those look like several big sites to me (not just one). And as many people said, Gruber is not some sort of BDFL...

> It seems a little questionable to me for John Gruber to have been ignored in this process.

No, it's the other way around. Gruber decided to ignore everyone who tried to improve the sad state of Markdown for the last 10 years.

And, if we look at the list of people who were writing it, we see Github, Meteor, Reddit, and StackExchange people (plus JGM and Atwood) as the participants, which I think cover the top 3 sites using Markdown.

And Jeff is using Markdown for his forum project, Discourse, so that's another chunk of users.

This kind of coalition has the power of numbers to standardize on something, which is why this is so exciting.

Yes, I was a bit wrong with that statement. Just read http://blog.codinghorror.com/responsible-open-source-code-pa...

There is a typo on the main page http://standardmarkdown.com/, in the section “How can I help?”:

“Read the spec, run the test suite, and exercise our reference impementations.”

“impementations” → “implementations”

I couldn’t find a GitHub repository for the code of the website itself, or I would have made a pull request.

Edit: I see there is already a thread about this: http://talk.standardmarkdown.com/t/site-typo-s-one-to-start-...

Wait, the spec doesn't even address things like tables.


See example #87. Personally I think it is absurd to try and include HTML(5?) in this standard and I would much prefer the tables in github markdown:


Because tables are implementation-specific extensions.

So the standard does not provide a standard?

I find the dokuwiki table syntax to be pretty simple and effective, or the markdown extra version. Don't know why none has been made a standard part of markdown yet. Seems like it must be due to backlash against table-based web designs of the 1990s, (which resulted in an entire generation of web developers thinking that tables are inherently evil and an entire generation of non-developers who just do things in MS Word or Excel instead because it's relatively easy to make tables).

> So the standard does not provide a standard?

A standard can be descriptive (bottom-up) or top-down (prescriptive). A descriptive standard will only check and document common-ish features to implementations. Tables are not one of them.

Yes, they’re part of Markdown Extra[0], written by Michel Fortin.

[0]: http://web.archive.org/web/20140830092621/https://michelf.ca...

Does the spec allow extensions?

So are fenced code blocks.

I assume the spec is descriptive, and fenced code blocks are 1. a pretty common extension and 2. generally added the same way everywhere

Reddit and GFM use the same table syntax. Reddit is huge [1]. GFM is widespread.

PHP Markdown, MultiMarkdown, etc also support that syntax. Stack Overflow is pretty much the exception [2].

I'm not interested in Markdown parsers which do not support tables. They are useless to me.

[1] http://www.reddit.com/about/ - "last month, reddit had 114,540,040 unique visitors"

[2] http://meta.stackexchange.com/questions/138946/can-we-add-ma...

+1. I hope that book publishing tools (leanpub for one) also subscribe to the standard once it's been formalized/ported.

would love to hear Gruber's take on this.

He said in his podcast a few weeks ago that he thought it was unnecessary, as the ambiguity allowed for different flavors with different uses. I'm assuming the reference to the Yankees being the best team in baseball is directed at Gruber.

During that podcast, Gruber encouraged that group to consider not calling what they were doing Markdown. Something to the effect of, "Come up with your own thing, and see if it catches on." He noted that the ambiguity is probably what has made Markdown useful to such diverse groups with different needs, and should be preserved.

> During that podcast, Gruber encouraged that group to consider not calling what they were doing Markdown.

John Gruber's stance was a little stronger than this - he currently has a reasonable claim to the trademark Markdown, as a term he coined and popularized for this use. This group's use of the brand "Standard Markdown" to describe something the owner of "Markdown" disagrees with seems ill-advised. He's now forced to either try to push them off the name or effectively abandon the trademark to genericization.

So, Gruber is fine with people implementing their own markdown processors without his permission, and still call it markdown, and he even likes it when they do that, he likes the flexibility and multiple flavors of markdown.

But if people implementing their own markdown processors try to write a spec or grammar for what they are implementing... he is not fine with it, and considers legal action? It's okay to write a markdown parser, as long as you don't write a spec for it?

There may be a way to justify that position rationally, but I doubt there is legally. He's already abandoned any claims to trademark, by making it clear he's okay with people making their own markdown parsers and describing them as 'markdown parsers', without his permission.

My position (and what I see others taking) is not a problem with formalizing Markdown, which many see as a good thing, but the name.

If they made this an called it StackMark it would be fine.

But this feels more like a power play. Like when Microsoft came and made Visual J++ in an attempt to take control of Java from Sun. It seems oddly and unnecessarily mean spirited and hostile. The name seems designed to either engender confusion or as a slight against the original.

How about "Specification-flavored Markdown"?

I'd accept that. Seems unwieldily (so it wouldn't be my choice), but I don't think it's outright hostile to the original.

We've got Disqus, Stack Overflow, GitHub, and others. John has referred in the past that he doesn't mind how GitHub has GitHub flavored mark down. This new one could be called Atwood flavored (to pick a name I know is involved). Or they could have stuck with GitHub Flavored markdown and just expand the GitHub flavor.

He's already lost it to genericization. Trademarks distinguish vendors in a market place; plenty of different people operate services that provide "Markdown" formatting that are not the original vendor and are incompatible. Without having taken any steps to license other people's uses of the term, it's not operating as a trademark in any normal sense (unregistered or not).

I don't know how well genericization applies to this, markdown was a loosely defined specification, intentionally encouraging modification. all the "incompatible" versions of markdown are within what he intended.

further, its just the name of a spec, should the owner of a spec really be expected to continuously hunt down and test/validate every implementation of their specification? that doesn't exactly seem possible in the slightest.

I don't think he would have trademark protections for something like this for other reasons, I do wonder if there is anything similar that applies in this situation

> should the owner of a spec really be expected to continuously hunt down and test/validate every implementation of their specification?

I'm pretty sure thats exactly what trademark law says you have to do. You have to defend your trademark. You can't go ten years letting everyone use the Markdown brand where ever they want, and then suddenly decide one day you want to start controlling it.

> he currently has a reasonable claim to the trademark Markdown, as a term he coined and popularized for this use.

Coining and popularizing a term is not a basis for a reasonable claim to a trademark. Trademark rights stem from one source: bona fide use of the mark in the ordinary course of trade. If its not used as a mark identifying and distinguishing the source of a product in commercial transactions, its not a trademark.

> He's now forced to either try to push them off the name or effectively abandon the trademark to genericization.

If there was ever a good claim that it was a trademark (which I don't see the evidence for), I think there's a pretty strong claim that it has already been lost to genericization, given the long-standing established uses on a variety of unlicensed implementations with differing sources.

The ambiguity of Markdown formats has been nothing but a minor pain to me. It makes it harder to search for syntax advice, that's for sure, and 99% of us casual users are doing just that.

I am excited for a well-documented, standard Markdown format to be the top link on Google.

I remember listening, but wish I could find the episode again. Do you remember which one it was?

I believe it was the 2 parter with Marco Arment. Either this one: https://daringfireball.net/thetalkshow/2014/07/19/ep-088 or this: https://daringfireball.net/thetalkshow/2014/07/19/ep-089

Just several hours to sift through :)

Listen to it on Overcast.fm

"Atwood's crusade"


I've landed on the guy's markdown pages (he refers to this in the podcast) several times, trying to figure out how to do stuff in markdown. I find the page hard to read (the font is tiny; I always resize it), and the examples rarely seem to describe what I am trying to achieve.

It's starts at about 1:15:00 in Episode 88.

It's the episode of The Talk Show with Marco Arment as a guest.

Here's a reply he made to a twitter conversation about it: https://twitter.com/gruber/status/507305771265454080

It definitely seems shitty to take the name of his project without his permission, regardless of how righteous they think the cause.

From the podcast linked below, my rough summary of his position: Essentially, that while a spec that cleared up some ambiguity might be useful and is a task he might undertake someday, calling one thing "true markdown" and other flavors not wouldn't be useful. If Github wants to have a version of markdown that supports code better than a blog engine needs, good for them.

So basically follow the example of pre-standards browser-specific HTML features?

When you are considering how two things are alike, don't forget to also think about the ways in which they are not. Unlike with HTML, content producers who write Markdown, don't need their documents to be parsed correctly by many different engines. They only have to target the one they are using.

To be clear, "Standard Markdown" is only trying to address the ambiguity of the syntax. Sites are still going to implement Standard Markdown plus some ad hoc extensions, so it will still be the same practically in that regard.

Which was where most innovation and the good parts of modern HTML came from?

Just FYI: That tweet exchange is from two years ago.

I would like to think that they at least approached him.

We did -- no response to the current spec after a week of waiting for a reply.

A much earlier lengthy email response from Gruber around 11/2012 evaluated each of the changes Stack Overflow and GitHub made to Markdown one by one (there were some he agreed with) and essentially said "ambiguity is a feature" at the end.

We disagree about that.

But why use basically the same name? If you want to make a fully specified version why not give a slightly different name instead of just "Standard X"?

Using (basically) the same name strikes me as somewhat hostile given the views Gruber has expressed, and likely to cause confusion to end users.

The problem is that once Gruber embraced ambiguity and encouraged lots of people to make whatever they want and call it "Markdown," it's hard to say "no, no, you can't call this one specific thing Markdown."


He's not telling them they can't — he's saying they shouldn't. Those are very different things.

There's a difference between a fork (flavour), and just claiming ownership, which is what this is.

It's less like he's saying they're wrong and more like he's saying they're rude.

> But why use basically the same name?

Because it communicates the right thing to users >90% of the time. If you learn the language specified here and then go write some reddit comments or file a GitHub issue using that language, it will do what you expect.

The few places where it doesn't you probably don't have an intuition about anyway.

If you treat "markdown" as an improper word describing the language and not some sort of proper "brand name" that describes provenance, then what they describe here is "markdown".

> If you learn the language specified here and then go write some reddit comments or file a GitHub issue using that language, it will do what you expect.

It would do the same thing if all those groups (since they seem to be onboard) had decided to call it TextMark or CommentAscii or some other new term. As long as they all use the same term it would be fine.

But instead they're basically trying to strong-arm redefine Gruber's name, and they'll win because they're bigger.

It's in terribly poor taste.

This will actually make things worse too, because they've invented another standard. People will see 'old' Markdown sites that don't work like 'new' Markdown sites ('Standard' is too subtle) and ascribe it to a bug in 'new' Markdown.

They haven't avoided confusion in the way a new name would have done very quickly.

Same confusion, acting like a jerk to take over someone else's creation. High class there.

Markdown has outgrown Gruber's stewardship, "ambiguity is a feature" is not an opinion I can get behind. Calling this something other than markdown would be more confusing for end users. It is markdown, standardised.

> It is markdown, standardised.

I would avoid this wording. I would instead say:

It's a flavor of markdown. The flavor is heavily documented. The flavor's name is "Standard Markdown".

"I don't like his position so he should lose his ownership". Lovely.

My problem with the name "Standard Markdown" is I don't think it's going to be clear enough, I think people will think it's the same thing as Markdown (which it's not), under the theory that "non-standard" would have an obviously different name such as "Lisp Markdown" or "Japanese Markdown".

If they had used a word other than "Markdown" I wouldn't have a single problem, I would cheer them on.

I don't see a real benefit in this name to anyone, but I see serious downsides.

> "I don't like his position so he should lose his ownership"

That's certainly an unbiased translation :rolls eyes:. If you want to have a good-faith debate, you should avoid tendentious re-writes of your interlocutor's arguments.

> "ambiguity is a feature" is not an opinion I can get behind

You clearly don't like his position.

Be he has explicitly chosen not to make a specification, he's had years and numerous requests. From what I've seen/heard John Gruber likes that it isn't formalized with a spec.

So if a group of people, especially a large group with 10s of millions of users (at a minimum) decides to write a spec and name it "Markdown" over Gruber's wishes it sounds like trying to take ownership from him.

My phrase was glib, but I don't think it's that far off from many of the comments expressed here.

He owns an ambiguous text formatting system? He didn't invent the notion of simple ASCII-character based formatting, and he didn't write a spec. Plus this spec explicitly deviates from his implementation, so it's not the same obviously.

The reasons that he didn't write a spec after requests is very likely post-hoc rationalisation, behind the simple reason that writing a spec is not a fun task.

I've certainly struggled with the layout of exact stuff in Markdown ... but there's something about this name, the writing on the index.html, and the constant use of the unofficial file icon (which i'm really not a fan) that kind of irks me. Maybe it's the spirit of the naming? Maybe it's because of the effort to _brand_ this? And perhaps the developer-centric tone of the writing versus the writer-centric tone of the original spec? I'm not sure.

From the original Markdown doc: "HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text." The lack of support for complex or exact layout was intentional.

As I read it, if you want your Markdown documents to be rendered a specific way, you choose/configure/write a Markdown parser that renders it that way (possibly with the assistance of an additional stylesheet). If you need a particular extension for a task (tables, syntax-highlighted code blocks) you can use an parser that supports them. And if you need specific HTML elements, you can use them inline.

The way I read it, Markdown is intended as an _input format for markup tools_, designed to be both legible and meaningful as plain text. Any meaning that can't be explicitly encoded in the ASCII format, including the specific HTML tags used to render a given construct, is outside Markdown's scope and should probably be stored in a more structured format.

It kind of sounds like you have disagreed over the same things for five years now, and finally got enough names on your side that you decided you didn't need to get agreement and could just take over the name.

Not cool.

Gruber has been okay with people writing and distributing their own markdown processors, with whatever variations they want.

The difference here is that they wrote a spec for the variation they plan to implement? That somehow makes it not cool?

Or just that they're calling it "Standard Markdown"? Could the dispute be avoided if they called it "A Standardized Markdown", or "Standardized Flavor of Markdown" instead?

There are many markdowns, and Gruber likes that, fine. Other people would like to standardize and make compatible implementations. Nothing's stopping people who disagree from continuing to ignore the standardized spec. But where' the logic in saying "you can release whatever markdown variations you like, as long as you don't try to make different implementations compatible with each other."

It really should be obvious that none of those other names are acceptable. Github-flavored markup is obvious because it is _not_ taking the name from the author and it is not lying about where it comes from.

Standard markdown lies about where it comes from and thus claims more authority than it is due. Formalize it all you want, then name it coding horror markup.

I don't see how stealing other peoples credit is acceptable.

Whatever. I really respect Gruber for his original design of markdown, but am puzzled by his destructive behavior in this. While he was sitting on his hands, a lot of us have been annoyed at creating a markdown doc in one app and finding it looks funny in another client. This spec is long overdue.

He can still choose to be caustic and demand a rebrand, but it'll only delay the inevitable replacement of the original markdown.

But wont that always be an issue because vendors will have to disable features selectively. I see the merits of a standard from a developer standpoint but I don't think hat solves the problem you are describing.

Gruber should make a question and answer site called Standard StackOverflow.

And it should take over if StackOverflow's service is crappy.

I vote for using a different name.

Going to be honest, I'm not cool with this, and will not support it under this name. I'm probably a minority, I almost always am, but it will impact how I view and support the products built by this team. Not cool with me gentlemen, not cool by half.

You can't have your cake and eat it too. If ambiguity (and thus different implementations) is a feature, then a natural side effect is that another group of people can come along and say "this is ridiculous, let's define a new implementation we can all support".

And if you're doing that, it's pretty obvious to call the effort to produce a standard implementation Standard Markdown. Unless you think Github-StackOverflow-Reddit-flavored markdown is a better name :)

Yea, usually out of respect and general human decency, the inventor of a technology gets to retain rights to the name and the names usage. Very disappointed.

I think you've got it backwards. It would be less decent to give it an new name and forget its origins. Calling it Standard Markdown waives any claim to have created anything new. It makes it clear this is merely an effort to standardise the language Gruber famously invented. It gives all credit for origination to him.

I'm 100% certain I don't have it backwards. Gruber is still alive, so you can ask him if he wants it the same name. Oh, they did; he said no. Not honoring the original inventors wishes is in direct opposition to propriety. It will cause me to file trademark against any open source project I don't want to lose rights to. Seriously, how am I the only one who doesn't think this is f^#&^%d up?

I hadn't read the stuff about Gruber not wanting them to use the same name before I wrote my comment. But I still don't think it's 'fucked up' in the slightest. It actually sounds like Gruber is being irrational and a bit of a dick, from his comments that I've just read. His behaviour seems weirdly lame for someone capable of such good design. If he wanted to, he could have trademarked it, but he chose to give it free to the world and just sort of hoped that it would stay roughly in a shape he would like. Resisting standardisation is a weird thing to do. His notion that ambiguity is a feature is a dumb one. I think this is all relevant to the discussion about whether it's decent/honourable to use a similar name against his wishes. If his wishes are anti-progress, then tough luck, people are going to progress things if they can. He chose not to copyright/trademark anything. He can't have it both ways.

He did copyright everything. Explicitly. In a very short license where one third of the conditions of use was:

>Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Gruber is not being irrational. He is operating under a different paradigm, which he explained last time Marco Arment was on his podcast. He is approaching this from the view that the optimal markdown implementation for a code site like GitHub is different to the optimal markdown for a commenting site like Reddit. Standardisation just locks in a suboptimal implementation for everyone. Whether you agree or disagree, it's at least a rational viewpoint.

The creator of the project let you do anything with it other than use the name markdown for a derivative product. They went ahead and did that. A completely unreasonable move that is just spiteful.

You can't copyright a name, which seems to be his main point of contention judging by the public responses he has offered.

This has nothing to do with my view point, it's simply a fact of law: you can't copyright a name. No matter what text you put somewhere says, it doesn't magically apply.

Standardisation doesn't lock it down, it just establishes a central flavour. It doesn't force Github to use the standard. Github can keep using GFM. It still benefits Github and others for there to be a well-defined standard which they can use as a base for defining their own variations against.

Documenting your own Markdown flavour will be easier if you can say "It's Standard Markdown, plus/except these features...", instead of "It's part of the soupy world of 'Markdown', but here are the features that some/all other implementations don't have...".

> He did copyright everything. Explicitly.

I didn't realise that. In that case he can force them to change it if he doesn't like it, right? I don't get why people are talking about honour/decency.

If you create an open format without any standardization, what do you expect? Does every implementation of markdown need Gruber's blessing? They're not stealing his idea or anything. He's given proper credit for inventing markdown in the first place.

Another way to look at it is this is just another implementation of markdown -- one that some of the bigger names in the markdown-business are going to support moving forward.

Given that it'll have StackOverflow, GitHub and Reddit behind it, that's definitely a large enough boost (or at least a large united front) to have this flavour be dominant. What does that Venn Diagram look like, I wonder: SO, GH, Reddit inside the whole online Markdown community.

Gruber seems to be a bit of a dick about it. Maybe he got surprised and it hit him harder than expected today. No surprise though, he's now about to be usurped. He sat on his hands for years. In the release today (and forever) they give him large amounts of due credit. The Talk Show crowd (I'm a listener) will grumble, and fanboys on Twitter will support him and jeer Atwood personally, but oh welp. There's one party actually advancing technology, the other resting on laurels.

He kind of mentioned being a benevolent dictator on the [podcast 88 discussion](https://overcast.fm/podcasts/episode/344902019595#t=4527), but what important decisions has he actually made lately? It seems to me he just points back to his implemention perl script. Genuine question. He hasn't made a spec because (loosely) "why have a spec; just do whatever you want, take a look over here".

So it's a variant of his perl script. Great, that sounds exactly as he mused everyone should do. I can see how it rubs him the wrong way with "Standard Markdown".

Also: by doing this, the group will be forcing his hand. They've released it magnanimously, invited him to be a part of the process for years. He didn't respond in kind, labeling it "Atwood's crusade".

He may not like the name "Standard" enough to do something about it. He can choose to pursue legal options. I doubt he wants to spend any money on that. You've got to assume GH, SO, and Reddit went over the Markdown license on DaringFireball.

He can choose to be grumpy about it, but this is happening. Those 3 entities have massive persuasive force with their user bases; enough to become standard.

Then they should call it Big Site Markdown. Calling this a standard takes regular, varied, simple, use-case-specific, optimal Markdown away from the rest of us.

But if you say your system uses "Markdown" then that's zero help for someone who wants to submit to you a complicated Markdown document for processing.

Ambiguity is not a feature it is a bug. It is not optimal.

> But if you say your system uses "Markdown" then that's zero help for someone who wants to submit to you a complicated Markdown document for processing.

This "Standard" makes things even worse. There are plenty of sites already on the internet that say they accept "Markdown", and that meant something: that it implements Gruber's formatting, and perhaps some extensions (and sites with extensions are normally clear about the fact that they're extensions, e.g. "Github-flavoured Markdown"). Now people will see a site that accepts "Markdown", expect it to support a feature from "Standard Markdown", and get angry when it doesn't.

If you want to submit a big document for parsing make it LaTeX or HTML.

Markdown is not for that and the exact reason to use it is that every site could customize it for their usage. Contrary to your assertions (which I see is backed by no argument) abiguity in markdown is a feature. Ambiguity in HTML was a bug.

Funny, I had a blast writing a 30 page report with R Markdown, which is extended to hell and back (Math support, tables, graphics, whatnot).

You can make it clear that your implementation isn't the "official" one without denying credit. See e.g. Iceweasel; it's very clear that a) it isn't Firefox b) it owes a lot to Firefox.

I agree with Gruber. Ambiguity is a feature. It allows every implementer (leanpub, github et al) to add their own idiocentricities while staying true to Gruber's "spirit" of Markdown.

Everyone is still free to implement their own version. But it seems like many of the people behind the biggest implementations would rather agree on a standard.

They still can. They can be as ambiguous as they want. They just wont be able to advertise it as compliant with "Standard Markdown".

I don't see a problem.

Can the same be achieved with a common core (spec) + 3rd party bolt-on extensions?

But isn't the ambiguity what allows you to make your own version?

Edit: In case what I am writing is misunderstood, I am not trying to be snarky or negative. I am just curious.

I think most people would prefer there wasn't any ambiguity in the first place.

No ambiguity, no 500 different things called XMarkdownY

has there been any standardization efforts which didn't end up with implementation-specific changes everywhere?

admittedly the worst example for such a topic, but, we still don't have a situation where all browsers agree on all renderings, and all of them still don't follow the spec, and in some areas, they don't plan to.

I can see html requirement being a pain-point for anyone implementing standard markdown.

Go for it. Time will prove which side is correct.

Is this the same group of people he brought up on the recent episode of The Talk Show? The group that wanted to essentially take away the original credits (or something to that effect) from him?

I don't think anyone wants to take credit away from Gruber. My understanding is that they want to move the language forward. More people than just Gruber use it now. I haven't been following him much recently, but for a long time his attitude was, basically, "You can't change anything without my approval but I'm not going to invest any time in this." The way he has handled Markdown's success over the last few years has not engendered my respect.

Why is it important that the new thing have the old name?

Reducing user confusion is one possible answer, but I expect if you are going to argue that, you end up with the name not mattering because most of the users aren't even aware of it.

People are definitely aware of the name. It would be a complete non-starter to have a name that didn't reference "markdown" in some way when the project is an effort to standardise markdown.

There are certainly a large number of people that are aware of the name, I'm not disputing that.

My point is that there are tens of millions of redditors that aren't. I would also guess most light users of Stack Exchange sites are not very aware of the name.

For all those people, I don't think the name matters. Also, the heavier, more interested users will likely not be disrupted much by a different name.

I assume the baseball thing was his requirement to sign off on this, or an attempt to placate him...


Applications are open for YC Winter 2018

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | DMCA | Apply to YC | Contact