Ok, I had challenges with statements like this in the article:
All of this means that it is not possible to write a simple rule for when a paragraph (or other block element) ends.
Except there is a very simple rule, block elements are terminated with a blank line. The argument that changing
line 1
--- < this is inserted between two blocks
line 2
Really changes the 'line1' from a block element to a header element (its no longer followed by a block line) which has not a lot to do with parsing but more with lexical analysis. And then later the author reveals what is perhaps their actual thesis statement "Markdown became so popular because it was simple and somewhat extensible." which I would agree with if the period had landed three words earlier in the sentence. :-)
CM is a nice spec for a "markdown like system" :-) with many of the ambiguities rubbed off the edges. Add tables and I'll totally switch from multi-markdown to this more 'elucidated' specification.
I'm really surprised that so many people are hung up on Atwood et alia trying to bring some explicitness here. I've been using Markdown(tm) derived systems for a few years now and have felt the pain of many of their points directly.
I think the explicitness is the one aspect which has been widely well-received. We all know the pain of an inexplicit Markdown, and CM did a fantastic job of addressing that.
Much of the frustration, at least from my eyes, is because CM attempts to incorporate too much of the mess that Md once introduced. I understand they did this in the interest of keeping compatibility with most "Markdown" documents. But they had the opportunity to fix things up, and really I wish they did.
The quintessential example here is the inclusion of HTML. By allowing html to be mixed in, Gruber really allowed a lot of flexibility and versatility, but that only makes sense if the content could be trusted and that it will only ever appear on the web. Tables are a great example of reasonable html usage- they are supported in both Md and CM. There are a lot more examples of unreasonable HTML usage, which I'd rather not enumerate.
These days, with the proliferation of Md as a widespread content language for public discussion across mediums, HTML doesn't belong. There are other cruft and ambiguities that CM could have cleaned up easily. CommonMark had the chance to improve this situation, but they went to great lengths to embrace it. If they had considered themselves as a distinct dialect instead of "the" standard, they may have gone a different route and written something more modern and clear.
The project is no called longer "Common Markdown". It's CommonMark [1].
From Atwood's announcement yesterday:
Edit: after a long and thoughtful email from John Gruber – which is greatly appreciated – he indicated that no form of the word "Markdown" is acceptable to him in this case. We are now using the name CommonMark. [2]
Anyway, the reason the specification is complicated is because creating a regular grammar from a rich irregular grammar requires a lot of work. Things like reading ahead to distinguish between:
paragraph 1
%%%
paragraph 2
and
paragraph 1
---
paragraph 2
The goal is to help companies like StackExchange and Github get out of the markup language business by solving a set problems that aren't really on the radar of individual bloggers using markdown, but that very much impact websites at scale.
The article is a case in point - StackOverflow can't be efficient if it's pushing an entire parser into the browser. It needs to degrade gracefully when javascript is off.
In general, the world will be better off when the canonical markdown documentation is not written with a tiny font on a grey background. Perhaps we'll even see markdown [or CommonMark] begin replacing RTF and BBCode more places.
That's a very good writeup, and his points are important for anyone to consider before proclaiming support for the CommonMarkdown effort. I wish there were way more discussions like this of the technical merits of CommonMarkdown than the name.
While I'm very supportive of some kind of sane Markdown specification, it's pretty disappointing that those with the biggest audience to push a specification have created such an apparently poor one. And after 2 years! Spec-by-examples, especially for an inherently ambiguous and forgiving syntax like Markdown, should be known to be a bad idea.
I've tried to use Markdown for very simple formatting (to have two consecutive paragraph have a wrapper style, e.g. to have a note style) - and failed. I've tried various parsers, wrote my code hacks (also called: extensions), regex replacers whatnot, just to conclude, that even if I am able to do that, the live preview will suck.
Fast-forward today: I've started to use Asciidoc with the Atom editor and its Asciidoc live preview. I'm using asciidoctor to generate docbook, and xslt to get it formatted in the way I want. I feel productive to write the content, and I can control every aspect of the output, in the very specific way I see fit.
A simple blog post with a bunch of paragraphs and bold styles may not be worth it, but anything more complex will favor asciidoc.
Out of curiosity, why not write DocBook directly using a WYSIWYM editor -- for example OxygenXML? Edit: I don't think it's worth using for blog posts and such, but for anything that you plan to publish -- papers and books -- it works very well.
Do you review your own changes, or someone else's? Asking because the former is unusual, but the latter works much better with OxygenXML's built-in change tracking. It's fantastic for working with editors (in combination with, say, Subversion).
Both. Also, I have sometimes a doc edited on google docs, then copied over to local file and formatted in asciidoc. After that we put it back to the google doc in asciidoc markup, and subsequent comparison and merging becomes a way lot simpler.
Good article. I also agree with his approach of taking Common Markdown and breaking it up into a core, and then extensions. That means parsers can be standards compliant while working in environments and situations where certain features don't make sense (e.g. something that takes in markdown and outputs to an programmable LED sign, won't need URLs, HTML, and so on just formatting).
I wish Hacker News had markdown.
Off topic question: Why has rich text fallen so far out of fashion? I really like Markdown, but why is it that Markdown is now so popular and richtext boxes that can display a realtime preview (e.g. bolding text, italics, etc) aren't. What is it markdown offers over that? Is it just transportability?
One nice feature is that markdown makes text annotations explicit and obvious. There's no hidden styling. Empty lines don't have a font size. Its obvious when a bolded region doesn't bold the spaces between words. In the Rich Hickey[1] sense, markdown is much simpler than rich text editing because all you have to worry about is the semantics of your text (this is a heading) and not how its actually styled.
Weirdly, its kind of a huge throwback to LaTeX. Thinking of markdown as a "modern, simplified LaTeX for the web" seriously hits the mark.
> Off topic question: Why has rich text fallen so far out of fashion? I really like Markdown, but why is it that Markdown is now so popular and richtext boxes that can display a realtime preview (e.g. bolding text, italics, etc) aren't. What is it markdown offers over that? Is it just transportability?
A very good question. I think it's because once you can type fast, having to take your hands off the keyboard to use the mouse to select text, apply various styles, add links, etc. is slower than just writing everything with the keyboard without raising your hands.
I think you're mostly right - I'd just add that perhaps the lack of (real estate) space on most mobile devices discourages wasteful and hard-to-henpeck toolbars.
Plus, as others have pointed out, there's that 1/2 MB entry fee. Expensive on transit and on local resources.
Maybe also a correlation with the kinds of people who write nontrivial text on their mobile devices, and are comfortable with in-line markup?
I don't need to use the mouse with Markdown. The keyboard is sufficient, and once you have a bit of practice it's easy and quick to use.
Additionally, I think it emphasizes the styles that are important in social media (blockquotes, code, bold, and italics) while de-emphasizing those features that are less important to it. The rich text editors, even on the web, all have a standard layout of buttons which displays all the wrong features first.
Rich text editing on the web is complex, Markdown is simple. Adding rich editing for something as simple as a comment box typically means adding something like TinyMCE: half a meg of JS to build the edit UI and attempt to paper over browser quirks and edge cases. Markdown is just a <textarea> plus a call to your renderer on the back end. It's offloading complexity to the user.
The reason I wouldn't use a rich text editor is it leads to "support issues".
It wasn't because the implementation was buggy but rather the fact the end-user thought it should behave like word and just copied/pasted stuff.
Rich text editors are more complicated and tend to have usability issues. I had to support one for a year with very, very average users who used the application infrequently.
Browsers don't have good controls for entering rich text.
So you're left with trampling over the input experience with a lot of javascript. It breaks things like the "it's all text" extension, and generally will only work for the subset of configurations that is tested for.
If browsers had decent html-editing widgets, it might work better. I've yet to see any form of rich text editing that doesn't lead to frustration (never mind works on mobile touch etc).
Google has an interesting solution for G+ -- they've broken plain text entry (and plain text paste of long texts) without giving any benefits of rich text entry. But I'm sure it's great if you live in a bubble where no-one's used an actual text editor, and gwt is the best set of widget anyone's heard of. Facebook on mobile (in a mobile web browser) is pretty awful too, if you try to use the completion-options for tagging friends.
Come to think of it, I'd only be half as upset with g+ if one could simply upload a utf-8 text file into all of the comment/edit boxes.
Partly simplicity and ease-of-use; partly probably so many users (and developers who are users) being burned by bad implementations of WYSIWYG editors.
I think GMail's is pretty decent, but the majority of rich text editors I've used on the Internet over time have caused almost as many issues as they solve when trying to write formatted text.
According to the vfmd spec history[1] the first version appeared in july 2013. According to the other project[2], they started "about two years" ago. It would be impossible for the former to discover the latter, given that the work was behind closed doors. The people in the latter group probably did not bother to look at alternatives while they were pursuing their own solution.
wow, gruber is more of an ass than I thought. His modus operandi is blow off private communications and have a public tantrum
We've been working on the Standard Markdown project for about two years now.
As we got closer to being ready for public feedback, we emailed John Gruber,
the original creator of Markdown, two weeks ago (On August 19th, to be
precise) with a link to the Standard Markdown spec, asking him for his
feedback. Since John MacFarlane was the primary author of most of the work,
we suggested that he be the one to reach out.
We then waited two weeks for a response.
[...]
and again:
Starting with the name. In his email John graciously indicated that he would
"probably" approve a name like "Strict Markdown" or "Pedantic Markdown".
Given the very public earlier miscommunication about naming, that
consideration is appreciated.
We replied with the following suggestions:
Compatible Markdown
Regular Markdown
Community Markdown
Common Markdown
Uniform Markdown
Vanilla Markdown
We haven't heard back after replying last night, and I'm not sure we ever
will,
Gruber's often an insufferable Apple mouthpiece who thinks way too highly of himself, and has been for the last ten years that I've paid attention. That doesn't keep me from reading everything in the RSS feed, though. Hell, I've even spent considerable sums of money to advertise on his podcast. But this exchange doesn't surprise me.
What does surprise me is how Marco was happy to be one of Gruber's flying monkeys on Twitter. Maybe Marco has an interest in the fight that is unknown to me, dunno.
Anyway, I don't care one way or the other. If forced to care, I'd even side with Gruber on the principles. But don't be shocked that some parties handled this in a less than graceful manner.
Motorola makes a watch, the Moto 360, the name being an obvious hat tip to being round. There's a bit of black plastic along the bottom though, so the actual screen takes up a bit less than the full area of the circle. And Gruber certainly seems to think he's very clever in consistently calling it the "Moto 270".
Maybe he has a good argument that they can't call their thing Markdown, but certainly if he starts whinging that they aren't properly capitalizing his trademark, then I think he's behaving in a hypocritical fashion when he quite clearly takes other people's trademarks so casually.
Also, I think it's just as childish as seeing Micro$oft back in the day, but I guess that's a matter of taste.
Wow, I really don't understand how this man has such a following. Everything I hear about him is so petty (not to mention that everything about his blog is written to somehow conclude that Apple is some sort of god, even when the source is completely the opposite)
Are they working towards building a formal grammar? I thought so from yesterday's discussion, but I don't know how hard would be to get a sane BNF for markdown
<script>
var CONTENT = '' +
"Why Common Markdown isn't the Solution\n" +
...
That's probably the most roundabout way to put an article on the web. You are inlining Markdown in an HTML document. Then the browser has to parse and execute 4.5 MB (!) of JavaScript and then it can finally turn that Markdown string into HTML.
HTML documents are a pretty good choice for, y'know, HTML.
Well, if your goal was to increase the page weight from 10kB to 2.2Mb, you surely succeeded.
Oh, I'm quite aware :). It's an effort of extreme dogfooding of https://github.com/khan/perseus. This post doesn't use anything interesting, but if I wanted to post about some of the interactive math content we're doing there, I could actually embed it. It is also useful to learn how annoying it is to embed (answer: much more annoying than I'd like).
I suspect this pattern will continue into perpetuity because such a large audience will never come to grips with the fact that "better" isn't always better.
SOAP is not a clarified, less-ambiguous, consistent standard developed from REST for the same role. (Heck, they aren't even the same class of thing -- SOAP is a protocol, REST is an architectural style. And SOAP is signficantly older than REST.)
RSS:Atom might, arguably. be very loosely analogous to Markdown :: Common Markdown.
I think the key one here is "XHTML:HTML". Like HTML markdown offloads the responsibility onto the parser writer to figure out what was intended. So while I sympathize with Github and Stack Overflow, as a user it should just work. And usually does.
All of this means that it is not possible to write a simple rule for when a paragraph (or other block element) ends.
Except there is a very simple rule, block elements are terminated with a blank line. The argument that changing
Really changes the 'line1' from a block element to a header element (its no longer followed by a block line) which has not a lot to do with parsing but more with lexical analysis. And then later the author reveals what is perhaps their actual thesis statement "Markdown became so popular because it was simple and somewhat extensible." which I would agree with if the period had landed three words earlier in the sentence. :-)CM is a nice spec for a "markdown like system" :-) with many of the ambiguities rubbed off the edges. Add tables and I'll totally switch from multi-markdown to this more 'elucidated' specification.
I'm really surprised that so many people are hung up on Atwood et alia trying to bring some explicitness here. I've been using Markdown(tm) derived systems for a few years now and have felt the pain of many of their points directly.