Things Markdown got wrong

  _italic_

  *bold*

  _italic_

  *italic*

  __bold__

  **bold**

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...

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*

  **this**

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.

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.

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.

I @'ed John Gruber on my original tweet and readers might enjoy his response: https://twitter.com/gruber/status/1240888155307495426

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.

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.

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.)

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.

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

  <h3 id="stuff">Things about stuff</h3>

https://github.com/ashton314/marked-man

Hope someone might find it useful. :)

When you're reading raw markdown they're extremely useful for short snippets since they save you two wasted lines per block.

* 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>

    <div>The big <span style="color: red">*bear*</span></div>

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.

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

[2] TidBITS: https://tidbits.com

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

https://stackoverflow.com/questions/60995936/vertical-table-...

Lots of other things I hate more than this, but dagnabit this drives me nuts too!

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.

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.

    ```
    ***
    property1: ...
    property2: ...
    ***
    code
    ```

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-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.

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.

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.

> differnt types of content.

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.

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.

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.