1. 23

  2. 24

    I can sympathise with jgm’s desire for a simpler spec; modern Markdown is “more congealed than designed”, to misquote Douglas Adams. However, I’m pretty sure one of Markdown’s original design goals was to make good-looking, readable plain-text documents, ever-so-slightly constraining existing conventions so that they could make good-looking, readable rich-text documents too.

    To dramatically reduce ambiguities, we can remove the doubled character delimiters for strong emphasis. Instead, use a single _ for regular emphasis, and a single * for strong emphasis.

    The trouble is that in plain-text documents, people traditionally used * and _ for level-one emphasis (read as “bold” and “underlined” respectively), but typographic tradition is that level-one emphasis is italic text. So “single for level-one emphasis, double for level-two emphasis” is the most natural, semantic translation.

    Shortcut references like [foo] would have to be disallowed (unless we were willing to force writers to escape all literal bracket characters).

    I don’t know how I missed it, but until this year I missed that shortcut references were even possible. I started off with long-form [text](url) references, which looked ugly and broke up the text, and eventually twigged to [text][tag] references which still look weird to people who don’t know Markdown (or people who haven’t seen that syntax before). Just being able to write [text] in running prose marks that text as special without overly distracting the reader, and if the next paragraph (or something at the end of the document) says [text]: http://example.com the association should hopefully be plain.

    Since we have fenced code blocks, we don’t need indented code blocks.

    Fenced-code blocks are weird and ugly unless you’re already familiar with Markdown, while indenting is a clear visual delimiter.

    Instead of passing through raw HTML, we should introduce a special syntax that allows passing through raw content of any format.

    I can appreciate this from a technical standpoint (it’s a simple rule that solves a whole class of problems!) but even without raw HTML support, Markdown is pretty heavily tied to the HTML document model. Consider Asciidoc, which is basically Markdown but for the DocBook XML document model instead. There’s definitely similarities to Markdown, but the differences run much, much deeper than just what kind of raw content pass-through is allowed.

    We should require a blank line between paragraph text and a list. Always.

    This also is an excellent technical opinion, but click through to the OP and look at the examples of the new syntax and tell me whether either of them look pleasing.

    Introduce a syntax for an attribute specification.

    This definitely makes Markdown more flexible, but doesn’t make it any prettier to read. Also, if anything it ties Markdown even closer to the HTML document model.

    Overall, these changes would move Markdown further from being a plain-text prettifier, and closer towards being a Huffman-optimized encoding of HTML. That’s not a bad thing, and certainly it seems to be what most people who use Markdown actually want, but it’s quite different from Markdown’s original goals.

    When the CommonMark first began (as “Standard Markdown”), they tried to get John Gruber involved, but as I recall he refused to take part and told them not to use the name “Markdown”. I felt he was being a jerk, but having thought about it, I wonder if maybe he felt a bit like Chuck Moore about ANSI Forth, that the real value was the idea of a hastily-written script that took something human-friendly and made it computer-friendly, and making a set-in-stone Standard with Conformance Tests would be the exact opposite of Gruber’s idea of Markdown, no matter how compatible it was to his script. I imagine something like ABC notation is much closer, despite being entirely unrelated.

    1. 8

      You raise valid points and I can certainly understand where you’re coming from with “[o]verall, these changes would move Markdown further from being a plain-text prettifier” (to which I would sort of concur.) I have some disagreements about fenced code blocks and a blank line between paragraph text and a list but they boil down to personal visual preferences. Code indenting is in my opinion ambiguous and I almost always insert a blank line between paragraph text and a list item. It’s great that original Markdown allows for both.

      On the other hand, I feel we have to acknowledge that original, i.e., canonical Markdown has evolved from Gruber’s original implementation and scope (simple blog posts?) to the lingua franca of text input in websites—such as the prompt I’m currently writing in—and the de facto plain text format or LaTeX pre-processor. For instance, I do all my writing in plain text Markdown and use Pandoc to produce LaTeX typeset documents, letters, and papers with bibliography. Heck, I even wrote a static blog engine on top of my publishing workflow to guarantee that one text source file produces the same document regardless of output medium (PDF, web, &c.) (The OCD kicked in, lol.) I am a big believer in plain text and separating content from formatting, and Markdown is a great, modern plain text format.

      Ultimately, I think we have to cater for and balance both realities. Gruber’s original simplicity of the format, which notwithstanding being ambiguous, should be the guiding principle, and the evolved scope of present-day Markdown. And, boy, that’s a tough one.

      1. 4

        I definitely agree. Like all successful technologies, Markdown has grown well beyond its creator’s intended limits, and as much as I miss pretty plain-text I much prefer Markdown to BBCode or the rich-text editing features browsers provide. ReStructuredText is a light-weight markup explicitly designed to support multi-target output and the kind of extensibility people want for Markdown, but I find it awkward and pedantic and I’d much rather use Markdown any day.

        I’m curious, though: you say “Code indenting is in my opinion ambiguous”, how so?

        1. 2

          First off, forgot to mention that I always use [link][tag] link references and didn’t know about tagless ones. Neat.

          Regarding your question: I feel like between tabbed and space-based indentation (which may output the source text differently when cating or writing in $EDITOR) and cases like list-nested blocks (should I indent again or maintain current indentation level?,) that you have to worry how different current and future Markdown interpreters will interpret the document. Instead, I find the fencing solution (with ` backticks, for the record) better and clearer: wherever I am in the document simply fence the code and be done with it—I don’t have to count or check the indentation.

          1. 1

            Follow-up: also what @myfreeweb and @Forty-Bot wrote below.

        2. 4

          [text][tag] references

          Ha! I only knew about the shortcut [text] references, TIL on the [text][tag] one :D

          indenting is a clear visual delimiter

          Indenting can be a pain to work with though. Especially in web comment fields!

          1. 4

            Indenting can be a pain to work with though. Especially in web comment fields!

            I end up having to paste text in and out of vim to format code correctly. Backticks are a much better solution imo.

            1. 1

              One of these days I’ll get around to writing a replacement for the “It’s All Text” extension that works with modern Firefox, then I can write all my comments in a real text editor!

              1. 3

                I’ve seen a few around, but haven’t found the time to test any of them to see how well they work.

          2. 7

            This topic resonates with me as the author of a Markdown utility. But I think it completely misses the point at what’s such a PITA about Markdown. And that’s not its annotational trespasses.

            The problem is that Markdown’s just a human-readable subset of HTML. It’s like writing in HTML without being able to use classes, semantic markup, metadata, IDs, forms, and so on. The original Markdown accomodates for this by allowing HTML directly in the input. So basically the Markdown because a textual preprocessor. Then there’s another problem: have you ever looked at an HTML-only document? No styling? So there’s a bundled cost in needing the CSS and embedded HTML (or templating HTML) for any (not non-trivial—again, look at the basic HTML document) document formatting. Or just use a Markdown extension or implementation that does it for you… which is another problem.

            All of the extensions and implementations balkanising the language try to sit between “presentation-ready HTML” and the original markdown. Some are reasonably standard, like metadata or tables. Then we have equations, footnotes, charts, video, etc., etc. Each of which has been implemented several ways. (Which table format would you like today?) And each one is called “Markdown”. Great! And then, some extensions clobber the original language—like metadata, which appropriates the first paragraph.

            In my opinion, this is just going to go the way of any commodity: the largest implementation will rule, and the rest will follow. Hopefully folks will come to their senses and just use HTML, but “sense”, unfortunately, is not found in the same quantities as Markdown implementations. Mine included. :)

            1. 2

              Despite the author specifies that in his opinion going beyond markdown is a useful daydream, I liked the reflection and the discussion (even here).

              IMHO, a pure “plain-text prettifier” (as @Screwtape called it) would be pretty useful. There are for sure tradeoffs to explore, but I guess that a minimal markup language is possible that can be structured enough to produce nice web pages, latex or pdf but yet clean and almost invisible in source form.

              1. 1

                I’d rather write Pug, honestly (it’s a Haml-like HTML dialect). Am I the only one? I don’t want to remember all these rules for lists and line breaks and whatnot. Markdown strikes me as both simple and confusing.

                If there’s a compelling non-HTML target for writing Markdown, I totally understand; power to them. I never found one myself.

                1. 5

                  Pug is much more oriented towards layout templates than text documents. I guess you can write articles in Pug, but I wouldn’t want to do that.

                  LaTeX is a very compelling non-HTML target!

                  1. 4

                    Any time I write anything for university which has to be handed in as PDF, I write in Markdown (with some LaTeX if necessary) and use Pandoc to output to PDF.

                    1. 2

                      Pug doesn’t look that satisfying to myself, but I try to do as much as possible in org-mode as it supports things I care about such as tables.

                    2. 1

                      I’d rather write latex