13 ms·
Things Markdown got wrong
- mnarayan01 7y ago> Code Blocks probably aren't necessary When you're reading raw markdown they're extremely useful for short snippets since they save you two wasted lines per block.
- Grue3 7y agoBut these short snippets are useless because you can't easily copy paste them, especially with some programming languages that are whitespace-significant (looking at you, Python). And I don't understand how triple ticks are wasted lines, because you need to surround a code block with empty lines anyway while triple ticks work straight after line break.
- recursive 7y agoIf you're using your clipboard, it's invariably going to be at the wrong level of indentation regardless. What's the correct level of indentation? 0? 1? more? There's no generally correct answer, so you're going to have to use the block indent feature on your editor anyway.
- jakear 7y agoHot take (maybe): GitHub flavored markdown is the ideal markup language. If the author’s ideas were actually better, we’d use them instead. It supports code well, it supports non-enumerated lists well, it supports enumerated lists well (if you don’t want view it in rendered markdown, you can view the raw and just disregard the numbers, understanding that the items are supposed to be sequential). It supports links well. It supports images well. It’s easily readable, even with no prior context (@toml, yaml, etc.). It does whatever a static website could want, and it does it all decently well.
- judge2020 7y agoPeople tend to use whatever they have to use to be on a platform since these different parsers aren't portable. Everyone is on GH for the code hosting, getting a markdown editor that works is a bonus. If you go to any other community that uses a different markdown standard or even something that's not markdown, people will be using that - not because it's better than GH flavored markdown, but because that's what's available.
- ComputerGuru 7y agoNot true in the slightest. I used for periods of my life StackOverflow, Jira/Confluence, and bbcode exclusively and hated interacting with each of their markup languages.
- b0rsuk 7y agoGithub supports reStructuredText just fine. You can even display images in Readme without any extension, just a plain image directive.
- beart 7y agoYes the author praises GitHub flavored markdown. The criticisms presented are on gaps in the original markdown design, not implementations.
- swyx 7y agoauthor here. yup. tried to make that clear by constantly referring to Gruber's spec. A few years ago I didn't even know there were different flavors of markdown. Fortunately/Unfortunately Gruber's is the one that stuck and is universally accepted by all markdown tooling, hence it is now the lowest common denominator we must work with.
- arve0 7y agoHave you seen the commonmark standard? Did not see that mentioned. https://commonmark.org/ https://commonmark.org/
- holman 7y ago> I'm not sure who invented [fenced code blocks], but I definitely know that it is widely used because GitHub Flavored Markdown made it so and I am grateful for that. I’m pretty sure Vicent Martí (@vmg) was the originator of them. I remember we spent a number of weeks internally at GitHub debating the syntax, since no one really fell in love with any of the proposals for various reasons. Eventually the triple tick won out and that’s worked out fairly well, I think.
- rapsey 7y agoMan I hate those ticks. I have no idea what arcane key combination on my keyboard I need to do to get them. Maybe it's easier on a US keyboard.
- adrianN 7y agoMy biggest problem with the ticks is that they're dead keys if you want to be able to write accented characters easily. I write à code sample` way too often.
- Freak_NL 7y agoYou could consider using the compose key instead of dead keys. Diacritic characters take a three-key chord instead of two ([compose ` a] instead of [` a]), but all programming characters type as-is. The right alt is usually chosen as compose key.
- AlchemistCamp 7y agoI'm not in the US and there's a single key that corresponds to a back-tick. In fact, it hasn't yet been an issue for me on keyboard layouts for four different languages (from three separate language families, no less)! Where is your keyboard from?
- CodesInChaos 7y agoGerman keyboards have both accent directions as a dead-key. So you have to press press shift+´ then space to get `. And that assumes you can remember which direction markdown wants.
- godelski 7y agoThere's always these "Markdown got X wrong posts" and they seem to be very browser centric. You know how I use Markdown 99% of the time? Vim. I LOVE that it is simple and easy to read in a text editor. I spend a lot of my time in the terminal and that's WHY I use Markdown. If I wanted fancy things that display better in a browser, I'll use something else. I look at Markdown as great because they kept it simple. I can read it easily in vim and I can have some nice features in a browser (i.e. my GitHub repos don't look like they're from 1995. But they also don't look like a Geocities nightmare). I use Markdown to document code. I use it to keep notes. I use it to track tasks. Etc. It is my digital pen and paper BECAUSE it is simple, because I can read it in the terminal just as easily as I can read it on the web. Keep Markdown simple.
- thayne 7y agoI also use markdown in vim a lot, and some of these "things it got wrong" make it worse, because you end up having to use html to do things like tables. or numbered lists aren't actually numbered in order, etc. I'm actually surprised the absence of tables didn't make this list.
- godelski 7y agoThis is how I make tables |column 1| column 2| |:----:|:---:| | 1 | 2 |
- swyx 7y agoI think your mental accounting of saying you use Markdown 99% of the time in Vim is primarily when you alone are concerned. But consider also that you are "using" Markdown when you read Markdown written by others, on documentation, in a browser. A wholistic accounting would probably move Markdown higher than 1% of your time!
- godelski 7y agoIf it wasn't clear, let me be. Absurdly high numbers typically indicate exaggerations.
- 7y ago
- juped 7y agoOrg is a way better naturalistic markup format, with way better tooling, but it's hampered by being emacs-only and having weird devotees who like to sell it as some kind of task planning tool when really it's a naturalistic markup format. I've never liked emacs, but I keep it around for Org, which I use most often as a LaTeX generator without all the ceremony of actual LaTeX.
- lmilcin 7y agoI also love org but it is no replacement for Markdown exactly for the reason you mentioned. Emacs as a way of life is a no go for most developers. I may love Emacs but I want to be able to edit my project with something else if need be (IntelliJ IDEA?) and I definitely don't want to force my users to any particular IDE. Making my project only really accessible to Emacs users just to be able to work with document files seems like a very good idea if I want to discourage them from ever looking at it.
- globular-toast 7y agoThere's nothing at all tying the org-mode format to emacs. It's a plain text format which any editor supports and syntax highlighting would be just as simple as for markdown.
- loeg 7y agoDoes any editor other than emacs support it in practice? And does the tooling around it run outside of elisp?
- zimpenfish 7y agoI'm a ludicrously casual user of orgmode but https://github.com/jceb/vim-orgmode https://github.com/jceb/vim-orgmode works for me in conjunction with the beorg iOS app.
- arh68 7y agoThere is a Sublime Text plug-in [1], but it's been a while since I used it. I think it's in Python, not elisp. If you're just looking to edit Org files, Emacs is hard to beat. I don't use Org files so much anymore, more OmniFocus & Markdown/Sublime. [1] https://github.com/danielmagnussons/orgmode https://github.com/danielmagnussons/orgmode
- greggman3 7y agoHmmm, * Markdown in HTML. NO!!! That would drive me crazy. I use HTML all the time for diagrams. If I had to be aware of every tiny place where my content in the diagram was going to get munged by the markdown parser I'd tear my hair out. * * vs - I've used * my entire life for lists, decades before markdown existed. Never heard of using - for lists until yaml * auto numbered lists. NO! The problem is it's nearly impossible to keep your formatting right if you have a long item lists. I often write answers on s.o. where it's like "You have 3 issues. 1. several paragraphs 2. several more paragraphs and code samples. It would be absolute hell to have to figure out the formatting to make sure auto numbered item 2 stayed 2 and didn't become 1 in a new list * code block indentation - agreed that code fences are generally better. Worse most places I enter markdown (stackoverflow) don't have any indenting/outdenting editor controls which makes it really painful. Either I had to manually indent 5 to 50 lines or else edit outside stack overflow and paste in. I know stackoverflow has Ctrl-K but it doesn't work once you take in account the list indentation issues. * no syntax for adding classes I don't mind that. It kind of feels like part of the point. If I need a class I use embedded html although that's another place to rant. Inline HTML uses markdown where as self contained HTML does not. I'd prefer they both didn't. In other words. If you put The big <span style="color: red">*bear*</span> you'll get a italic red 'bear' but if you put <div>The big <span style="color: red">*bear*</span></div> You'll get red '<asterisk>bear</asterisk>' Ok, I give up. no idea how to put an asterisk on HN. >:( As mentioned above I'd have preferred no markdown in HTML as it's bitten me quite often trying to color code variables in a math description that uses * and having the * get eaten by being parsed. * Ids - The id thing does bug me too. Markdown generates ids based on headlines but that's way too brittle. Edit the headline and your ids break. I also wish auto-numbered footnotes were a standard feature that worked by id so I could do something like [-fn-](#someid) and later #fn-someid paragraph a it would insert [<num>] at the top and link to #fn-someid at the bottom.
- NobodyNada 7y ago> * auto numbered lists. NO! > The problem is it's nearly impossible to keep your formatting right if you have a long item lists. I often write answers on s.o. where it's like "You have 3 issues. 1. several paragraphs 2. several more paragraphs and code samples. It would be absolute hell to have to figure out the formatting to make sure auto numbered item 2 stayed 2 and didn't become 1 in a new list I think you and the author agree on this point: Markdown does have auto-numbered lists, and the author of the blog post believes that was a design mistake. If you write a Stack Overflow post with a list numbered 3, 2, 1, it will be rendered as 3, 4, 5.
- pm90 7y agoI was turned on to ReST by a coworker and prefer it over Markdown. Aesthetically ReST code seems easier to read in raw form; and it’s somewhat more predictable in what works and what doesn’t because bad reST code breaks.
- swyx 7y ago[author here] wow I didn't expect this to shoot up so quickly! Obviously I love Markdown and use it every day. But like with everything you live with every day, you notice the little things. I @'ed John Gruber on my original tweet and readers might enjoy his response: https://twitter.com/gruber/status/1240888155307495426 https://twitter.com/gruber/status/1240888155307495426
- jimmaswell 7y agoWhat was even the motivation in the first place to not respect newlines?
- Someone 7y agoIf the first word after the newline wouldn’t fit on the last line before the newline, you can’t see whether there is a newline. Also, since you don’t know window width, that can happen even if, on your terminal, the last line of a paragraph is only 3 characters and the first word of the next is “A”.
- kccqzy 7y agoI assume you are talking about the fact that adjacent lines are merged into a single paragraph. Have you written traditional plain text emails or write any plain text documents? You almost always hard wrap your lines for readability. Even in HTML, newlines are mostly equivalent to just spaces.
- Carpetsmoker 7y agoThis is also very advantageous in diffs; diff-ing a Markdown file with many 1000+ character lines is rather hard.
- jimmaswell 7y agoWhen does a markdown line get that long?
- Carpetsmoker 7y agoWhen people write it like that?
- karmakaze 7y agoWhat's even worse is to insert newlines, you use invisible markup that will often get removed depending on editor settings: "When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return."[0] [0] https://daringfireball.net/projects/markdown/syntax#p https://daringfireball.net/projects/markdown/syntax#p
- vortico 7y agoAbout the header slugs: I don't think the content of the header should be the anchor ID. Readers will link to it, the author will fix a spelling issue or whatever, and the link will break and other readers will arrive at the top of the page when the browser doesn't find the old ID. My solution that works with most Markdown variants is to use inline HTML to define an anchor directly before (or after) the header. <a id="stuff"></a> ### Things about stuff But of course this isn't much cleaner than just using inline HTML for the header itself. <h3 id="stuff">Things about stuff</h3>
- swyx 7y agoas an author i'd say its rare to change headers, while its easy for the user to guess the right link if the id is broken. careful not to penalize the 99% usecase for a slightly better 1% usecase.
- chrismorgan 7y agoSome tools are now allowing you to manually specify the ID in this way: ### Things about stuff {#stuff} Hugo works that way by default, and I copied that syntax for Zola in https://github.com/getzola/zola/pull/685 https://github.com/getzola/zola/pull/685 last year.
- lenkite 7y agoPrefer Asciidoc over Markdown. Easier to remember syntax, richer set of controls and more importantly - better tables. Tables in Markdown are a nightmare. Asiidoc is a lifesaver for tables. For big tables, columns can be specified as rows leading to sane reading.
- rambojazz 7y agoIMO Asciidoc tables can get messy quite soon, to the point that at that point I'll just use HTML.
- gerikson 7y agoI just ”shell out” to HTML for tables.
- swiley 7y agoHow do you make PDFs? When I’ve used html features I’ve resorted to weird tricks with WebKit but that’s really not great.
- Carpetsmoker 7y agoHTML tables are hard to write, read, and edit though. If you want to make the document easily readable both as HTML and Markdown (quite useful for a README, I think) then it's not a very good option.
- battery_cowboy 7y agoKinda on-topic (50/50): I'm looking for a flavor of something-like-markdown, but it would have semantic tagging and some abilities to add my own attributes to an element/tag (like for links, I want to be able to specify some to open in another tab, but others to open in the same tab, I'm willing to do that with raw attributes if I can add them on) for conversion to HTML in a static generator, is there something like that anyone knows about? (I prefer not to "roll my own" if I can use a standards-based language) For instance, I'd want to do the example in the GitHub flavored markdown with tags like <article> or <aside> around markdown-like syntax. Markdown is so easy compared to HTML, so I want that ease in my article-writing workflow. I was considering using HTML directly in a templating language, but I want it to be a more human-friendly text format, like Markdown.
- aib 7y agoHave you seen Pandoc[1]? I'm not sure it supports the particular cases you've stated, but I've been using it happily as an HTML generator[2]. 1: https://pandoc.org/MANUAL.html https://pandoc.org/MANUAL.html 2: https://www.aib42.net/articles https://www.aib42.net/articles source at https://github.com/aib/www.aib42.net/tree/master/articles https://github.com/aib/www.aib42.net/tree/master/articles
- battery_cowboy 7y agoI'll look at it thank you
- thayne 7y agohave you looked at asciidoc?
- battery_cowboy 7y agoI will do that, thank you for the suggestion
- Eugeleo 7y agoYou could try Pollen [1]; there’s a little bit of setup, but you can generate beautiful webpages in it. It even has a markdown dialect, in which you write most things in markdown, but you can also add your own custom tags. [1]: https://docs.racket-lang.org/pollen/ https://docs.racket-lang.org/pollen/
- russellbeattie 7y agoMy firm belief is that if Markdown had never been adopted, we would have a standard way of formatting text by now supporting these 10 basic formatting types: headings, paragraphs, bold, italic, strike-through, monospace, bullets, links, images and horizontal rules. That's it. Just 10 basic formatting options. There's no reason why, in 2020, these aren't available everywhere. Just like every text editor can understand emojis (with colors even!), these simple formatting rules should be baked into every platform by now, and easily used on everything from PCs to phones to TVs, in every editor from Vim in a terminal to email to iMessage to Wikipedia's text entry box. Just like emojis are. It's truly insane we haven't standardized this yet. How old is RTF or PDF? Doing this basic formatting in ascii text is just mind-numbingly stupid.
- madhadron 7y agoWindows and macOS do carry italics, strike-throughs, and the like through copy and paste. I think it's the tyranny of the teletype emulator that keeps us doing this. After all, why shouldn't we issue textual commands to a computer in a more sane environment?
- ilammy 7y ago> Windows and macOS do carry italics, strike-throughs, and the like through copy and paste. There is no magic, they do it by literally exchanging HTML on the clipboard. Applications use it as a lingua franca and convert the text into whatever form they use internally.
- orthoxerox 7y agoHTML? Not RTF?
- ilammy 7y agoI'm not that sure about macOS, but on Windows that seems to be way more prevalent in my experience (had to deal with it when worked on clipboard redirection via RDP). The format also has some additional metadata embedded into it [1]. After all, Windows applications kinda pioneered "rich text" exchange via clipboard. [1]: https://docs.microsoft.com/en-us/windows/win32/dataxchg/html-clipboard-format https://docs.microsoft.com/en-us/windows/win32/dataxchg/html... The format is actually negotiated by the communicating applications so it quite can be RTF too, depending on what formats the applications can produce and understand and the priorities they give to them.
- combatentropy 7y agoI wish that markdown formatted bold and italics like this: _italic_ *bold* instead of: _italic_ *italic* __bold__ **bold** because stars around a word make it look like it's glowing, sort of like bold does, and underlining a word means to make it italic. Does no one remember this? In English class, before computers, our teacher told us that certain words are always underlined: book titles, ship names, etc. In Typing class, our teacher told us that if you submitted a typewritten manuscript to a publisher, what you underlined with your typewriter would be converted to italics in a typeset book. Underlining meant italics. And sure enough, nowadays when everyone has a computer instead of a typewriter, and can make real italics, they tell us that book titles, ship names, etc., ought to be in italics (the same things that my teacher used to tell us should be underlined) https://www.purchase.edu/editorial-style-guide/general-style-preferences/italics-and-underlining/ https://www.purchase.edu/editorial-style-guide/general-style... I get kind of why Gruber did it his way. He was caught up in the Semantic Web, where you don't use <i> and <b>, you use <em> and <strong>, and <strong> means <em> only more so. So by that logic *this* is emphatic, and **this** is strongly emphatic.
- kazinator 7y agoMoreover, the convention that you advocate is more or less an established practice in Usenet and mailing lists, long preceding markdown. This design decision in markdown is uninformed.
- Sniffnoy 7y agoAgree in general, but don't like the underline/italic thing. Most word processors have underline as separate from underline. Hence the alternative old email/Usenet convention: underscores for underline, slashes for italic.
- combatentropy 7y agoProfessional typesetters have an aversion to underlining text. It's ugly. The line interferes with descending letters: f, g, j, p, q, y. The underline is as thick as the stroke of a character, so decorative marks compete with signal marks. It's just too strong. That's why you see text underlined in homemade flyers but almost never in books, magazines, newspapers, or other things designed by pros. The recent addition to CSS to specify that underlines go behind the descenders is a welcome change. Professional web designers have the same aversion that print designers have, they are birds of a feather. But now they have another reason to hate it. Underlining has come to mean hyperlink. Because of their original aversion, they will often use CSS to remove that default underline, maybe bringing it back only when you hover over a link. But because it is still a widespread convention throughout the web, and probably always will be, they would never, ever emphasize something by underlining (they use border-bottom ;). Since you should underline something only if it is a link, which has its own markdown, and since underlining is ugly anyway, and since bold and italics are enough ammunition for all your emphasizing needs, and since it is an established convention from the old days that underlining meant eventual italics when it went to press, it's okay in my book to repurpose _underscores_ for italics. Slashes instead on both sides like /this/ --- hmm, it's not bad. I'm undecided.
- chrismorgan 7y agoreStructuredText on these, for anyone that’s curious or thinking about it: 1. If you use “5.”, it’ll give you a five. If you want auto-numbering, use “#.” as your prefix. (While I’m thinking of it: I hate that using actual Unicode bullets like “•” doesn’t work in Markdown, and that in https://talk.commonmark.org/t/unicode-character-bullet-u-2022/397 https://talk.commonmark.org/t/unicode-character-bullet-u-202... it’s been actively rejected for CommonMark.) 2. Code blocks are by indentation only, no fencing, but avoids confusion about indentation levels by defining all of that stuff properly and having it match visual usage, rather than Markdown’s crazy “four spaces, but in certain situations we’ll let you get by with 3, 2, 1 or even 0—but if you then seek to nest, remember to bump it up to eight rather than just N+4”. Code blocks are indicated by `::` at the end of or as the entire previous paragraph, which is esoteric, but also fits in very well with its directive syntax, which is how you can attach extra metadata to code blocks. It’s definitely not as simple as the newer Markdown fencing approach, though it fits into the rest of reStructuredText in a sane and principled way so that it’s not at all hard. Still, I think that a new version of reStructuredText would quite possibly include fencing in some form—or maybe directives would be resyntaxed to be able to be fenced rather than indented, though achieving that while still allowing nesting would take care. 3. Markdown in HTML in Markdown? That Markdown extends HTML is the real problem here, and is both its greatest strength and help in adoption, and its catastrophic weakness. reStructuredText is a language of its own that doesn’t extend anything, so that style of HTML output is typically done by defining new directives, which can then contain reStructuredText. It’s strictly less powerful, but it composes way better. As a workaround, the `raw` directive lets you put in arbitrary HTML (or LaTeX, &c.). 4. By deliberately not being HTML, reStructuredText handles this sort of thing much better. Each node in the document can have classes (which will end up as class="…" in HTML, something else in LaTeX, &c.). You can do things like `.. class:: …` to apply a class to the next block (heading, paragraph, list, &c.). Most directives support a :class: option. You can define new roles so that :classname:`…` will do what you desire. And none of this is then tied to HTML. 5. reStructuredText lets you define anchors at any place in the document (which can also be used for index entries when writing books or things like that). `.. _anchor-name:` above the heading will do it thus. This protects you against the anchor changing (and thus breaking links) if you change the text of the heading. Any form of automatic heading ID generation is left to the software to decide, e.g. Sphinx generates IDs by default. 6. Field lists. A field list at the start of the document is treated as document bibliographic data, and you can put anything in there you like. I myself prefer reStructuredText in almost all regards, but I scarcely use it any more other than for a couple of types of personal documents, because of the ubiquity of Markdown. It was similar with Mercurial and Git.
- okapii 7y agoYou create empty lines by adding two spaces at the end of lines. MD has invisible syntax. To me this without doubt is the worst thing about MD.
- freepor 7y agoPeople put too much behind Markdown is what happened. It was just a random idea on a blog post. But people made it a universal authoring standard and it is just not up to the task.
- foolfoolz 7y agoi actually disagreed with a lot of these. markdown is opinionated. the feature set is limited. the output looks almost all about the same. this is the goal. no one wants the myspace outcome of simplifying messages. you usually don’t need much styling but the tools that markdown includes are good enough. if you need more you probably want to ask why you’re writing in a place that only accepts markdown
- boublepop 7y agoSo are you saying that you disagree with the current “hmtl as superset” version of markdown? Or are you saying that it’s good that he didn’t go all the way and support markdown-in-html-in-markdown because the halfway point makes it perfectly half usable for the point of having html in the first place? Markdown is great but there are some minor points where it fails spectacularly with only minor tweaks needed to improve it tremendously. Also code ticks at its point to most are just considered part of “standard” markdown.
- slantyyz 7y ago> markdown is opinionated. This. If I were to guess, Gruber made Markdown to make writing for his blog easier. Then he made it available for whoever wanted to use it too, which was very nice of him. Given how there are already multiple flavors of Markdown available that address various shortcomings, I don't know if there's a point to critiquing Gruber's original version of Markdown since it was likely created to satisfy his writing requirements first and foremost.
- ashton314 7y agoShameless plug: I do 99.98% of my work in a terminal, and I'd much rather read markdown like a man page. I created a little utility to display Markdown (actually, any kind of file that `pandoc` can read) and displays it nicely formatted. You can see it here: https://github.com/ashton314/marked-man https://github.com/ashton314/marked-man Hope someone might find it useful. :)
- stragies 7y agoI use a variation of the shell-pipeline you use in your `mm` script. I don't know how to do code blocks here, so I'm pasting the un-commented one-liner mdv () { pandoc -s -t man ${1:-"-"} |groff -T utf8 -man | sed 1,4d | head -n -4 |${PAGER:-$(DN=/dev/null; which less &>$DN && { echo "less -FRSEX"; }|| which more 2>$DN || echo cat)} ; } from my answer here: https://stackoverflow.com/a/61029131/5208540 https://stackoverflow.com/a/61029131/5208540 This is a shell function to add to your environment
- SeriousM 7y agoThings it did right: It was the right tool at the right time. Everyone knows it and can use it. It's like Javascript for documentation.
- KKPMW 7y agoSome of those things are addressed in my favourite markdown variant - multimarkdown https://fletcher.github.io/MultiMarkdown-6/MMD_Users_Guide.html https://fletcher.github.io/MultiMarkdown-6/MMD_Users_Guide.h... The author has found a sweet spot between being very conservative with the original declarations and adding the missing functionality. It also comes with an amazing lightweight implementation written in C that behaves correctly: gets input from stdin or a file and passes it to stdout, without the -o flags that (e.g.) pandoc is using.
- suref 7y agoI'm currently working on a markdown system where I wanted to extend codeblocks to be able to incorporate more information. The `js:title=example.js` just doesn't cut it. Want I landed on was some sort of yaml-ish format: ``` *** property1: ... property2: ... *** code ``` This way multiline properties are supported and I can also incorporate markdown inside the properties themselves.
- mmcnl 7y agoWhy do these articles always pretend to be so know-it-all? I really don't like the explicit statement that "Markdown got it wrong", leaving no room for debate. For everything that Gruber supposedly "got wrong", a lot of arguments can be made for why Gruber got it "right", the author often explains that himself. That means that a lot of this is subjective. Let's keep the facts and opinion separate.
- slantyyz 7y ago> Markdown got it wrong You're right. The problem with the statement is that there's a presumption Markdown was created for the world at large, and I think it was originally designed for one "customer", who also happened to be the creator. Which means Markdown got it right.
- coffeefirst 7y agoIt's also weird to say "this is wrong" about missing features that there are widely-used extensions for.
- BerislavLopac 7y agoAnd one thing that this article gets very wrong about Markdown: It was not designed to be a structured markup syntax of any sort. The syntax, in fact, was never actually designed as such. Markdown originated as, basically, one guy's attempt to convert instances of unofficial text-formatting convention, commonly used in text-only communication such as emails and Usenet, into HTML that can be presented on the Web. In order to do that he had to enforce some standards, while still leaving some flexibility (which is why the top levels of headings have more than one forms; both were commonly used to designate the same thing). It was only after companies like Stack Exchange and GitHub started using Markdown as, ironically, a markup language, that there were any attempts to enforce a standard. I clearly remember a whole online "war", for the lack of better term, arguing pros and cons of standardisation.
- ddevault 7y agoWhat this fails to capture is the original motivation behind the design of Markdown. It was based on things people were already doing to add "markup" to plaintext things like emails. It was designed to just werk to convert your normal email-esque writing style into HTML. This article considers Markdown from the opposite perspective for which it was designed. In other words, Markdown is not designed to be a simplified markup language for HTML. It's designed to make HTML a frontend for plaintext. The numbered lists with *., for example, would be totally unreadable in plaintext without context.
- scelerat 7y agoMarkdown drew its influences from predecessor structured text languages whose goal was minimum formatting of ASCII text in a structured way such that it could be parsed and re-rendered into any other format. The goal was simplicity and readability in plain-text email and Usenet posts so I'm not surprised that fifteen years from its inception, and thirty or more years on from some its antecedents, we're using text and thinking about how we use text differently. One of Markdown's pivots from setext was the addition of code blocks. In the environment that setext was created, a code block would simply be rendered much like everything else: in the plain and probably fixed-width display that your email was also displayed in. By 2004, email had rich formatting, Usenet was on the wane, and people still needed a lightweight text format to share. Markdown filled that need, as did a number of other similar alternatives, though I forget their names. My first exposure to such lightly-formatted ASCII was setext [1] which was the format chosen for the Mac- and Apple-oriented TidBITS email newsletter [2]. As a contributor to that newsletter, Gruber would have been intimately aware of the format. Twenty years ago, I used setext in code projects basically the same way as nearly everyone uses Markdown now. I like OP's suggestions though I've always liked the 'lazy' approach to ordered lists. [1] setext: https://en.wikipedia.org/wiki/Setext https://en.wikipedia.org/wiki/Setext [2] TidBITS: https://tidbits.com https://tidbits.com
- kerkeslager 7y agoI agree with some of this (i.e. the numbers), but I think it's coming from a place of not understanding what Markdown is for. For example, your complaint about indentation for code blocks makes no sense if you're using Markdown appropriately. The original idea was to take emergent syntax used by text file authors as cues for humans reading text files, and use that as a syntax for generating HTML, so you could use text files as the source of truth for generating HTML. Backticks aren't an emergent syntax used by text file authors as cues for humans reading text files--that's a syntax directly intended for generating code blocks in HTML, with little semantic value if the markdown is going to be consumed as text. If your goal is to have something consumable as both text and HTML, then some sacrifices have to be made, because text simply can't do everything that HTML can. The error-prone indentation syntax is just a compromise, but there were features that were left out completely. The original markdown didn't contain underline or strikethrough, for example, because text can't do those things. The problem is that for a few years, this idea turned out to be useful as a way of allowing users rich text editing capability on websites. So people wanted Markdown to do everything that HTML could do, hence we get underline, strikethrough, code fences, etc. This hurts use cases where markdown is used for its original purpose, because modern markdown isn't as nicely consumable as text files, but users didn't care because they weren't using Markdown to be consumable as text files. And this made sense for a while. And where this becomes stupid is that if you don't care about it looking nice as text, then you shouldn't be using Markdown. There are a wealth tools for rich text editing on the web (TinyMCE being the most obvious choice, but not the only one available) and they're FAR superior in user-friendliness to Markdown. Many actually support Markdown, but there's less and less reason to even expose that functionality to your users. If you don't care about how your Markdown looks as text, then just use HTML and edit it with a rich text editor. There's another use case where you want to compose HTML content without the overhead of actually writing HTML, but you want to "do it like a coder", so using a rich text editor isn't appropriate because you want to be able to diff and whatnot. But in that case, there's still no reason to be using markdown, because if you're "doing it like a coder" than you can just write code which makes what you're doing much clearer, and give you a lot more power. Textile, Org-Mode, LaTeX are all better options. GitHub has persisted in using Markdown well past the advent of mature web text editors, because they still seem to be operating under the illusion that nontechnical users will become a significant part of their user base. Slack and Reddit are both moving toward fully rich text, and the fact that they are still trying to expose their Markdown roots just makes their rich text painful to use. MediaWiki using their markup language still, probably because they are blocked by the enormously difficult task of migrating an enormous amount of content, but if you're starting a new project, you don't have any of the tradeoffs that these organizations do, so you shouldn't make the mistake of following in their footsteps.
- wackget 7y agoThere's also no way to create vertical tables with headers on the left: https://stackoverflow.com/questions/60995936/vertical-table-headers-i-e-headers-on-the-left-in-markdown https://stackoverflow.com/questions/60995936/vertical-table-...
- andrew_ 7y agoTL;DR - "Markdown is too simple for me, I'd like it to be more nuanced" I'm not saying that to be cheeky. The article can be boiled down to that because the author is looking for HTML features in Markdown, when there's very little need. e.g. we don't need classes in markdown and we don't need IDs or `name` attribute specifiers because that can be accomplished already by mixing in the HTML that one needs.
- cornishpixels 7y agoHonestly, the single biggest problem with Markdown is that it's been implemented in so many different ways by so many different people. This is largely because a lot of corner cases were simply not defined. When a website uses Markdown for input, it's extremely tough to be sure of how to format certain things, especially when multiple different syntaxes combine. (I'm thinking of things like list+code block; or bold+italics, or list+line break, etc.)
- hodgesrm 7y agoMarkdown has similarities with CSV which is also underspecified and has varying implementations. Even simple things like quoting don't work consistently across applications. That has not stopped countless applications from using CSV because it's so useful to have a simple transfer format. CSV corner cases usually don't hurt too badly because you can usually rule them out based on the source or sink of the data.
- Already__Taken 7y agoThe second you want to do code and images on a page I just spend all my time fighting whatever markdown workflow is in place. Which would be fine if it added anything but they never just work, you still need to do your own image optimisation and aligning images or custom layout sections is terrible or not possible. Markdown is harder to work with in the long term than just wiring HTML with Emmet. That's my opinion a few years ago and these days I'd double down on it as editors are so good. Tables suck in everything so we should standardise a json and/or csv import language to drop tables in a built time anyway. Markdown is good for notes. Even mermaid diagrams are kind of unpleasant to write.
- jdeisenberg 7y agoYes. At times I would like to be able to use italics in a code block to emphasize some portion of the code, and that seems very difficult, if not impossible, to do. I realize this would conflict with automatic syntax highlighting, which is probably why it is not allowed.
- RMPR 7y agoTypo > differnt types of content.
- brianzelip 7y ago> There's nothing I hate more than reading a good article with headers, wanting to link someone directly to the section relevant to them, and then not having an id to use to send them straight there. Lots of other things I hate more than this, but dagnabit this drives me nuts too!
- jesse_m 7y agoI can't stand the invisible syntax like a double trailing space is some valid syntax.
- jesse_m 7y agoI can't stand the invisible syntax like double trailing space.
- blackrock 7y agoMarkdown has been a godsend. It’s just what I wanted. Something text based, where I can sorta control some formatting, but isn’t tag heavy like HTML. I just need it to format a few things, to make it easier for myself to consume later. The most useful for me is actually the syntax highlighted code blocks. I use it mostly for brain storming, planning, and scratch work.