9 ms·
Why Markdown Is Not My Favourite Language (2012)
- tonetheman 12y agoNewer markdown stuff here: http://commonmark.org/ http://commonmark.org/ Gruber did not want them to use the word markdown so they changed to commonmark. And they are trying to standardize with a spec. I would also consider it along with your other alternatives.
- TazeTSchnitzel 12y agoCommonMark doesn't really fix much given it's not so much a proper spec as a set of tests, and most big users (who wrote the spec!) aren't actually using CommonMark anyway.
- pyre 12y ago> most big users (who wrote the spec!) aren't actually using CommonMark anyway. I'd say this is partially due to inertial. Reddit and StackExchange for example, have communities that have been writing in their variants of Markdown for years at this point.
- tptacek 12y agoPart of the problem is that people don't really grok the point of Markdown. There's a reason it doesn't support tables, or a syntax for making the kind of language used in a code snippet. The point of Markdown is to mimic the conventions of ASCII-text email, both to make writing it as natural as possible, and to make Markdown pleasant to read in both ASCII and HTML. If you want something more featureful than Markdown, the problem isn't Markdown; it's that you're using the wrong tool for the job.
- pmoriarty 12y agoorg-mode in emacs supports tables, and it's ASCII-based. Here's an example, displayed exactly how you would see it marked up in org-mode syntax in emacs: |-----+-------| | Key | Value | |-----+-------| | 00 | foo | | 01 | bar | |-----+-------| org-mode can export to HTML, and many other formats.
- josteink 12y agoOrg-mode is a beast. A fantastic beast, much like Emacs itself. You dive in, but there's always more to learn. Some things may be for you and some things don't. Everyone should give it a try. A little known fact, even among most org-users: Github can render org-mode files to HTML directly if checked into a repo, thus you can write your README files as org-files. Shameless example: https://github.com/josteink/csharp-mode/blob/master/README.org https://github.com/josteink/csharp-mode/blob/master/README.o... This alone was enough to make me drop Markdown as my go-to format for semi-formatted text-files. A subtle killer feature here is org-babel. You can embed proper code in your text-files and have your editor (at least Emacs) understand them as such. Which makes it excellent for writing technical documentation for projects where code is involved.
- pyre 12y ago> A little known fact, even among most org-users: Github can render > org-mode files to HTML directly if checked into a repo, thus you can > write your README files as org-files. I recently stumbled across the tidbit. The Ruby library Github uses to generate it though isn't 100% though. If you want to use org-mode properties for style customization of html output your SOL. Original project: https://github.com/bdewey/org-ruby https://github.com/bdewey/org-ruby Currently, you cannot do much to customize the conversion. The supplied textile conversion is optimized for extracting “content” from the orgfile as opposed to “metadata.” It does say that developement has moved to: https://github.com/wallyqs/org-ruby https://github.com/wallyqs/org-ruby Which has no such note, but doesn't say anything about supporting it.
- TazeTSchnitzel 12y ago>Github can render org-mode files to HTML directly if checked into a repo They also support ASCIIDoc, ReST, MediaWiki markup, Creole, etc. See: https://github.com/github/markup https://github.com/github/markup
- donniezazen 12y agoI really wish that other services would be like this. You enter text in a few popular markup languages and not one specific language.
- jotux 12y ago>There's a reason it doesn't support tables I don't see how the inclusion of tables violates the ascii-like readability of markdown. Github has implemented a table syntax that is natural to read/write and makes it easy to include tables in your document. Example: https://github.com/Defconbots/2015_target/blob/master/hw/boards/bom.md https://github.com/Defconbots/2015_target/blob/master/hw/boa...
- mplewis 12y agoI built a tool to convert your CSV tables to Markdown table format: https://github.com/mplewis/csvtomd https://github.com/mplewis/csvtomd
- JetSpiegel 12y agoNatural to write? This: |Name |Quantity|Part Number |Distributor| |:--------------:|:------:|:------------------:|:---------:| |BAT1, BAT2, BAT3|3 |534-082 |Mouser | is not "natural to write"
- sebastianavina 12y agoof course is natural to write, given the proper emacs plugin.
- krick 12y agoYep, and there's also exists plugin like that for vim. Although it doesn't exactly comply to github's column alignment markup. https://github.com/dhruvasagar/vim-table-mode https://github.com/dhruvasagar/vim-table-mode
- sitharus 12y agoTo add to that, Markdown was created to scratch one person's itch with no real desire to support a wider community. It was put online and other people liked it and modified it, but the original site doesn't have any of this.
- baddox 12y agoIs that a correct history of Markdown? It certainly seems to have been designed to be easily readable and writable for laypeople.
- nine_k 12y agoAFAICT Markdown codified a lot of best practices from ASCII emails and forums of years past (e.g. 20th century's). What looks like careful design may be as well a result of a long evolution.
- rtpg 12y agoThis feels like a post-facto explanation that gives way too much credit to Gruber as a language designer. I find it hard to assume that Markdown is extremely well thought-through considering the fact that we didn't even get a grammar for the language, just an implementation that would be considered super broken in any other language.
- kasey_junk 12y agoThis implies that Markdown is designed as a language, which would have things like grammars and can be reasoned about with proofs and the lambda calculas etc. Instead, Markdown should be thought of as a convention. A convention that allows for automated translation of ascii text into html. Further, instead of thinking of Markdown as designed think of it as evolved. In the case of an evolved convention, we wouldn't expect formalism or even long term design. What we would expect and what Markdown is extremely good at is usefulness, high levels of adoption and ease of change. Which we do see. If your needs require formalism, or complex html features then Markdown is not the right tool for you.
- leoc 12y agoIf it's intended to be interpreted by computers, what's the point in avoiding precision? All a fuzzy specification does is make it probable that those interpretations will be mutually inconsistent and/or unintuitive and problematic and/or prone to crashes and security failures.
- johnchristopher 12y ago> If it's intended to be interpreted by computers, what's the point in avoiding precision? Because markdown is for humans first and foremost, not computers. It can't be clearer than that.
- rtpg 12y agothat is disingenuous considering that Markdown the spec is offered alongside markdown.pl. If it's intended for humans first and foremost, then why offer the transpiler? After all, it already looks like ASCII e-mail. The overriding directive is human-readability, not unparsability (which do not go hand in hand).
- 1wd 12y agoWhat parts of Markdown are closer to conventions of ASCII-text email than the equivalent Creole? Two spaces at the end of a line? List renumbering?
- donniezazen 12y agoI am in a position where I know a little of Markdown and a little of reStructuredText. Considering the little time I have and I have to learn a language I would want to learn something that is extensible. Isn't that a valid reasoning?
- BerislavLopac 12y agoMarkdown. Is. Not. A. Language. Markdown was never intended to have any particular standardized syntax -- it was simply a script that took a common syntax used for a long time when formatting plain text and convert it to formatted HTML. The attempts to standardize it are misguided, as there is absolutely no need for that -- there are numerous existing standards for precisely that, starting with ReST which follows a pretty similar syntax (in fact, any attempt to standardize Markdown will end up with something very similar, as it has to solve all the same issues).
- toolz 12y ago>Markdown was never intended to have any particular standardized syntax At some point it was intended to be standardized or else we wouldn't have a standardized version of markdown syntax.
- sitharus 12y agoBut there isn't a standardised version of Markdown. There's John Gruber's original syntax, and there are dozens if not hundreds of variants. When some enterprising people declared they had created "Standard Markdown" the original author got very upset: http://blog.codinghorror.com/standard-markdown-is-now-common-markdown/ http://blog.codinghorror.com/standard-markdown-is-now-common... Markdown does not have standards, it's just a collection of base formatting conventions a lot of people like.
- pyre 12y ago> There's John Gruber's original syntax, and there are dozens if not hundreds of variants. All of the variants exist due to the many undefined edge cases in the original syntax, and not further development by Gruber to 'officially' resolve ambiguities. Some of them became their own standards (e.g. MultiMarkdown) others just became undocumented behaviours of certain Markdown parsers and/or generators when handling edge-cases with no defined 'official' way to handle them. > When some enterprising people declared they had created "Standard Markdown" the original author got very upset: This seems to have more to do with the name being 'Standard Markdown' and seeing it as an attempt to usurp 'ownership' of the 'Markdown' name. Said author didn't flip out over variants like MultiMarkdown. > Markdown does not have standards, it's just a collection of base formatting conventions a lot of people like. The efforts of people to standardize it are efforts to resolve this idea, and make Markdown more formal.
- rcarmo 12y agoI've been using Textile for ages, and it's much better than Markdown for just about anything _except_ footnotes (in MultiMarkdown) and pieces with multiple references to the same URL. In particular, Textile has great table syntax, which I use extensively in pages like http://the.taoofmac.com/space/infoviz http://the.taoofmac.com/space/infoviz (markup at http://the.taoofmac.com/media/infoviz/index.txt http://the.taoofmac.com/media/infoviz/index.txt). But over the years I became so used to Markdown (largely thanks to the profusion of editor support it spawned) that I mostly gave in. Still, Creole might be a good addition to my next CMS/Wiki: http://github.com/rcarmo/sushy http://github.com/rcarmo/sushy (already supports Textile, Markdown and ReST).
- riffraff 12y agothe first wiki I wrote used textile, I added wikipedia-style links and it was about perfect. I still can't understand why markdown overtook it in popularity.
- ams6110 12y agoI don't like any of them. Markdown, ReST, various wiki/forum dialects of "simplified" text formatting. They are all as complicated if not more complicated than just writing HTML. They all have a bunch of rules and special cases. I'd rather just write in HTML which I already know. I don't understand the motivation for any of these "alternative" markup formats. Normal non-technical people want Word (or at least, some kind of WYSIWYG text entry). I've been on projects where they tried to get non-developers to use ReST and it was an abject disaster. The tech writers revolted and refused to use it. So then a developer had to be sidelined to convert their Word documents to ReST so that we could produce HTML. Yeah HTML is not perfect, but neither is any of these other markup languages. If you like one, fine, but don't wonder why none of them has really caught on outside of small niches of highly technical people.
- cespare 12y ago> They are all as complicated if not more complicated than just writing HTML. They all have a bunch of rules and special cases. I'd rather just write in HTML which I already know. I find that Markdown is significantly easier/faster to write than HTML and, more importantly, easier to read in its un-rendered form. To me (and presumably lots of other people, given Markdown's ubiquity) it's well worth learning the relatively small syntax. Edit: Here's a quick comparison with a README.md from one of my projects: Rendered: https://github.com/cespare/reflex/blob/master/README.md https://github.com/cespare/reflex/blob/master/README.md Markdown: https://raw.githubusercontent.com/cespare/reflex/master/README.md https://raw.githubusercontent.com/cespare/reflex/master/READ... HTML: https://gist.githubusercontent.com/cespare/ad6c41aa28583cac8b2c/raw/98f0da452068a0db2719002d0b0fd0654dd5faf4/md.html https://gist.githubusercontent.com/cespare/ad6c41aa28583cac8... Three things I notice from this example: - The verbosity of an XML syntax with HTML is annoying, particularly the need for closing tags. <code>xyz</code stands out as particularly verbose (compared with `xyz`). - Having to escape certain characters like & makes this HTML sample harder to read (this is more of a problem with technical/code documents). - Automatic linkification prevents stuttering: <a href="http://example.com">http://example.com</a> http://example.com">http://example.com</a>
- deleted 12y ago
- cespare 12y agoCan we get a (2012)?
- cies 12y agoAlternatives: asciidoc. Maps easily to docbook, and has a heap of extra features.
- syntern 12y agoThis. All the benefits of markdown (and similar), with a decent toolchain, version control capabilities and exporting to various formats.
- zimbatm 12y agoAnd it's also relatively close to markdown (biggest change is links). The asciidoctor project also has browser extensions for rendering which are really nice. For the lazy: http://asciidoctor.org/ http://asciidoctor.org/
- k__ 12y agoGithub can render asciidoc. Do they use asciidoctor.JS? I found the lib was rather big :/
- lucb1e 12y agoSince getting ReText, a simple Markdown editor which can export to PDF, ODT and HTML, I notice I want to make many documents in it instead of using LibreOffice. As long as it doesn't need imagery but just normal text with formatting (chapters, bullet points, perhaps code examples, etc.), it's much easier to create and keep in version control. It's super light, in a text-based format no program will ever have issues with (try the "open" docx format in LibreOffice) and when sending it to others I just attach a pdf export. Markdown as a spec may not be nailed down 100%, but as a practical thing to use it's very handy. There are implementation differences between StackOverflow and ReText, but those are details.
- anonymfus 12y agowikicreole.org don't work without www. Right link is http://www.wikicreole.org/ http://www.wikicreole.org/
- bigbugbag 12y agoThat's what I came to the comments for. wikicreole webmaster, please do configure your DNS thoughtfully, and OP please check your links before posting.
- buster 12y agoThis article is great. I really never understood the preference of Markdown over rST. Also, little do people know that github supports rst https://github.com/github/markup https://github.com/github/markup But looks like Creole as well, which i didn't know :)
- aidenn0 12y agoAs far as I can tell the only advantage rST has over markdown is that it's better defined. I rarely find that I prefer the rST syntax to markdown.
- buster 12y agoI frequently write documentation with sphinx, over 30 pages long. rST is a blessing for me. Markdown doesn't even get near. It's fine for some 20 line README on github but that's about it.
- aidenn0 12y agoI'm with you there in that I couldn't imagine writing 30 pages of markdown. For something like extensive documentation, I could imagine rST winning, particularly since there is a standard syntax for extending it. I still mostly use LaTeX for documentation though.
- buster 12y agoYou should give sphinx + latex a try. I have my own cookiecutter template for docs and it's never been easier and fast to write some good looking documents.
- 1wd 12y agoYes, Markdown is really bad. I really wonder why it's so much more popular than Creole, Textile etc.
- archagon 12y agoRevisit your starting assumption?
- Turing_Machine 12y agoIt looks like the famous Bjarne Stroustroup quote holds true for markup languages as well as programming languages. "There are only two kinds of languages: the ones people complain about and the ones nobody uses."
- arh68 12y agoDoes anyone else prefer txt2tags [1]? It also works. [1] http://txt2tags.org/features.html http://txt2tags.org/features.html
- cogburnd02 12y agoI do; of all the lightweight markup languages, it seems like only txt2tags has a sane representation of HTML links. [1] http://en.wikipedia.org/wiki/Lightweight_markup_language#Link_syntax http://en.wikipedia.org/wiki/Lightweight_markup_language#Lin...
- JetSpiegel 12y agoUgh, that's the syntax of TVTropes. What a mess, I never know if the title comes before or after the link, and whether to wrap with 1 or 2 square braces.
- cogburnd02 12y ago[ @JetSpiegel ] Challenge: (1) write an 8-page (or more) document with 32 (or more) hyperlinks in it in both txt2tags and any other format. (2) Print out the plain-ASCII source files. (3) Wait until you forget the whole text of what you've written. (4) Re-read it (both versions) somewhere without access to a computer/phone/tablet. (e.g. the bathroom) You will understand why txt2tags makes more sense: (1) Less markup [i.e. fewer characters] than Markdown, Textile/Texy, AFT, reST (2) Text-first, unlike AsciiDoc, MediaWiki, PmWiki, Org-Mode, BBCode. Text-first leads to better/easier readability of source ASCII IM(NSH)O. (3) Unlike POD, has a syntax for named links.
- billpg 12y agoMarkdown and all the other Markdown-esque formats need to be consigned to the history books. No really. It is almost 2015 and we are still typing symbols on each side of words in text boxes when we want to emphasize something. Are we cavemen? (Following was added after initial posting) Technology has moved on. We should no longer need to remember which combination of magic symbols we need to make a bulleted list or whatever. There are often helpers to insert those magic symbols. That's great, but then why keep showing us the magic symbols? Do you want me to care that s represent italics? Will including this second cause this fragment to be italicized? How do you show an asterisk without it meaning intalics? Grrr...
- krapp 12y ago>Are we cavemen? Well, essentially, yes. What do you suggest we use, then?
- billpg 12y agoOne of those text-entry boxes with buttons for emphasis, list items, etc.
- krapp 12y agoHacker News seems to have a weird fetish for its 'minimalist' UI ... probably because it has a higher than typical ratio of users who spend time behind a terminal, and due to some underlying belief that the lack of bells and whistles keeps the normies away. If they added a rich text editor there would probably be a riot. But to be fair, at least markdown is a lot cleaner than bbcode.
- billpg 12y agoI should probably point out before someone else does, that my own blog, hackensplat.com, is one of those very websites I'm complaining about. In my defence, its just a blogger.com hosted site and I'm using their comment system. I want forms to either accept plain text and allow angle brackets and stars, or accept HTML and provide an interface that hides the HTML tags. We only need Markdown and their ilk for the last generation of websites (including mine) that are behind the times.
- ilchenearly 12y agoTo me, one big issue is that you cannot use markdown to present everything, for example, one cannot use it to produce something like <pre>`d`<pre>, I mean he cannot use ``d`` to do that, right? Also you cannot write ``` ```markdown ## HEADER ``` ``` to produce a fenced code block which contains a markdown source code for code block. Also, different markdown editor use different markdown parser. So, same source code will be rendered differently in different editor.
- shurcooL 12y agoMarkdown is many different things to many people. I love Markdown, but I mean the GitHub Flavored Markdown. Using plain Markdown would be very weird for me. So discussing flaws of plain Markdown seems pointless to me since I don't use it due to a much better variant being available.
- jrochkind1 12y ago2 years later, how's creole doing, anyone know? Has it developed (in any sense of the word) much in two years?