John Gruber's original Markdown.pl is one of the worst small programs I have ever read, completely riddled with outright bugs and misfeatures that continually bite its users in the ass. It's awful even by the already low standards of hand-written many-pass regex-based spaghetti-parsers.
Nobody should be using the original script, and unfortunately many of the other implementations out there are direct transliterations that replicate all of its absurd errors, like where if you mention the MD5 hash of another token in the document, the hash will be replaced with the token, because it uses that as an inline escaping mechanism! Reddit got hit with a XSS virus that got through their filters because of it: http://blog.reddit.com/2009/09/we-had-some-bugs-and-it-hurt-...
See the changelog for what started as a PHP transliteration and turned into a rewrite that squashed 125 (!) unacknowledged bugs: http://michelf.com/projects/php-markdown/
The worst part is that he outright refuses to either disclaim or fix his implementation, and so far he's repudiated everyone else's attempts to do so. He's a terrible programmer and a worse maintainer, he really still thinks the documentation on his site is comprehensive and canonical. As much as Jeff Atwood leaps at every chance to play the fool, there's no way his directorship can be anything but an improvement.
I'm so tired of this mentality that says basically, if you release something for free on the internet, you are obligated to maintain and support it for the rest of your life. Gruber created this program, for free. You are under no obligation to use it. Don't like it? Here's your money back. It may be true that the code is shit. If you think so, don't use it.
Like other responders, I worry that this mentality causes fewer coders to release their projects, for fear of backlash like this post. Think about it: Your feelings toward Gruber are incredibly negative and hostile, and in fact, you would have better feelings toward him if he had kept Markdown to himself and never released it at all. Does that seem fair to you? If the ill will generated by people like yourself outweighs the good will generated by those who appreciate the code I release, or if I fear that it might, what motivation do I have to release my code?
He enjoys the credit for being the creator of something used by millions every day, but is entirely unwilling to take the responsibility that comes with that creation being a very public mess.
It works for his usage, but all the ambiguities and undefined behaviors affect a huge number of people, and his only response he's made for eight years has been to retain sole moral authority and refuse to use it.
It works for his usage, but all the ambiguities and undefined behaviors affect a huge number of people, and his only response he's made for eight years has been to retain sole moral authority and refuse to use it.
You gain moral authority by actually doing something. If you use markdown, and wish to propose a better markdown than markdown, go for it, I'm sure lots of people will be pleased, but bear in mind that lots of people will whine about any bugs as well, and expect you to work for them for free and spend significant resources and time fixing edge cases which don't matter to you personally, just because you released the source.
If you're ready for that though, of course go ahead and create a better markdown, or help with this proposed spec, Gruber certainly can't stop you. It doesn't really matter what Gruber says, what trolls on a mailing list say, or what you say on this forum about his responsibilities, whether he is self-appointed dictator for life etc (though I'd dispute that), what counts is putting the work in, which is often surprisingly difficult - far more difficult than criticism.
Of course you can do that. I think people's problem is with Gruber's unwillingness to lend any support to those efforts to create a less buggy implementation.
Right now, the canonical markdown implementation isn't very good. It's hard to change what the canonical implementation is without Gruber's support. It doesn't even require much from him - just his blessing.
He isn't under any obligation to do this. No-one thinks he is. But it would be a good thing for him to do.
Frankly, I don't think what Grubber says matters here, and I see why he wouldn't want to engage all the trolls who are enraged by his inaction. Markdown works for him and he prefers it simple if somewhat vague/buggy, if you need something different, build it.
If someone wants to write a spec, a better parser or a better markdown full stop, there is absolutely nothing to stop them. The problem is, people would rather bitch about why no one else is doing anything and complain about gruber than actually do the hard work necessary. Do the work first, then look to gruber for canonization if you must, though by that point his views on the matter would be irrelevant.
I don't think they're asking for lifetime maintenance and support. I think they're asking that if the author is aware of bugs and exploits, they should at least make the small effort to alert users who are still downloading their code.
If the exploits are as well-known as the grandparent comment asserts, and Gruber is aware of them, there really is no excuse for him to leave the code up without any warning that it contains known exploits. However, if he has no idea and everyone is assuming he knows without someone telling him, that's not exactly fair.
What an embarrassing post to be occupying the top of this thread. Blaming Markdown.pl for security flaws? I suppose the memory corruption bugs in the "optimized" C Markdown parsers are somehow his fault too?
He wrote a text-to-HTML parser with a particularly elegant little language design and got on with his life, which involves writing more than keeping up with bug reports in Perl scripts. Get over yourself; comments like this make us all look bad.
> And he did a horrible job of it. Horrible. But he considers himself the BDFL of Markdown. Break that down for me.
Christ, you're being a dick. All John Gruber did to you was design a minimalist markup language and write a quick-and-dirty proof-of-concept Perl script to implement it. Just use a better implementation and get on with your day.
If that was all he did, it would be fine. But it isn't. His website still encourages people to use his script and his specification, even though they are known to be buggy. If you publish something on the internet and it turns out be wrong or defective, you have a moral obligation to point that out, especially if better alternatives are available.
Is it insane to try and keep the good stuff from disappearing under the garbage? Have you ever searched for something, only to come across a multitude of pages that were just incomplete, wrong or otherwise useless? A search term for which the gems are buried under so much manure you need all your Google-fu to find the gem? How do you think this will play out in the years to come?
People like Gruber, with an audience, a following, should set an example. If his code has bugs and he is informed of those bugs, he should take a few minutes to list those bugs. He doesn't have to solve them. He doesn't even have to point people elsewhere. Just listing them is enough and saves a lot of people a lot of time. If you can't be bothered to do that, please take your code down: it is nothing but pollution, keeping us from finding the better code.
This submission, which suggests forking or standardizing Markdown, has currently over 400 points. My guess is that "just use a better implementation and get on with your day" is not a good enough answer for many of us, including Jeff Atwood and David Greenspan.
This would be a lot stronger argument without the ad hominem bits. He's obviously not so terrible if he created this thing that has people so up in arms.
I think there's something to your post, but the tone makes me want to dismiss it. I know, stupid emotions.
This internet lynch mob mentality... I wonder how much this discourages people from releasing things. So, Gruber releases markdown.pl. People like it. People love it. People use it, people reuse it, people rewrite it. Next think you know, he's being insulted on the internet because he released something he wrote to serve his needs and not passing on some sort of figurative mantle or blessing.
> He's obviously not so terrible if he created this thing that has people so up in arms.
Oh please, double standards like this disgust me. Microsoft had shit slung at it for years on end by the tech community because IE was terrible and held back innovation on the web, but no one claimed that IE is "not so terrible" just because everyone cared about it.
The difference with Gruber is that he's a darling of the tech community because he's Apple-anointed nobility. But as a programmer, in my eyes (and in the eyes of any other objective observers) he's absolute shit.
The reason Microsoft is dead to many developers (myself included) is that they used their massive corporate power to shut down good startups making cool stuff.
I didn't care that IE was terrible (until v3 or whenever), I cared that Microsoft went to all the major PC manufacturers and told them that their licensing deals were toast if they preloaded Netscape.
I didn't care that Word was a crappy word processor, I cared that they used their market position on office documents to make minor incompatibilities that prevented WordPerfect from interoperating.
I didn't care that Windows file sharing wasn't half as good as NFS, I care that they continually fucked with the SMB protocol so that no one could sell UNIX machines that could share with Windows networks.
It has been an absolute pleasure watching that Microsoft's power over device makers disappear. The world is better off for it, and Microsoft will always be an asshole in my book.
There's a differenc between trying to maintain app store policies that strike a balance between security, end user interests, developer interests, profitability, etc. and intentionally putting bugs in your OS to break third party products, stealing third party products and building them into your OS, or bundling free products with your platform or office suite to drive third parties out of a market.
No, the difference is that Gruber is a person whereas Microsoft is a corporation. Corporations aren't subject to the same social mores - it isn't hurtful to say something nasty about a corporation.
Abandoning basic etiquette that you should have learned in primary school and calling someone "absolute shit" is not cool.
While I agree that calling somebody that is not cool, I think you'll find that product owners at corporations do take it to heart when harsh criticisms are called out. They identify with their output.
The thing is this isn't something new, I and a number of other people have been enraged by this for eight years now.
Over those years it's grown in usage exponentially, and so has his fame as a sportswriter for team Apple. Throughout that period he's continued to brush off all kinds of attempts to clean up bugs, define ambiguous behavior, or fix the security vulnerabilities. It hasn't mattered what approach people have taken, he just does not give a shit. Here's an example from last week: http://six.pairlist.net/pipermail/markdown-discuss/2012-Octo...
He's spent so long burning off any goodwill I would have for him on the matter, being cordial just isn't a priority anymore. NERD RAGE.
You've been enraged by the handling of a text-to-HTML converting Perl script written by a tech writer?
You're right: he just does not give a shit. I can see why. What possible upside could there be to engaging with someone who handles themselves like you are here?
You've never been enraged by poorly written tools or technologies? There have been times I wished I could reach through my monitor and throttle some well-meaning idiot for wasting hours or days of my time.
Imagine that you're a mechanic working on a motor that uses the ProprietaryNew fastener (hex heads? so 20th century!). Unfortunately, the only ProprietaryNew wrenches are made out of cheap metal, and the sockets strip with regularity. You can't imagine saying a few nasty words about the parentage of everyone in ProprietaryNewCo?
Actually I think he does give a shit, he just feels that things could be a lot worse than they are and tinkering isn't necessarily going to improve things. Given how widely used it is there is some merit to this argument.
From a comment on Twitter yesterday in response to someone, it doesn't seem that Gruber is particularly interested in engaging with this (though I may be wrong). If that is the case I suspect we'll see a forking of the project and we'll get to see whether a committee will do better.
It may well do - Jeff has a good track record at getting things done and is well respected and well liked - but personally I wouldn't put my mortgage on it because as well intentioned as these things are we all know how design by committee usually turns out.
Care to show us your alternative? It'll be on Github or GoogleCode, or maybe your personal blog, somewhere we can download it, try it out, and criticize it too, right?
Surely 8 years of rage is enough encouragement to write your own replacement for ~1000 odd lines of Perl?
Or by "enraged", did you mean "annoyed enough to write critical posts on random internet sites, but not motivated enough to spend an evening or two solving the problem myself"?
"The real problem cannot be solved without some forward action on his part."
Sure it can - you write something better, then get everybody who's already using Gruber's version or one of it's presumably also-flawed reimplementations to switch to yours. Or, is "8 years of enragement" really just keyboard-warrior-hyperbole on your part and an excuse to criticize someone who's achieved widespread adoption of some code you claim is 2nd rate, but which haven't bothered to improve or replace?
Besides, it sounds to me like David Greenspan has come up with a fine solution.
The perceived simplicity of the format (driven by the naivete of the implementation) played a significant role in making it popular, but lays a minefield of bugs and ambiguities for implementors especially if they want any combination of sanity and interoperability.
I find it disheartening that the top voted comment is so blatantly rude. I'm not sure what is gained by calling John Gruber a terrible programmer and maintainer. If you want to praise Jeff Atwood for taking over the stewardship of Markdown, great.
Christ, maybe I should pull all my open source projects that I no longer work on down from github for fear of people actually using it and then complaining when I don't maintain it indefinitely.
The dude released a script to the public under a free software license and people used it. If you think it's bad, fork it and fix it, otherwise don't use it, that's how the open source ecosystem works.
There are a dozen MarkDown implementations that are better than Grubber's piece of shit, and a couple that are actually nice. The lack of a decent implementation is not the issue. This issue is that Gruber is (regrettably but naturally) seen as the authority on MarkDown by a whole lot of people, and he's still encouraging them to use his insecure, bug-ridden disaster instead of pointing them in the direction of something that anybody outside of his use case would ever want to use.
He just needs to add a sentence or two to his website and he'll save countless developers a ton of headache. He just doesn't give a shit.
Yes, you should take down such projects if you have been informed of problems and can't or won't take the time to document them. Infinite maintenance is a straw man, because that wasn't requested. Only some civility was requested.
Your project can cost people a lot of time if it promises, but doesn't deliver. I just spent quite some time searching for a decent XSD parser in Ruby, haveing to wade through a score of projects that promise to do what I want, but turn out to be incomplete, buggy or otherwise useless to me. Many people will perform the same quest and together a lot of time is wasted, which could have been prevented if people would not just publish any damned thing, but would also take the time to properly document its state.
Open source projects without proper documentation, I can do without. This problem will only become worse in decades to come. I sure as hell hope github will start purging old projects with too many 'not useful' votes within the next few years. Otherwise it'll be a morass of stink where the gems can no longer be found.
I thunk the point he's trying to make is that if Gruber doesn't want to maintain Markdown, that's cool. However, he should announce that and let the community take over.
Get over yourself. The guy wrote something that suited his own needs and released it so that others could use it too if they wanted. Programmers ported it to other languages because they liked the idea and wanted to see it thrive -- I've used the PHP port in many homespun web apps over the years. Is it perfect? No, and no software is. But when I've needed a script that easily converts line breaks and hyphens into paragraphs and unordered lists (the normal use case I've taken advantage of), it's done the job every time.
This is one of the reasons Why left the programming community. People are not thankful. Even if you release a great idea - with obviously _not_ the best code - the one thing you get is criticism. Maybe also the words that "you are the worst programmer on earth" following the words that "you put your family in such a shame".
You know what programmers think because of such comments? "My code is so bad I can't release it. Even if the idea is good." And this Sir helps no-one.
> You know what programmers think because of such comments? "My code is so bad I can't release it. Even if the idea is good." And this Sir helps no-one.
I agree. This has even stopped me from __starting__ a few FOSS projects I've wanted to develop.
What I love here is that not just satisfied with running down Gruber, you also feel the need to get in a little swipe at Jeff ("as much as [he] leaps at every chance to play the fool"), a man who seems broadly in agreement with you (though is far more constructive in his approach).
No. I was curious and checked - this: https://github.com/waylan/Python-Markdown is slightly below 3k loc mark (2977) excluding extensions, and by the look of it it's much more heavily commented (I didn't strip blank lines or comments at all). Markdown.pl has 1450 loc.
So - no, bullshit, you need to multiply by 2 at most in case of Python :)
Another interesting comparison would be with the Text::Markdown CPAN module which is Gruber's original code & comments converted to an OO interface with POD documentation added + bug fixes.
Wow, I wasn't expecting my email to Jeff to end up as a front-page blog post!
The point here is that Markdown doesn't have a spec, nor do any of its variants to my knowledge, so I was proposing to come up with some Markdown-like language that does have a spec. Under discussion here is the more ambitious (but also appealing) plan of writing an official spec for Markdown, the same way JavaScript got a spec in the form of ECMAScript that we now identify with JavaScript itself.
A spec is a long, tedious, human-readable document that explains the behavior of a system in unambiguous terms. Specs are important because they allow us to reason about a language like Markdown without reference to any particular implementation, and they allow people to write implementations (Markdown processors) independently that behave identically. The Markdown Syntax Documentation is not a spec (it's highly ambiguous), nor is any implementation (not human-readable; some behaviors are probably accidental or incidental and difficult to port perfectly). The hard part of writing a spec is codifying the details in English, and secondarily making decisions about what should happen in otherwise ambiguous or undefined cases.
My motivation for working on a Markdown spec is first and foremost avoiding "bit rot" of content, which happens when we write content against one Markdown implementation and then later process it with another. We don't have this concern with HTML, JSON, or JavaScript, or at least we know what bounds to stay within to write code that will work on any implementation. This is achieved through specs, even if only implementers ever read them.
I would love pointers to Markdown processors that are implemented in a more principled way than the original code, for example using standard-looking lexing and parsing passes, but that still handle nested blockquotes and bullet lists together with hard-wrapped paragraphs.
Specs are important but I'd argue a conformance test is equally or even more important.
With a conformance test people can test their implementations and when ambiguities arrise new tests can be added or old tests fixed. Without, conformance tests different interpretations of a spec lead to divergent behavior. Once that behavior is out there long enough it becomes difficult to fix as people are depended on it and/or its quirks.
I'm confused. How are you supposed to have a conformance test without first having a spec? To what would the implementations be conforming, if not a spec?
Sorry, What I meant to really say is specs are not sufficient. Sure specs are important. But even with specs, without comprehensive conformance tests implementations will diverge.
I work on the WebGL spec and tests based off the OpenGL ES spec and tests. Even though the OpenGL ES spec is long and detailed, every edge case for which there is no test is broken or different in one driver or another.
It's entirely possible to build a conformance test suite around an existing 'black box' of code and accept that whatever it does, even stuff that might be considered a bug, is what any compliant implementation should also do.
(You could also fix some of the more egregious bugs, and then expect implementations to follow your new behaviour)
> Without, conformance tests different interpretations of a spec lead to divergent behavior.
I think you mean either:
> Without conformance tests incorrect interpretations of a spec lead to divergent behavior
Or
> Without conformance tests different interpretations of an ambiguous spec lead to divergent behavior.
Conformance tests should test specific behavior defined in the spec. Tests will never (or rarely) prove spec conformance but spec conformance should always prove test conformance.
Is there actually a notation and + operator for which 1 + 1 = 2 is ambiguous? Only being semi-rhetorical, I'd be interested to know if there is one. (Modular arithmetic is not considered ambiguous, at least not in the math neck of the woods.)
Not really answering your question, but more to the point of the discussion in my opinion, a() + b() could be ambiguous if a() and b() are functions with side effects and the evaluation order of the +-operator is not specified.
> 1 + 1 = 2 Is fairly unambiguous until you introduce operator overloading (and why i despise overloading).
What is it specifying—or, perhaps a better question, what would an implementation look like? It might be more precise to say "I have yet to encounter an implemented spec that was not in some way ambiguous."
That's not how addition works. You're either adding the vectors or you're adding the magnitudes. You don't get to sleight of hand by writing one and adding the other.
You should look at Pandoc[1]. It's a Markdown-to-everything converter, and though I'm not super familiar with the code I believe it's well written. One of my favorite tools for writing.
You also need to add that the parser of Pandoc is not regular expression based. It is a very robust parser, parsing the document in an internal abstract tree you can easily modify. You can also adapt the parser to your needs with simple extensions. You can then get very nice outputs in HTML or PDF[1]. As it is a nice command line tool, it is easy to generate everything with a simple Makefile too.
+1 for Pandocs extensions. I can verify that is sufficient for producing a doctoral dissertion (in German; not my own…), via LaTeX.
The way Pandoc handles citations, footnotes, tables(!), etc is just delightful.
I'd also like to note that some parts of Markdown from the user perspective are non-intuitive and clumsy.
Such as links and images (inline).
Markdown works so well because it is intuitive and appeals to those who once saw old word processors. They don't have to worry about syntax, and can just enter their text into a textarea (free from JavaScript WYSIWYG interference and the inherent troubles of running that on old and new mobile phones, their playstation, web browsers, etc)... and it just works.
Yet some parts of markdown are simply not intuitive. Links and images are two places where I see in usability testing that the end user will constantly refer to help documentation to figure out how to do it.
Beyond getting the code consistent, maintainable, and testable I'd love to see the language itself solve some of the papercuts that trouble the lay end user.
Realising that what I was planning to do for my project (discussion forums, tumblr for forums) was to create an alternative to markdown that would resolve some of these user issues as well as parser issues, I had already decided that I would not call it markdown and that I would educate my users in something new that hopefully solves their and my needs and would remain very stable due to a well-thought out and documented design in the first place. If what you're proposing is in this vein then consider my hat thrown in, what help I can give I will... take me to your git repository.
This is sort of my problem with the whole genre of "light" markup formats.... ultimately they are still a bunch of arbitary conventions to remember, and at that point you might as well just learn/write HTML. YMMV.
Strictly speaking, that isn't the problem being solved by Markdown, either.
Remember that Daring Fireball does not have comments, so this isn't a concern. Markdown was something originally created to solve an authorial problem, not something for forum creators to use for comments.
It's flexible enough to do that, but it isn't the purpose of Markdown.
Why not? You have to protect against malicious HTML injection whether or not the user is using markdown, plain text or html, so why not let them use a carefully restricted subset of html?
While this is not wrong, markdown involves much less typing than HTML. Also, should one need to use HTML, markdown does allow one to switch between HTML and markdown.
They're arguably less arbitrary than HTML; most of them are based in things that people have done/tend to do with plain text when they're trying to create a formatted document. That yields two benefits: the source document is inherently formatted -- transparently so, since even people who don't know what Markdown or the like is will be able to read it -- and creates something of a visual mnemonic for the formatting convention.
Not saying any one implementation is perfect, just that they have these nice properties.
Having wasted a lot of my life reading miles of reddit comments, there are some people who don't understand the link syntax, or switch the brackets ()[]. It happens. But not that often, when the alternate way of posting a link is to just paste it in plain text with no title associated with it.
I look at it like this: [this] looks a bit like a button you might press (or a link you might click). It looks like what it does.
(this) looks like something you'd whisper off to the side --- to add to the conversation. For example, "That picture is nice (but it needs more trees).".
So links go like: [this is the thing you click](and btw, this is where it leads).
In normal text, we usually link to things by first citing them then providing the link. An example would be Google (http://www.google.com). Its natural that we surround the link in () in normal text.
Now the bit we add to help the parser is to tell it where the thing we're linking to begins and where it ends. [ and ] are not usually found in normal text and are therefore used for this purpose. Thus the modified example would be [Google](http://www.google.com).
I would much rather see a more mnemonic approach for links, where you would write either _click here_ [http://wherever.com] or _click here_ (http://wherever.com). The underscores look like an underline, which is the traditional appearance of link text in HTML. It's easy to remember. Whether the URL is in square brackets or parentheses (maybe either one would be acceptable as long as they are a matched pair) doesn't matter, but underlining the anchor text is the way to go, IMO.
Markdown has this brilliance in that it's not just random markup that produces html or something output, it's own human-targeted plain text output is its own source. A such the link syntax is extremely easy to remember. When I write text, I want to read the label, whose reference is a link, hence the order is label then link. If I wrote this link in pure plain text I'd simply naturally write:
Lorem ipsum dolor sit amet (http://www.amet.com), consectetur adipiscing elit.
So the order is the same is markdown since it's its own output. Still the world is not ideal so we need a hint to tokenize a little, and since parentheses surround the link, let's use square brackets. This also fits very well with the array/hash/dictionary syntax, where you associate a key sitting between square brackets with a value.
If I want to make a more remote reference so as not to interrupt the reading flow with a big link (remember that markdown source is its own plain text output) I can simply do what I'd do if I inserted a reference, that is annotate the label.
Lorem ipsum dolor sit amet[1], consectetur adipiscing elit.
The footer naturally follows, as we again assign a key to a value. And since there can be an optional title to the link, it comes afterwards so that urls vertically align.
Again, I find brilliance in Markdown in that it leveraged long (as in decades) established conventions (e.g headers, italics, lists, quotes, code blocks...) that apply directly to plain text in order for the source to be its own output, so that even for someone who doesn't have the first clue about Markdown it's readily readable as if it were not markup.
The fact that Meteor wish to call this Rockdown suggests to me it is to change it.
By creating a specification and tests, they will be modifying Markdown even if just subtly enough to remove bugs and ambiguity. Doing even that is to create something that isn't Markdown, existing Markdown parsers may do something different with the same text... so clearly this isn't Markdown.
It may share 90% (or more, or less) similarity with Markdown, but some areas would certainly need tweaking and changing to make the goal (specification, testability, consistent implementations) possible.
To my understanding this means that Rockdown is Markdown inspired/derived.
And as such, that there is a hope that a good specification and the ability to be implemented in a testable and consistent way... will, by mass use (on the sites mentioned), eventually result in Rockdown superseding Markdown.
In my universe, I'm simply looking to get rid of bbcode as the markup syntax of choice. And if you were at the support end of trying to tell people how to insert images on forums then you'd understand that the Markdown syntax is a real difficulty for a lot of people.
The path that I prefer is to use Markdown, but the areas that cause the greatest difficulty in usability testing, to modify those to make things more implicit and frictionless. Worrying about []() (or vice versa) is an obstacle to the user that shouldn't exist. But if everything else is good from a user perspective then I definitely want to keep that stuff.
I still get those the wrong way around [text url] often enough. I only mess up MarkDown slightly less often because I write more of it.
The "() is more common than [] in regular text, so it makes parsing-sense to start a special markup code with []" is going to help me with that, though. That particular mnemonic only works for coders, though :)
Also, doesn't MediaWiki syntax sometimes also have a pipe | between the url and the text in a link? Or is that only for internal links?
Why are people still interested in Markdown - what problem is it solving and for whom?
It's 2012 and we have HTML 5 compliant WYSIWYG text editors. We no longer have to write plain text littered with special codes, for the purpose of running through a parser, to produce HTML which looks nice on a web page. Maybe it made sense a decade ago when web forms had terrible editors, but not anymore. I think Joe Internet writing blog posts and forum replies would agree with me.
For developers, a README file in plain text looks great everywhere, and avoids any Github vs Bitbucket vs Assembla display issues. If you need to write structured documentation for a system, there's probably already a designated markup language you're supposed to use, so Markdown doesn't help there.
I think you are grossly overestimating the quality of current rich text editors... None of them produce reliable clean code. Some produce less shitty code than others, but they do so through tremendous amounts of post-processing.
Markdown just works and always produces clean, easy to style code.
I am in love with plain-text files. I edit them easily no matter what device I am on, whether it is my desktop, my phone, over SSH, in a browser. I can use my more powerful text-editing software instead of being stuck in a weak WYSIWYG editor.
My blog is just a directory of Markdown files that get compiled into HTML files. No cumbersome WordPress or other blog software installation I need to maintain, just copy the HTML to the server. Simple.
Same thing with documentation. Write once, from anywhere, output clean code to multiple formats: HTML, LaTeX (and PDF, DVI, etc. from there). No need to worry about making sure complex documentation toolchains are installed, just a Markdown compiler. A huge advantage of Markdown is that the source is as readable as the output. JavaDoc, for example, sucks in this regard if you try to do any formatting (lists, tables, etc.). If I am reading the source code--and I prefer to read the source if I can--then the javadoc is often useless for complex functions where it is most needed, because the HTML formatting is unreadable. I am actually building my own documentation system because of this (see https://github.com/jdbernard/jlp if you are interested).
"Why are people still interested in Markdown - what problem is it solving and for whom?"
I understand the question and wonder why it attracted down-votes. The executive summary of my answer: light markup is used in places other than text areas on Web sites.
Many of us use Markdown to keep formatted text in, and, ultimately, to generate valid html markup from. Markdown is not just for textareas in Web pages. Whole books have been marked up in markdown.
Markdown files are just text files with 'explicit' markup within them and so will always be accessible/editable/processable in the future. Markdown is 'flexible' in the sense that it allows alternative markup for the same output, and is 'light' in the sense that a limited range of styling and block formats are available. Compare that with LaTeX which shifts with each tex-live release, and which means that markup written some years ago may not format without hand editing on a modern LaTeX release.
There is the reference implementation available from Gruber's site, and, as others have mentioned, pandoc implements markdown in a way that can be extended. I'm dubious of the need for an 'official' specification; I rather like the scrappy streetwise nature of Markdown.
> Compare that with LaTeX which shifts with each tex-live release, and which means that markup written some years ago may not format without hand editing on a modern LaTeX release.
What? Certainly details of individual packages may change, including addition or removal of functionality, over time, but I don't even know what it means to say that "LaTeX shifts". The underlying markup language for LaTeX, which is the same as that for TeX, is very flexible, but has had the same flexibility since at least 1982, if not 1978.
I understand the idea that built-in extensibility leaves a platform, to some extent, to blame for its plug-ins; but many people in this discussion have proposed building some sort of plug-in architecture for Markdown, too.
> Why are people still interested in Markdown - what problem is it solving and for whom?
For techie types it is familiarity: as a programmer I've used mark-down style syntax in code comments (and emails back when plain text was the norm) for years so it feels natural. I can type and edit text with mark-down faster then with full WYSIWYG control (even if the editor has good keyboard shortcuts). Also I can use the same text+markdown in code, emails and documentation that is desired to look a little fancier - I don't need to reformat for a second audience. Markdown isn't perfect, but for me it is a better solution for some things than WYSIWYG.
Simplicity and resulting cleanliness of mark-up can be an issue sometimes. I've seen WYSIWYG editors get tied in knots over bad HTML that they generated themselves.
Simplicity is another bonus for sites taking in user content, particularly sites like the StackExchange family. By effectively having a while-list of formatting options you can keep a consistent look on your site more easily. If you aren't sure what problem this solves, think Geocities.
It makes security a little easier to: you don't have to worry so much about potential injection attacks that are very possible if trying to generate/accept full HTML and filter it for the bad stuff afterwards (you still have to be careful to think about these issues of course, but your available attack surface is much smaller and therefore easier to manage).
> Github vs Bitbucket vs Assembla display issues
This is the very problem that people are actually discussing - competing interpretations make mark-down less useful then it could otherwise be, and a global standard might help that issue if it gets widely adopted. Of course many incompatible interpretations already exist and any new standard will face adoption friction, so we may end up in a situation like parodied in http://xkcd.com/927/ (it worked well enough for Javascript in the long run, but I think there were fewer common and slightly incompatible implementations of that at the time than there are of markdown now).
Markdown is fantastic because it restricts the formatting.
When users copy/paste from MS Word into HTML editors the paste often keeps the font from the Word document which is not the proper font for the html page. That results in a messy page layout.
In my experience it's easier for users to understand Markdown syntax than to understand the "hidden codes" in HTML editors when they want to fix the layout.
Sure, but if we could paste HTML between editors and browsers without any rendering or layout issues, there would be no reason for users to look beneath the surface. I do agree that we're not quite there yet.
There is still the need for destination system to fully validate the input to catch badly formed content which may cause unpredictable issues and (more importantly) to screen out injection attacks, which may not be a trivial task. Relative to validating markdown decorated content it is far from trivial.
You can use markdown as source for formatting, but the source is very readable by itself.
This is extremely important for writing and also for fall back purposes. Any time there is any kind of a problem in writing or reading or interpreting, just fall back to source.
People can say html is human readable but the difference is huge. I didn't even know that markdown is parsed on hacker news, I just used stars as underscores as natural formatting.
There's also potentially much much less overhead. Ultimately, browsers and your cell phone apps etc should just format markdown natively, meaning huge performance boosts, as html, css, js etc has just become so complex for many tasks as a consequence of do-everything.
My phone's email client struggles browsing back and forth of what should be just a few small text files and file attachments. It uses way too many cycles since it's also a jpeg and css and js renderer with scaling and everything.
As someone who's used text email and news groups, lightweight formatting is very natural and informative. Those services would not have been possible in the past if they had been bogged down with large amounts of excess complexity.
I guess reducing overhead is not sexy because it doesn't involve new features. In the future everybody will just create their typed static oneliner email as 10000x10000x10000 pixel 100 fps 3D movies of 2 minute length (you see, that's the time it takes to read it), and if some supposedly slightly technically literate person asks that perhaps they should use a word 2020 .doc instead for reduced file size, the answer is "but you can't do a space station flythrough in it".
The sheer popularity of Markdown implies that there are some use cases for it. For example, Reddit uses Markdown exclusively, and I don't believe ALL their users are highly tech-savvy.
Personally, I don't trust or use (if I can avoid it) any on-the-web WYSIWYG text editor, because a) they tend to be slow and clunky and b) it's difficult to predict what HTML they will turn out a lot of the time, and I will often end up needing to edit that HTML.
Also, for common blogging / commenting tasks, Markdown is as fast or faster to use than WYSIWYG editors. I've been faffing around with a forum that won't let me use Markdown recently, and forces me to use its clunky WYSIWYG editor to add lists into my posts. It didn't take long for me to start yearning for the simplicity of linebreak - asterisk - item rather than a multiple-click WYSIWYG process.
I find it more comfortable to write Markdown than to use a WYSIWYG text editor. That the WYSIWYG editors tends to produce really shitty output doesn't make things better.
Markdown and similar formats can also easily be used to produce other output than HTML.
And Markdown is plain text, and that's another appealing factor: Even if you read it somewhere that won't render the Markdown, it is still readable. The same can't be said about HTML.
For some people and some uses, plain text is just more comfortable.
I love the ability to scratch something down in Markdown really quickly, and being able to convert it to LaTeX if I want to, without any hassle.
I'd love to write blog posts in Markdown. Google+ uses the italic and _bold_ syntax in their own posts, which is very useful.
I don't exactly know why it's better, to be honest. Maybe WYSIWYG editors are inherently dependant on their own implementations and rely on people learning the interface.
Text-As-An-Interface is beautiful in it's simplicity. Markdown is the perfect mix of simple markup without the insanity of BBCode.
1. Could you recommend some of these good WYSIWYG editors you claim exist? The ones I've seen are all slow or awkward (basically not having enough keyboard shortcuts) or get confused when I delete part of the text (and usually have all of these problems).
2. It sounds like you are only concerned in producing HTML. I like using markdown for everything. Using the excellent Pandoc I produce both HTML and pretty PDFs from markdown text, with nice looking formulas too. (PDFs are produce through LaTeX, for HTML Pandoc offers several options, I use MathJax).
I often find myself writing short plain text files, usually quick personal notes. Occasionally they grow larger than what I'd call a "short" plain text file, and at this point two extra requirements pop up:
1) they are going to need some structure.
2) odds are, that I'm going to want to show this document to someone else at some later point in time[1].
Markdown offers (to me) by far the easiest transition from "basic plain text note" to "slightly longer formatted document", because most times, all I have to do is continue writing the way I was doing already.
[1] corollary: as programmers know, when reading their own code, "someone else" also includes you in three months time.
Yeah, but whereas git and other version control systems are great with lines of code - and diff works well on that - for text we need a diff that works on lexical units within a (much longer) line or structure.
I know git can be configured to use an arbritary programme for diff - just not sure where to find one...
Many users like their WYSIWYG text editors (even though they are often problematic between older browser versions or with "paste-from-word" or conflicts with other JS-includes). And the expectations are rising - one customer of ours would like a WYSIWYG-editor "with Apple style interface" in the browser, with all the bell's and whistles of a full blown publishing solution including complete layout control, input validation, CMS support and so on. The old TinyMCE fields of his legacy app will no longer cut it.
Meanwhile, I write the documentation for my software in Markdown, because it is the fastest way for me to get structured text from my mind to my machine. And with the help of pandoc, it's convertible into all other text formats, from HTML to PDF and LaTeX etc. (Although the html-with-images to PDF support of wkhtmltopdf is even better, so it's Markdown => pandoc[for HTML] + wkthmltopdf [for HTML to PDF]).
using Markdown you can:
- track versions with tools like git
- using pandoc, you can transform it in html, pdf, latex, beamer, rtf, slidy
- you are sure you are separating style from content
- it can be used everywhere: using console editors like vim (or the simple nano, that I love), text editors like notepad+, gedit. I found out a very nice android app, Epstile, that uses markdown and syncs the data using dropbox.
- just this morning, in the office where I'm working, there was a discussion like "this doc was saved using office 2010 or office 2007?". Using markdown, you can avoid such a mess.
Most tech-type people don't like WYSIWYG. I know I don't. The product that my company makes has a very nice WYSIWYG editor built into it. For a hackathon I replaced it with a Markdown editor and all the other developers went nuts (sadly, for various reasons, it never made it into the real product).
The main appeal is Markdown lets us write formatted text without ever having to use the mouse or figure out what the current WYSIWYG editor's key commands are. Often times -- like making nested bulleted lists -- there just plain aren't any key commands. I'd much rather type a few square brackets and create a nice hyperlink on the fly than invoke some silly menu, paste in my link in the window that pops up, create the display text, etc etc.
Unfortunately, that is absolutely not true in any implementation derived from the original Markdown.pl without a whole lot of bugfixes
Because of the chickenshit way he attempted to escape things by replacing them with their MD5 hashes and then switching them back, you can encode anything you want to be output by the markdown processor. Reddit was owned by a viral XSS comment because of this in 2009, it's been exploited a few other times since.
I do not agree that a spec has to be written in English. Like most natural languages, it is very easy to be ambiguous and to underspecify. Resolving this can make English just as human un-readable as anything else.
Specs like this should be written as executable reference implementations in a well defined programming language. This can very well be human readable, and should be done without regard for efficient execution. It's less ambiguous, amenable to automated conformance testing, and is easier to evolve than a natural language document.
If that's the spec, how do we know which aspects of the executable are really part of the specification and which are implementation details? For (a somewhat extreme for the sake of illustration) example, if the spec is written for Ruby 1.8, do C implementations have to intentionally slow down to match its execution speed?
Of course not. Such a spec would state what are its inputs and outputs, either as natural language descriptions or as types (say, if the reference language supports it).
Everything outside that (e.g. timing) would be fair game to optimize. Moreover, as I hinted at, a spec should not be optimized for speed or efficiency, but rather readability and unambiguity.
> Of course not. Such a spec would state what are its inputs and outputs, either as natural language descriptions or as types (say, if the reference language supports it).
So you agree it wouldn't work for specs to be "written as executable reference implementations in a well defined programming language"?
> Everything outside that (e.g. timing) would be fair game to optimize.
But sometimes you want to specify performance characteristics.
The simple fact is that without just embedding a traditional spec within it, an implementation cannot tell you what aspects of its behavior are "specified" and which are just implementation details. This makes reference implementations inadequate specifications. That's all I was getting at.
> So you agree it wouldn't work for specs to be "written as executable reference implementations in a well defined programming language"?
No, then I would be disagreeing with myself. :)
> But sometimes you want to specify performance characteristics.
For a Markdown processor, hardly. But...
> ... cannot tell you what aspects of its behavior are "specified" and which are just implementation details.
That is a fair point indeed. I was merely disagreeing with the linked article in that a spec should be in a natural language, which I still hold to. Such specs generally have problems with under specifying, leaving too much up to implementation, which often ends with a few main implementations sort of becoming the actual practical spec. Look at browsers over the history for many examples. Your point seems to be that reference implementations might overspecify instead. This is true, but is easier to compensate for IMO. For example with clear types, natural language parts or even by conformance test suites being part of the specification.
I think you're unintentionally moving the goalposts here. The idea I was questioning wasn't "Specs should be written in something other than English," it was "Specs should take the form of an executable reference implementation." AFAIK railroad diagrams are not executable. I'm also not sure how BNF is supposed to specify things like "the map function applies a function passed in to each argument in a list".
What people really want is for all Markdown implementations to be basically the same so they don't have to learn any implementation-specific ideosyncrasies to switch from one to another.
The problem though, as I see it, tends to go away under certain circumstances. And the circumstances, I think, are these:
* If you've got a strong implementation, robust, actively-maintained, and runs fast,
* is easy to obtain, install, and use,
* is well tested and well documented, and
* has just the right blend of sensible additions to the syntax (for example, tables, def lists, LaTeX math, etc.) --- done tastefully,
then folks will just use that, model their own implementations after that, and just overall start considering that to be the standard.
I think this has been slowly and steadily happening with Pandoc.
And, aside from all that, two additional "killer features" that Pandoc seems to have over other implementations:
1. it can convert to/from other doc markup formats, thus making it easy to just convert your existing docs to pandoc-markdown and then use that as your master source format to generate other formats you might need; and
2. with its carefully-chosen set of additional features, it has been slowly proving itself capable of being a replacement for raw LaTeX for certain types of longer technical documents.
My understanding is that there's even some features in the works (for the next release) for converting between markdown dialects --- which would make it even easier to convert markdown files of various flavors into plain standard pandoc-markdown.
So, if you're looking for a standard, I'd suggest that it's for the most part already here. :)
>I would love pointers to Markdown processors that are implemented in a more principled way than the original code, for example using standard-looking lexing and parsing passes...
Have a look at Markdent - An event-based Markdown parser toolkit.
I hope some more thought goes into the usability as well. I find the syntax for links confuses a lot of users for whom I have enabled mark down editing. Wiki style [[link text]] works great if you assume links have no space or maybe something similar. Similarly the syntax for images has also always bothered me.
I have no problems remembering the Markdown link format, but I never remember the expected order in what you describe as "Wiki style" (which is really a style employed by some wiki software - there are plenty of wiki software that uses other syntaxes, including Markdown)
Ugh, no. This defeats the simplicity of Markdown. I do not want to have to remember some obscure implementation versioning string whenever I want to start a new document or comment. Maybe as an option, sure, but I will probably never use it.
I don't know if Reddit's implementation of Markdown is principled, but as a syntax it's pretty ubiquitous so you might have the traction to make it standard.
I might be the only one, but I actually prefer Markdowns handling of a single "enter" without spaces at the end to mean that the paragraph is not finished. It makes writing blogs and various other stuff in Vim much simpler, and I can more easily reformat text to wrap at 80 characters, and have better control over it.
Could I soft-wrap in my editor? Sure, but that would mean that the text files sitting on my hard drive now have very long strings in them making it harder to grep, making it harder to add to git (change a single character, entire line is now a diff :-().
I think this behavior is the better route because it accommodates both crowds. The line-wrap folks can just press enter twice; no biggie. But the console and vim users of the world can continue using line-breaks the way that work best for their environment.
On the flip side, making a single enter start a new paragraph wouldn't really help the GUI users (what's the difference between one line break and two, really?) but it would really hurt the console users of the world
* people typing markdown in text files, where you want to split paragraphs into word-wrapped lines of a sensible length, and consecutive non-blank lines form paragraphs just as they always have in text files;
* and people typing markdown into text entry boxes on web pages, where you would like pressing the <enter> key to actually mean something.
These two situations probably prefer a different default.
Then make the form that the user enters data into be either parsed differently, by pre-processing it, or have some javascript magic that automatically adds the extra two spaces required to make it work.
This way if the user presses <Enter><Enter> then the JS can remove the extra two spaces and it will still be valid markdown.
If this is a change that Jeff really wants, he needs to fork Markdown. This change actively subverts one of the goals that Gruber set down for Markdown, which is that Normal People can use it.
Changing this, especially for people who implement Markdown parsers, is geek arrogance.
The biggest deployments of Markdown — StackOverflow & GitHub — do not squash line breaks. They made this decision because authors did not assume their line breaks would be discarded.
The change is not geek arrogance. It is, in fact, a reaction to how Normal People use it.
If you think that users of StackOverflow and GitHub are “Normal People”, you need to adjust your personal RDF.
My wife is not a geek or a programmer. She will, if forced, learn the intricacies of an idiotic programmer‘s decision to make something easier for him (and it’s almost invariably a him) in order to participate in a particular forum. This is why people put up with crap like bbcode every single day. That doesn’t mean she enjoys it.
Markdown works because it makes plain text readable and formatted nicely. Markdown works because it works just as well in a plain text email as it does in an HTML-formatted email.
It doesn’t work because some geek says that the people who use heavily geek-oriented sites (StackOverflow & GitHub, to use your examples) are in fact ”Normal People”. (And, just for what it’s worth, I do find the fact that I have to join all my hard-wrapped lines back together in SO & GH comments to be immensely annoying. At least their markdown parser for .markdown files doesn’t do this.)
So, no I am not flat-out wrong. I hear geek whining that parsing is made harder because of a design feature that is present because most people don't think about or want to think about “correct” line-endings.
Before you decide that I’m full of hot air, understand that I am working with my wife’s novel that’s written in Markdown so that I can parse it (possibly using an existing well-written-and-maintained parser like peg-markdown or peg-multimarkdown as an intermediate mechanism) and then transform it into the LaTeX formatting required for making her PDF output and the HTML formatting required for making her EPUB (and thus MOBI) output.
I am well aware of how ugly some of it is…but it makes it easier for her to write her novel without falling back to proprietary formats like .docx. I’m willing to deal with some pain as an implementor in order to minimize what she has to deal with.
As such, I don’t really have a lot of patience for this type of geek whinging.
I'd respectfully submit that if your wife is writing a novel with actual line break characters at the end of each visual line, rather than only at the end of paragraphs, she's kind of an edge case. "Normal people" who have been using word processors since the late 70s have had it drilled into their head that you only hit return at the end of a paragraph.
It's my suspicion that Markdown was written the way it was solely to handle the case of blockquotes having ">" characters at the start of each line, and the reason that mattered is because BBEdit and Mailsmith had commands to wrap text that way, chiefly for quoting mail messages. This happens to fit in very nicely with the way Vim and Emacs wrap paragraphs, and I know there are people who've written novels in both. But I assure you that the vast majority of fiction writers are used to word processors, and for that matter, so are the vast majority of users typing things into text boxes. And if those users wrote a little poem
That had lines
Which looked like this
And failed to rhyme
Because they weren't really poets
...the chances are they would just hit return at the end of every line, because that is the way every program they have used in their entire lives works. This is why GitHub and StackOverflow made that change: because Markdown is not like HTML to most people. It's like plain text. In plain text, when you press return it means "end of paragraph." The way Markdown does it -- and the way Hacker News does it, I just discovered! -- violates the principle of least surprise. I am not writing HTML, I am writing text, and I expect it to act like text.
(For what it's worth, I've written a collection of short stories in Markdown and created the EPUB from that using my own Python scripts to do so. I am an edge case. Anyone who is writing fiction in a text editor instead of a word processor is also an edge case. Sorry, but it's the truth.)
Stackoverflow requires you to add two spaces to the end of every one of those sentences in your poem to work as you just said it did ... Stackoverflow DID NOT make that change you suggested it did.
If you are throwing away the ability to have visually formatted source text, all the teeth gnashing over the name of the new, properly standardized and beautifully implemented format becomes completely ridiculous. Nice looking source text is pretty much the core principle of markdown.
Which I suppose is the source of Gruber's apparent obstinance, if someone wants to make changes that exchange his design principles for other design principles (I don't think he cares much about naive users), why should he hand them the name of his project?
(to clarify, "apparent obstinance" is me doing a poor job of keeping sarcasm out of my post, I don't have a problem with Gruber insisting that the markdown name is his)
I agree -- but it doesn't seem to me that "treat return characters as hard line breaks" equates to "throwing away the ability to have visually formatted source text," unless one is using an editor that is unable to deal with soft-wrapped text gracefully.
Why do you feel like normal people, who have been trained for decades--not just on computers but on typewriters as well--that hitting enter means "go to the next line", would have an easier time if that assumption was violated? You even see the formatting in front of you: you are now on the next line, and yet when rendered this information is somehow ignored and the text is pasted together. E-mail clients, which have been doing crazy things to our text for years, don't even do this: the closest they come is format=flowed, and that's a special set of rules designed to be generated by clients, not typed by mere mortals.
I feel this way because of the reality that many people will centre text in a document by inserting spaces in front of the text they want centered, rather than using their word processor's centre command. It drives me absolutely bonkers to see that, but it's reality.
I feel this way because of the reality that many people will hit enter two dozen times to go to a new page, or to position a bit of text.
In the time that I've been working with computers, what I've come to realize is that most people simply don't have a grasp of the abstractions of the computer—they remember particular incantations that worked for them last time and keep doing them again and again.
My wife is an intelligent person; probably smarter than I am. She speaks three languages and has taught for the last twenty-two years. Watching her use the computer drives me absolutely bonkers because she doesn't use any of the things that I know make the computer easier to use. Neither does her sister. Why? Because neither of them have time to specialize in the use of the computer. They use it a lot, and I've been able to introduce a few things—but only for things that simplify their lives because they integrate into how they already work.
If two of the most intelligent people I know don't have a lot of these expectations…why do people think that most people would expect things to work the way that Jeff has proposed?
In a sibling comment (I only want to reply once), stickfigure says:
“Normal People have a consistent expectation regarding the behavior of line breaks.”
Actually, I don't think that Normal People have any understanding of line breaks at all. They understand letters, words, sentences, paragraphs, and to a degree pages. They know they want something to show up on the page, but they have no understanding of how the computer does its magic to make that happen.
stickfigure: “Normal People are comfortable with markdown in the first place. Neither you nor your wife are Normal People.”
For the second sentence, I agree and disagree. I'm certainly a geek with a more-than-passing interest in layout, formatting, fonts, etc.… This stuff interests me in a way that most people and most geeks certainly would never be interested in it. My wife is also not normal people on some level—she’s married to a geek who can take care of things like this for her. At the same time, she is 100% a computer user and has no interest in learning to program or learning to fight with programs that actively get in her way.
She also doesn't know Markdown as such. She knows a tiny subset that I have introduced to her that provides her with exactly enough to write her novel and for me to format it the way she wants it. (That's the paragraph rules, italics, and headings.) I've shown her a few other things for when she blogs—but even when she's using the Squarespace WYSIWYG editor, I often have to go in and edit the links to make them right.
There's a lot more that I could show her, but she neither has the time nor the interest to learn it.
Both of your examples--using spaces to center text and using a dozen newlines to position text--are based on the reasonable assumption of "what I see in my text is what I got when I formatted it": removing carriage returns entirely and pasting lines together to form larger lines violates that assumption. If the user expects that they can go to the second page by adding a dozen newlines, how could they possibly understand that newlines now don't mean anything at all? I will repeat: for decades, the enter key has meant a very specific behavior, and Markdown is the only setup I can come up with that either myself or my mother (or my grandmother) would have ever come across where the enter key doesn't cause at least a single line break.
Most people think that a block of text that is set together is a paragraph, especially as block paragraph format has become the norm for casual and business writing; indented paragraphs are the exception used when you have a layout process and not just depending on your word processor to get it right for you.
Email and HTML have not helped this; it is a common expectation that a blank line between two blocks of text represents the paragraph break—at least based on the emails that I've seen over the last two decades.
A fundamental philosophy of Markdown is that a Markdown document looks reasonable when sent via email as text or when sent as a formatted web page. That it's flexible enough to be usable for more than just email and HTML is a bonus.
It is also a common expectation that if you put a newline in an e-mail message, even without a blank line intervening, that the person who receives the message will not get the two lines pasted together to form a single line. The problem with the newline behavior of markdown--and to a very real extent this is the only such feature of markdown that has this bug--is that the text you are looking at looks nothing like the text that ends up being rendered.
No, I didn't, but thanks! That's very useful. Additionally, google + the help command led me to :help text-objects, which describes a lot more goodies similar to 'ip'.
I, too, would be strongly against "automatic return-based linebreaks." Given that markdown has constructions for lists and code blocks, one very rarely needs a hard line break anyway. Currently markdown works fine both for people who hard-wrap and people who soft-wrap. Let's keep it that way.
I feel your pain. Parens in links made me never forget %28 and %29. But I think your solution causes more problems than it solves. The biggest issue is that it's not backwards-compatible with current markdown. For example, in a citation following parentheses:
Blah blah blah (side note)[1](http://url1).
Your markdown generator could output
<a href="1">side note</a>(http://url1).
or
(side note)<a href="http://url1>1</a>.
The latter is current behavior, but your suggestion makes the grammar ambiguous. Most parsers are "greedy", so the former is more likely to be output. Unless you specified more complex behavior, people would have to go back and escape their parens near links.
I've just finished writing a hyperlink parser; getting it to handle your specific case would be totally do-able.
I think your overall point still stands -- there would be ambiguous edge cases -- but if Reddit comments are anything to go by, they really wouldn't be any worse than the current confusion, and making ()[] interchangeable would clear up a lot of the common problems that users have with making links.
To fix the ambiguous grammar, we need to add a url parser to markdown? This is a perfect example of how changes that seem simple to humans can have enormous impacts on software complexity. As you said, introducing that complexity wouldn't help in many cases:
I don't mean to be hostile, but just because something is "doable" doesn't mean it should go in the spec. Adding things to a standard imposes costs that feature-proposers rarely consider. It forces programmers to write more code to support that feature. More code means more bugs. These bugs annoy users and cost valuable programmer time. Multiply these costs by the number of times the standard is implemented and you can easily end up with millions in lost value.
Vanilla markdown doesn't require a url parser. It doesn't have ambiguous grammar. It's small. It's simple. And that's a good thing, because markdown parsers have enough bugs in them already.
1. URL parsing is a solved problem. Since I so frequently have my competence questioned on HN, I have to conclude that if I can do it, anyone can.
2. There are a number of people in this thread, and many many many more on Reddit and on other forums that use markdown, that have had a specific UX problem with markdown which we can solve. The solution will not solve all possible problems, but it will solve many of them.
3. I subscribe to the Linus Torvalds camp of software development, which is that software exists to solve user problems.
4. While the trade-off between additional code complexity (and better overall user experience) versus simpler code (and poorer overall user experience) isn't always justified, in this case I think it is. I mean, HN parses URLs for you and makes them clickable -- would you really support removing that as a feature, in favor of having simpler code, and having to copy & paste links into your browser?
5. This particular feature rather nicely lends itself to extensive testing so that you can make sure you've covered most of your edge cases. If we decide not to implement solved, testable features out of fear that some other programmer might not implement it correctly or test it thoroughly enough, then I don't know what to say about our industry other than that it's going to come to a standstill.
I'm afraid that's all the energy I have tonight for arguing about things I don't really have any influence over on HN.
I've been annoyed by that on reddit for...like 6 years. "You can just escape it" people say. As if normal reddit users are gonna escape strings themselves these days.
I once wrote a piece of software for my own use that used Markdown, and I wrote a thin preparsing layer that would allow it to do the right thing regardless of which of these I typed:
because [][] is used for [reference-style links][daringfireball.com], which allows you to write stuff like I did and still have []() handle both URIs, absolute paths or relative paths.
All of those debates about the link syntax is a complete and ridiculous bikeshed. Any solution I read around here above about making it "smarter", "better", or whatever just end up in making it awfully and needlessly more complex and ambiguous, and yet another bikeshedded standard. The way it is currently is totally KISS: [x](y) => link (i.e a href) and [x][k] + [k]: z => resolve k then link to z. Escaping ')' is trivially solved by the second case.
Why not _click here_ [http://whatever.com] as a more natural way to do it? The underscores imply underlined text, which has traditionally meant inline link, followed by a single, square-bracketed chunk that is obviously the URL?
(I'm not saying here that the resulting link anchor text has to be underlined, just that this pseudo-underlining serves as a mnemonic for writers and readers of the raw markup.)
Why get all angry at John Gruber? As many have already noted, he created Markdown for himself and released so that others could use it. AFAIK he didn't put any license/restrictions on it outside of calling himself BDFL. Whatever his skills as a programmer, writer, or his role as Mouthpiece of Apple, the vitriol is unnecessary (but absolutely fanscinating to watch). My panties bunch up naturally, no need to allow my feelings regarding Gruber to bunch them further.
Why get his approval? In the same spirit that Gruber created something for himself, you should just create something for yourself. I find it hard to believe that Gruber was the first person that conceived the idea of user-friendly text-markup. The new standard could just be inspired by Markdown and that would be a win-win: a respectful nod towards Gruber as well as the ability to move towards something 'better'.
It's consensus-building. If the creator of Markdown says the successor technology is Rockdown, everybody who deploys something on Markdown will get hate mail: "why aren't you using Rockdown? Gruber says it's the future." If that doesn't happen, Rockdown is just a peer to Markdown—an improved, specified peer but not anointed. It leaves the window open for people to say, "well, I like flavor-X Markdown better than Rockdown, so that's what I use."
If consensus-building is one of the goals, then I would agree with you that Gruber's blessing is important. But one of the goals of Markdown is to provided easy-to-use markup for text. Whatever the next iteration of this looks like, I think that people will get on board if it provides a clear advantage over Markdown as it exists as well as other markup formats. With or without Our Dear BDFL's blessing.
Only geeks will complain about whether the successor of Markdown is deployed. Others, the majority of whom user-friendly markup is aimed at, won't care.
If enough people get behind this, it won't matter that Rockdown is a peer to Markdown. With good tools and support, Rockdown has the potential to exceed Markdown, even if it's just providing a better canonical parser and documentation since it's pretty clear from most of these comments that this is where Markdown is lacking.
You're missing the point, and you're missing it hard. Look at CSV. Do you want a repeat of that fiasco? That's a format with literally one feature, and yet in the wild it comes in so many varieties you must guess and configure with every CSV parser. We're in a unique situation here in that the progenitor of the format is alive and can appoint a successor to avoid that whole problem.
"But one of the goals of Markdown is to provided easy-to-use markup for text." This is in no way contradictory to the aim. The idea here is to standardize Markdown, not to replace it with XML.
"I think that people will get on board if it provides a clear advantage over Markdown as it exists as well as other markup formats." The clear advantage is that the parser won't have to guess what you meant and thus get it wrong. The clear advantage is that when you enter copy text from Github and paste it in a Reddit comment box it will come out looking the same. The clear advantage is that in ten years there is a flag for "Accept Standard Markdown only/Accept my weird extensions" to establish a baseline. The clear advantage is that your files won't have an expiration date. The clear advantage is that you won't spend months closing tickets and replying to emails entitled "Why is my formatting all fucked up?"
"Only geeks will complain about whether the successor of Markdown is deployed." Yes, and only geeks care about standards, because only geeks understand the immense difficulty that is supporting a family of mutually incompatible formats and protocols and therefore only geeks understand what standards actually do for them. Users may not care, but when shit breaks they have this unpleasant habit of blaming us and our work, and I find it frankly insane that any reasonable programmer could resist an effort to make their life and the lives of their comrades easier, practically for free.
"If enough people get behind this, it won't matter that Rockdown is a peer to Markdown." Have you ever worked with scientists? There is code in my codebase written in Fortran 77—and that code was written two years ago. Not everybody is interested in upgrading on your schedule. In fact, in many places, obeying the standard is the standard practice, and there is absolutely no interest in performing time-consuming comparisons to figure out independently what is technically superior to what or even what the options are. Standards are intrinsically valuable to these organizations, and you will inevitably find yourself tasked with dealing with them. You're essentially saying "Why declare a standard when we can just rely on word of mouth and let people figure it out?"
I hate to impugn a fellow HNer, but I really can't abide this sloppy, half-assed, incomplete thought. This initiative is obviously the right thing to do, or at least try to do. If you disagree, I curse and damn you to ten years of supporting incompatible highly-similar formats, after which I am certain you will see the utter pointlessness of it and the ease with which it can be averted and agree with me.
I'm not sure what point you're referring to that I'm missing. Here's my point:
People don't need to wait for Gruber to make a standard; Gruber doesn't hold enough power to prevent the adoption of a Markdown-like standard. The adoption of the standard will correlate with the value that it brings.
I am not saying the rest of the stuff you think that I am saying; I was just responding to your argument.
This initiative is obviously the right thing to do, or at least try to do.
I completely agree with this statement.
Feel free to impugn me. It is your right to; actually, it is your obligation to if the situation calls for it.
I really hope that they borrow a lot if not everything from pandoc[1]. My only real complaint with pandoc is the table formatting, but I think fiddlosopher is adding org-mode like table support.
If you have not taken a pandoc for a spin I highly recommend you do so soon. In addition to being a great markdown dialect the pandoc tool set is the swiss army knife of text formatting. It is amazing how many formats pandoc can read and/or write.
EDIT: I spoke too soon, Fiddlosopher continues to impress. I just checked the open issues and a little less than a month ago he added "limited org-table support." Based off of the rest of pandoc "limited" probably means something like 85% to 95% :)
I cannot second this enough. Pandoc Markdown has some nice little tidbits, oddly contrasting to the above, the table syntaxes(yes there are more than one) are pretty darn useful.
I'm the author of a Markdown text (prose) editor[1], and can attest to Jeff's statement that all Markdown's parsers suck. The official perl regex-based implementation is a joke. Sundown is great, but only works for cross-compilation to other markup languages; it doesn't work for syntax highlighting, which is what I'm more interested in.
I ended up writing my own in Objective-C. It's not very pretty, and it doesn't use a formal grammar (just a lexer + custom grammar code), but it does the trick. I took a few liberties with the spec: throwing in GitHub-flavored code blocks.
Your editor looks pretty nice; super simple with a gentle element of WYSIWYG.
Can you not tile the background on the homepage, though? It looks horrendous at high resolutions and I suspect you didn't mean for it to be that way: http://cl.ly/image/341C0s1s0M03
(Safari 6.0, OS X 10.8.2)
Woah, how massive is your screen? You're totally right though, it looks awful tiled. I'll have to take care of that.
By the way everybody, I'm working on version 2.0 which is just about a million times better than the original. Hit me up if you'd like to get beta builds and a free copy.
I'm not that psyched about automatic return-based linebreaks. Everyone thinks they should use linebreaks to align their text, and the system should just ignore all single line breaks.
The current behavior of Markdown solves this problem very well. I don't want the newlines I enter for non-wrapping editors to remain in the generated HTML.
I agree, I am having trouble thinking of a situation where specific line break positions would be important to me in regular text that isn't covered by some other markdown structure such as code blocks or lists.
One word: poetry. Traditional break behaviour (new para) is great between stanzas/verses; not so much between lines. (It's also the primary reason why the <br> tag still exists in HTML.)
That hidden feature is so thoroughly buried that I didn't even know about it until I read your msg - and I've been writing markdown for years. For mainstream users, it might as well not exist.
It's not a matter of there being no work-around. MarkDown is meant to be as much for ease-of-use for the content creator/editor as it is to be a readable alternative text source. And HTML isn't always the desired output, so why should users have to know anything about HTML unless they're creating HTML?
I found that I've moved on to reStructuredText. It doesn't seem to be marketed as much as Markdown (the only reason I know about it is because of Sphinx) but I feel that it's a bit more capable. Simple tables are exceptionally easy and it handles URLs with parens in it just fine (a common pain when trying to link to Wikipedia articles with Markdown).
I use rst for everything due to using Sphinx heavily. Trivial tables are easy in any markup, but non-trivial ones are a pain. I use table mode in emacs, but we can't require everyone to use emacs.
I hate its URL handling.
And of course it needed Sphinx to make it work across more than one source file which means we now have two dialects.
I do wish everyone would just agree on one syntax and be done with it.
Regarding the URL handling, I also used to hate it, but wrote a tool to make it easier to deal with; details are here if you're interested (despite the title, the relevant tool is not Vim-only): <http://tadhg.com/wp/2012/10/07/tools-for-writing-restructure...;
The bit I hate is that I have no desire to have a global list of URLs and manage them. So instead I have to put a double underscore suffix after every url otherwise you get bizarre error messages. eg `foo <foo.com>`__
Have you tried using the list-table directive? I find it's a much easier way to create tables - it's based on writing indented lists which mirror the logical structure of the table (i.e., table / row / cell), rather than trying to produce ASCII art.
All my doc is in Sphinx so I play it safe, and all directives need to be supported in whatever version of docutils and rst2pdf are installed across the various developer machines. So for the moment I am stuck with ascii art.
rst is definitely better than markdown.
Honestly I also prefer textile to markdown.
And I sorta believe wikicreole is better than markdown.
I cannot understand for what reason MD has become popular, it has an annoying and confusing syntax for half of the things, supports many less things than others and is not stricly better in any way I can think of.
Supporting many less things is markdown's big advantage. It's a format that makes everything as simple as possible, but no simpler; it's the perfect format for "almost-plain" text like I often want in a readme - mostly plain text, but with headings, bulleted lists and the occasional hyperlink.
Compared to rst it's a lot easier to write links. I hadn't even heard of textile, but its link syntax also seems harder to write than markdown's. WikiCreole might be better, but right now figuring out what syntax a given wiki will support is far more of a crapshoot than using an arbitrary markdown implementation.
I'm using reST for everything: docs for people (converting them to html and doc before sending), doc-comments in every language I use, be python, T-SQL, java or F#
As a heavy LaTeX user (phd student; can't escape it), I'm convinced that there is a small enough subset of LaTeX that actually gets used day-to-day that someone could figure out a way to shim it into something like Markdown.
And then, for the LaTeX that you can't shim in, just have some escape hatch that sends fragments out to a renderer.
If I could only have:
* Math mode
* Citations and Bib files
* Labels and References
Then I'd be willing to go through a lot of extra pain to get all the weird tables and precise image placements that are inevitable in a 2-column ACM format.
EDIT: Having just investigated Pandoc, which many here are talking about, I realize this might be exactly what I've been looking for :)
rst2latex has worked very well for me. The current version has math mode. I've occasionally had to write some custom LaTeX to get things like natbib to work, but it's largely been problem-free.
(shameless plug) I wrapped Pandoc[1] in a web service and added on nice PDF exports and called it Docverter[2]. It will convert basically anything plain-text, including Markdown, into almost anything else plaintext, HTML, RTF or Docx. I also added rich PDF exports that go through a HTML intermediary.
If this gains some traction I'm sure I'll be adding support for it at some point.
"I'm reminded of the guy who decides that there should be
one standard because there are n divergent implementations.
So he goes and writes his own. Now there are n+1 divergent implementations."
That is probably the most likely outcome, but kudos to Jeff for trying.
The idea of Markdown is great, but I found the implementation of links is less than obvious. (haven't tried it in 4 years, so there was probably other issues that I had that I've forgotten)
The problem I inherently always end up having with "parses to HTML" syntax conventions is there are always warts where the syntax is harder to remember than the HTML it is supposed to parse to.
You can hardly blame links for that. There was no widespread hypertext format before HTML for conventional renderings to appear in. Most of the rest of Markdown has analogues in earlier plain text formats and is fairly visually suggestive.
Common Lisp managed to unite several divergent implementations of Lisp (MacLisp, InterLisp, Lisp Machine Lisp, etc.) under a single common specification. This was possible because the Common Lisp standard was not created by some third-party out of dissatisfaction with the other guy's stuff but by significant representatives from all the big camps. The desire was for better interoperability, not imposing ideals on the competition.
I think this effort, if Gruber supports it, is likely to succeed simply by incorporating most of the community. In fact, it could be even easier, because one of the principle motivators for the divergent implementations of Markdown is simply to create concrete specs around a concrete grammar. This doesn't mean there won't be divergences (Scheme, Clojure, OpenLisp, etc.) it just means that those divergences will be principled ("we reject the size", "we desire modern FP techniques") rather than accidental ("we used this regex instead of that to tokenize emphasized text").
I love it because the world needs an easy-for-humans way to format in pure ASCII without any tool. It is much simpler than using even the most well designed GUI. You can even write books with it, and you can focus on content.
But I hate Markdown. I hate it because it is superficially good: a lot of Markdown seems to make sense at a first glance, but if you look at it more closely you see that a lot is broken in its design (IMHO the fact that the reference implementation is broken is the minor of the issues).
It is surely possible to fix it. However it's better to have a broken Markdown now that no markdown at all. The fact that Github and Stack Overflow and Reddit are using it makes it absolutely obvious how useful and great the concept is. The actual design, implementation, and specifications can be fixed now. So kudos to the original inventor, but it needs a second pass from people that can give it a more coherent shape, with clear behavior, minor surprise, and parsing in mind.
I convinced my team to use pandoc instead of Word for documenting a new project, and now, because creating tables is so hard (they are not like Emacs users), I'm considering lobbying them back to Word, or writing a preprocessor to insert tables from CSV files... feels bad man.
How can this be harder than creating table with Word? Word always gets in the way. Word appears to be easier but down the road, it always end up as a painful process.
For me just the benefit of being mergable and delegating styling at the end of the tool chain is just plain great.
Well, add a last row with the first column larger than the previous rows, assume people don't know about column-mode editing, and you can imagine what they are doing to align...
I think I'll just "preprocess" the file, looking for something like !csvtable(filename.csv).
Wrote the script (it worked), but some specific complex features from Word still were missed ("how do I do a reference to a picture?") and couldn't be easily supported by pandoc or this script.
Though for a brief time of going full-mode procrastinator and writing another markup language...
Then I had to admit the whole thing wasn't really working and now recommend we move back to Microsoft Word because it's easier.
A day of Total fail, and procrastination, and making everyone install MikTex, pandoc and Python.
I hope I don't regret for suggesting we use Git...
It'd be nice if it Markdown was added to HN, at least for a consistent way of quoting that's better than using the code tag (which frequently cuts off text for some reason in mobile Safari).
> (which frequently cuts off text for some reason in mobile Safari).
Is this just because it doesn't wrap, and mobile safari doesn't display a scrollbar? (I've never used mobile safari, but I think that's true of the Android browser.)
Quoting with code blocks can be awful, but > is fine even if it's not explicitly formatted.
> Is this just because it doesn't wrap, and mobile safari doesn't display a scrollbar?
Pretty sure that's it. OS X (Safari and Chrome, at least) does the same thing unless you have a mouse plugged in. The formatting is such that it doesn't feel like it should scroll, even in the common case of characters being cut in half. Better styling on code blocks would do wonders for this.
Here's hoping they can finally work natural _underline_ support in...
Edit: I've wondered whether the original Markdown didn't have underline support because <u> was deprecated/removed from HTML. FWIW, <u> is now back in HTML5.
Underlines traditionally have semantically meant the same as italics. When an editor wanted the printer to make a certain word italic, he would underline it in the draft.
Really, underlines are a useless decoration. That's why HTML took them out. Not sure why they put them back in...
The primary reason is to provide for Chinese proper name marks (where underlining has a semantic meaning) and occasionally for misspellings (in English, we'd probably add the editorial text [sic]). As a decoration, it is useless, but there are circumstances where it has semantic meaning. (The <b> and <i> tags were promoted back to respectability for the same reasons, since using <em> for text that is not stressed or <strong> for text that would traditionally be bolded without implying extra importance is just as semantically incorrect as using <i> and <b> for stress and importance would be. Arbitrary spans don't imply any semantic meaning. Where I would have used <span class="foreign" lang="fr"> previously, I'd now use <i class="foreign" lang="fr">. The <i> tag marks the text as special rather than just arbitrarily styled.)
Like you said, they are a decoration. When handwriting something, some people use underlines for different kinds of emphasis. Those people want to make text look a certain way. It's good that HTML5 brought back underlines, just in case someone wants to use them, they at least have the option.
> The problem with writing my own Markdown parser in Clojure is that Markdown is not a well-specified language. There is no "official" grammar, just an informal "Here's how it works" description and a really ugly reference implementation in Perl. http://briancarper.net/blog/415/
As a non-web developer I cry every time I need to use HTML: It's really "ugly" in some way (And I'm used to ugly languages).
But I have learned to love Markdown too, I hope in the future, distant future: Someone will create a language that integrates HTML and CSS into a nice Markdown-like language.
<!doctype html>
<meta charset=utf-8>
<title>Hello, world</title>
<h1>Hello, world</h1>
<p>This is a paragraph about HTML.
<ul>
<li>Bullet point
<li>Bullet point
</ul>
I'm not a huge fan of the current Markdown mark. I'd encourage the creator (dcurtis) to push it, because currently it feels like a first-stage idea — or perhaps, an execution without an idea at all.
There are many questions — "What is Markdown?", for starters — that feel unaddressed by the mark. Instead, we get the brute force approach: splitting up the word into smaller word parts, which is what you do with a word if you don't know what it means, or you have to gesture it in Charades.
Rather uninspiring for an idea so beautiful that Jeff and others can get so excited just thinking about it, but what else can you expect from such a mark whose approach is so stubbornly literal? I take that back — only one word part actually gets to be represented literally... the other only managed to become a letter, in a moment I can only imagine involved the creator muttering "good enough". He must have found this mark uninspiring as well, given that he sought to put a box around it.
At least consider that the down arrow on its own is an overloaded concept, particularly on the web. Without context — and a mark should not need context — M↓ could read like a hotkey or command of some kind. This kind of ambiguity is utterly unnecessary — you're making a mark; it can be whatever you want it to be. Push!
There was some discussion about allowing even more metadata than just the syntax highlighting hint for fenced code blocks in the Literate CoffeeScript thread:
I can't speculate on antidaily's reasoning, but I can tell you why I don't like this way of doing markup. (I thought I was the last one.)
First is the lack of standardization. Asterisks traditionally meant boldface, I thought, but in some of these systems they mean italics. Some use underscores for italics, while others use slashes. And those are just the common conventions; the less frequently used ones tend to be even less standardized.
Second is the fact that the more conventions these languages implement, the more likely I am to emit one unintentionally, and then have to figure out how to escape the input so it's treated literally, if the language even supports that. (Note for instance the long-standing Lisp convention of putting asterisks around special variable names.)
Thirdly, the syntax rules of these languages are often ill-specified and incorrectly implemented, making it difficult to tell at times how to get the effect I want.
* Links are backwards (text,link instead of link,text like HTML anchors)
* Link syntax is pretty arbitrary (why braces and brackets?)
* Single line breaks are swallowed unless you append two spaces to the line. (How is this a "natural" formatting?)
* Footnotes with asterisks turn into bullet lists
Most or all of these are resolved by various implementations, but that's just another reason to hate Markdown: the inconsistencies between implementations.
I don't loathe it, but I don't like it, and I'm sad that WYSIWYG text-editing software is still so bad that a kludge like Markdown seems like a good idea to people. Markdown isn't optimized for people (it's harder to read than properly typeset text, and when writing it you pretty quickly have to remember syntax details, like what sort of brackets to use for links), and it's not optimized for computers, either (it's harder to parse than, say, XML).
If you've ever been involved in producing content management systems for non-technical users (typically involving TinyMCE/CKEditor etc etc) then you'll probably welcome this as much as I do.
Dodgy HTML, content pasted in from Word (with crazy styling intact), and a general encouragement for users to see text content in terms of styling rather than structure are all things that it will be delightful to see the end of.
How would one go about taking a project with a large corpus of non-standard markdown (e.g. Github, Reddit) and converting it to any standardized form, assuming that a standard is chosen that is not 100% backwards-compatible with all existing markdown flavors?
I don't think such a thing is feasible. I also don't think it's feasible for any proposed standard to simply look at the largest users and say "okay, we'll accept the idiosyncratic extensions of all of these differing flavors in an unambiguous way."
So assuming this pushes forward, there are (to my mind) two possible outcomes:
1) A backwards-incompatible standard emerges. No existing project adopts it, but new projects do. It gains legitimacy only once Github, Reddit, et al fade into obscurity.
2) A backwards-compatible standard emerges. Every large existing project adopts it, but the standard is so full of cruft and TIMTOWTDI that in ten years it gets usurped entirely by a challenger that emphasizes simplicity.
For Reddit, I would use the new parser for comments written after the upgrade and the old parser for comments written before the upgrade. Note that Reddit already puts post that are older then a month or so into a "frozen" archive mode where they can not be further modified, so after a month the old parser could be thrown away completely.
It has always bothered me that _text_ is not underlined text, but italicized text. Why not /text/ for italicized text. It shows exactly what it is doing. And text for bold text.
I also see no reason for text and _text_ to produce the same output. It just seems like a fault in the original spec to me.
* It's very uncommon to want your output text actually underlined.
* If you really do want underlining, just use <u>this</u>, since it's fine to put raw html in Markdown source.
* The most common way folks express emphasis is probably with ✱asterisks✱ (HN won't let me backslash-escape the *). A less-common alternative is to use _underscores_ (though I rarely see that anymore these days). Maybe the distant third most-common way was with /slashes/. I guess Gruber had to draw the line somewhere and just support the first two most common ways to write it. That seems reasonable.
Another reason to not use slashes for emphasis: using them might interfere (or at least cause headaches) with writing directory names, fractions 1/2, and "and/or" wordings.
It's been part of email and newsgroup etiquette for ages now. Same goes for the quote blocks. So, why change something that is working for a lot of people in different domains?
In a comment area (like on HN) it rarely makes sense to be able to add headings. Could some features of the specification be optional, so that a parser can be conforming even if it disabled those features?
Are there any parsers (preferably in JavaScript) which currently let you toggle features like that?
So, pulling an old man card: creating a formal spec for Markdown paves the way for adding more syntax which negates the main benefit of it: a lay person can interpret Markdown as a text file. If you want to add more syntax, we are better off using/extending LaTeX or troff.
Is there a reason why i should prefer Markdown over restructuredText? rst sems to me has all i need, it has specs, it has decent documentation, it has tools, it's not only used to output HTML but all kinds of stuff.
rst just looks more powerful and yet still as readable as markdown.
Having used them both a fair bit (though not to write novels, like some of the people on here): Markdown source is prettier to look at. This might seem minor, but it's the primary goal of Markdown. If I'm writing something highly technical, I prefer RST; if I'm writing something closer to plain English, I prefer Markdown.
I absolutely love the simplicity of Markdown, especially with github's addition of code fences/blocks. It's so trival now to add code and have it automatically highlighted. It's not nearly that simple in other formats (to get autohighlighting I guess).
Somewhat related: Pandoc supports delimited ("fenced") blocks as well, but as an alternative allows you to use tildes
~~~python
print "hi"
~~~
rather than backticks
```python
print "hi"
```
My own 2 cents: I like the more symmetrical tildes.
Anyhow though, yes, I agree; it's great that github supports delimited/fenced syntax-highlighted code blocks and renders .md files there automatically.
If it were up to me, I'd simply ask that markdown add support for h3 (other than hashes, e.g. Underline with hyphen and spaces) -- two levels of headings is all too frequently insufficient, inline links to images be rendered as image tags, inline links to videos etc. likewise become video tags, etc., the way other inline links become anchor links, and some form of table support be standardized.
Aside from that (and implementation bugs) I've been very happy with markdown.
Using Pandoc, what my habit has become is have the first line at the top of the file be title metadata:
% Title Goes Here
then make subsequent headings go ahead and start at h1 (rather than h2):
Some h1
=======
This puts an `<h1 class="title">Title</h1>` at the top, with regular unadorned h1's further down the page. So, if you like, you can style the title h1 differently from the other h1's.
It breaks the soft rule of having only one h1 on a page, but otoh looks good, and doesn't require me to go to h4 or h5 very often, so I can live with it. :)
I love markdown. I even created my own version which I have become addicted to -> http://blackstag.com/markdown. I'm fairly confident I will be the only one to appreciate my personal version, but hey - It's the ugly child I have come to love.
I'd certainly be interested in switching over to their version, provided some of the noted kinks get worked out.
Didn't Gruber co-design Markdown with Aaron Swartz[1][2]? Is there any reason why everyone refers to Gruber as Markdown's sole inventor/BDFL? What's Swartz opinion on all this?
Somebody please make a web-usable of Org Mode the language; it's like Markdown, but older, richer in features (while being as simple as Markdown) and is in daily use by many hackers for note taking, outlining, TODOs, organizing your life, etc.
I'm very happy that GitHub has an Org Mode renderer, even if rudimentary - I don't have to rewrite my notes and READMEs to Markdown.
We recently added Markdown as an option in our hosted reseller CMS (YikeSite) in hopes that some of our customers would choose it over the WYSIWYG editor.
I love Markdown, and, this is an awesome effort! I'm working on a Markdown editor/platform that could really benefit if this sort of stuff wasn't so fragmented: http://www.nimblenot.es/ (yes, that was a shameless plug)
And if you like Markdown... I wrote a Chrome/Firefox/Thunderbird extension that lets you write email in MD and then render it before sending: https://github.com/adam-p/markdown-here
This is one of the reasons I've never bought into the Markdown hype and generally avoid using it. Semantic HTML5 tags makes to-HTML compiled languages mostly unnecessary.
Most people don't need to or want to think about it.
Markdown is easily understandable by my wife (and we're using it to format her novels), and she doesn't have time to learn something ultimately as irrelevant to her is a format that makes a computer program happy.
What is Markdown, though, if not "a format which makes a computer program happy"? Presumably, your wife was already familiar with standard typographical conventions like italics for emphasis and indents to start paragraphs. A good text processing system for a computer should let the user deal with these conventions, rather than having to learn a markup system. I'd be interested to hear why you and your wife decided to use Markdown, and what alternatives you considered and rejected.
The other alternatives were essentially opaque formats (e.g., Word or Pages) that when she & I talked about them and the amount of work that I needed to do, she agreed.
She also writes long hand, so this is a minor adaptation for her to write like she does with emails.
The changes suggested are less natural for most people, and HTML is line noise to most people. If she had to learn HTML, my wife could do so—but it isn't necessary for her to learn HTML. It's also easier for me to have to worry about clean-up than her to do so.
We do have points where we have to figure out how to make certain things work (when she has lyrics, that requires a little more massaging on my part—but I insert the bafflegab bit and she just knows to edit around it or inside it).
It isn't perfect, but the results look very good. (In fact, the second novel looks better than the first, which was laid out in Pages and took me three times as long as learning LaTeX to format the second novel. The only problem with the second novel was finding a good font for the PDF version we use as a print-ready copy.)
This would completely defeat one of the best parts of markdown, which is the ability to mix in HTML tags whenever you want, when you need to represent something more complex.
I manage a large forum and we use BBCode. I recently "open sourced" our rules (https://github.com/minecraftforum/rules) and during building the system you see there I made the decision to opt to use Markdown over BBCode -- what everyone that uses the forum is used to.
BBCode isn't inherently "bad" if you're just writing something and won't ever edit it again but for anything that you will need to edit / review in the future it can be a serious pain in the ass to look through.
These are the two examples I used:
### Title here
This is some text [with a url](http://google.com)
vs.
[size=6][font=arial, helvetica, sans-serif]Title here[/font][/size]
This is some text [url="http://google.com"]with a url[/url]
BBCode was written to be written, it's no more difficult to write
[url=http://google.com]google[/url]
than it is to write:
[google](http://google.com)
but when reading the source (for maintaining) it... sucks, because it feels un-natural. With the Markdown version of linking (to pick a basic example) you can read a sentence how the person reading the processed version would read it:
A search engine called [google](http://google.com)
That reads as "A search engine called google" and then you see that google is a hyperlink. With BBCode it would read:
A search engine called [url=http://google.com]google[/url]
So first you read "A search engine called" then you see it's a URL and then you see "google". It can get very frustrating when you're looking at huge swathes of text written in a similar style.
> The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions
Which is appealing to me, and many others I suspect.
Nobody should be using the original script, and unfortunately many of the other implementations out there are direct transliterations that replicate all of its absurd errors, like where if you mention the MD5 hash of another token in the document, the hash will be replaced with the token, because it uses that as an inline escaping mechanism! Reddit got hit with a XSS virus that got through their filters because of it: http://blog.reddit.com/2009/09/we-had-some-bugs-and-it-hurt-...
See the changelog for what started as a PHP transliteration and turned into a rewrite that squashed 125 (!) unacknowledged bugs: http://michelf.com/projects/php-markdown/
The worst part is that he outright refuses to either disclaim or fix his implementation, and so far he's repudiated everyone else's attempts to do so. He's a terrible programmer and a worse maintainer, he really still thinks the documentation on his site is comprehensive and canonical. As much as Jeff Atwood leaps at every chance to play the fool, there's no way his directorship can be anything but an improvement.