1. 3

  2. 2

    This is one reason I like Org Mode everywhere. There is one definition, one place to check documentation.

    1. 1

      We don’t need such a tutorial, and furthermore, it probably can’t even be realized. Markdown is one of those de facto standards that prioritizes ease of use over any kind of rigor. It’s Postel all the way down.

      I see little hope for such an artifact.

      1. 2

        It’s meant to be rigorous, actually - there was originally a precise spec written by John Gruber, who also wrote the first implementation. He had compatibility as a primary goal. Unfortunately, of course, within a year there were a dozen incompatible versions.

        The tutorial does seem realizable, though… this plan talks through how to deal with incompatible extensions and quirks. And, actually, I see a use for it. The “Markdown formatting available” popup here on lobste.rs doesn’t even come close to describing all the syntaxes that the implementation supports. ``` is notably absent and I had to learn it by asking someone. That’s not laziness on anyone’s part; it’s the developer not knowing what exactly the library offers, and probably having a skill-set which isn’t oriented around technical writing. Having a common tutorial to just include on every site would be quite nice.

      2. 1

        It took me forever to figure out some of the most basic markdown elements, so it’s not surprising when I run across people who have never used it before.

        As for creating a better guide - I think it would be a useful, but at the same time I can’t see it ever being overly useful either.