RFC 7764 – Guidance on Markdown

[Freak_NL]

What I would really like is to end up in a situation where email clients all support text/markdown. It really hits the sweet spot between plain text and HTML. It has enough structure to show a nice outline, and the triple back-tick syntax is great for marking bits of text as code.

All without specifying how everything should look. You can read it as unformatted text, or let the mail client format everything in a style you like. This is sort-of like HTML without CSS (using the client's default stylesheet), but also very well readable as unformatted text, and free from the abuse of HTML email.

Alas. More and more companies are giving up on plain text email (even though this is required by the standard), and simply send you a hyperlink to click if you have plain text as your viewing preference for email.

[bhaak]

> What I would really like is to end up in a situation where email clients all support text/markdown. It really hits the sweet spot between plain text and HTML. It has enough structure to show a nice outline, and the triple back-tick syntax is great for marking bits of text as code.

Then we would have come full circle. A markup language that has been at least inspired if not derived from decade old usenet/mail conventions would be back where it started from.

> [...] and free from the abuse of HTML email.

Are you sure? The advantage of text/plain in mail is that I see every link as it is and no resources are loaded from external sources.

With markdown support in mail clients, we might be back at early HTML support. Link destinations would be unknowable again.

> Alas. More and more companies are giving up on plain text email (even though this is required by the standard),

If it's not plain text, it has to declare a mime type (how would the mail client know how to render it?) but I don't think plain text section is mandatory.

> and simply send you a hyperlink to click if you have plain text as your viewing preference for email.

Go tell them, and you can quote me on that, that they are stupid. If my mail client doesn't render text/html and prefers the text/plain sections that is because it is configured that way.

I know of no mail client that isn't able to handle HTML.

[kbenson]

I think all it would take is Gmail adopting it to start a chain reaction, and Gmail adoption actually seems somewhat plausible to me. Google has a habit of implementing things aimed a bit more at power users (while also omitting things that a a bit more middle-of-the-road). I could totally see some internal project that does this for Gmail making it to the public.

[chriswarbo]

> What I would really like is to end up in a situation where email clients all support text/markdown.

I don't understand; markdown is text. If you send markdown emails right now, what's the problem?

Admittedly I might be biased, since I read mail as plain text in Emacs, but surely plain text emails will display in all mail clients?

[inopinatus]

For transactional email I like liquid templated markdown. We render each through liquid, then send the resulting markdown in the text/plain part, and render it with redcarpet and github's sanitizer for the text/html part.

We used to downsample from HTML to plaintext with many irksome artefacts arising. These look a lot better. It does oblige a certain discipline on the part of template writers, I consider that a good thing.

[mderazon]

Have you tried Markdown Here ? http://markdown-here.com/

I use it on almost every email. It is really great.

[verandaguy]

I'm actually kind of excited about this! A `text/markdown` MIME type could (maybe? hopefully?) pave the way for native content authoring in Markdown without having to use an HTML-targeting compiler between the author and the browser.

I might be being optimistic, but if that ever happens, it could be the start of a new era in internet content authorship!

[bhaak]

Which markdown? There are various variants out there and the original is unsuitable for more than a most basic web page.

The RFC for text/markdown includes a variant specifier but that only makes me think that we would be repeating the mistake of early browers when there were browser-specific HTML tags.

[ausjke]

Can't agree with more. It's a pity these days, for nearly all the WIKIs, CMSes, blog platforms, still markdown is not the native format supported out of the box, most of them needs plugins etc, or you need run a static-site-generator to convert markdown to HTMLs.

[doublerebel]

I've long thought that YAML instead of JSON and Markdown instead of HTML would be ideal for the average person to get into internet content production and sharing. Combining both specs is YAML Front Matter, where metadata can live with the document.

Sure, the YAML and Markdown specs could be more strict but right now browsers are very tolerant of malformed HTML.

Unlike HTML it would help separate data/content from presentation, which I think is at the root of ads and poor quality content we are forced to sift through now.

[tlow]

Are you aware of https://ia.net/writer ? It is a markdown text-editor for MacOS & iOS that many people seem to enjoy.

[mrottenkolber]

The best decision would be to drop Markdown from everything and pretend it never existed. Then design a similar format with a formal grammar, and use that.

The sad thing is this won't happen. Given the traction I suspect there will be broken, incompatible Markdown implementations 100 years from now. Markdown really has the potential to become the worst universally popular standard in computing history.

What bothers me is that its not one guy (Gruber) who made a mistake and designed a language without a formal grammar (hey, mistakes happen), its that armies of developers wrote broken parsers for a language without a formal grammar. This is an impossible task, why did they not refuse to create something fundamentally broken, by definition. Now there are apparently people who want to standardize Markdown, without a formal grammar. How can they not realize that it will be impossible to ever implement the standard? How do they not see that what they are doing is professionally unethical?

[jgord]

Nooo.. it just needs a proper formal grammar adopted, that captures the best of the common variants.

Then people can extend their tools to use that single variant and standard parser/grammar.

Most [good] languages were implemented first without a formal grammar - lex/yacc/bnf usually came later, if at all.

[jalfresi]

Don't markdown files already have a MIME type of text/plain? Isn't that the point of markdown?

[deckar01]

In the context of emails, I don't believe using a special MIME type for markdown provides any benefit. Raw markdown is plain text and generated content is HTML.

It seems interesting in the context of version controlled markdown files written for a particular hosting platform's markdown flavor, but I don't think a specification for identifying the flavor is the solution. This could be no different than any other form of documentation that is generated by a script or framework, but code hosting platforms have decided to make opinionated decisions for a magical UX.

[inlineint]

I'm not sure wouldn't someone say that it is bloating of such simple format as Markdown, but I really want to see embedding of TeX math formulas in Markdown RFC/standard.

I'm talking about $\frac 3 4$ and $$\int x dx$$ notation. It is already implemented in some Markdown parsers, such as Pandoc and Jupyter Notebook, but because it is not standardized there are also a lot of parsers that don't support it. I think that adding it to the RFC/standard would reduce friction in math communications and make them more accessible, especially if Markdown format become widely used for email communications.

[c-smile]

"Oh how many of them had fallen into that chasm..." (C) M. Tsvetaeva

Instead of markdown we need something what I name as flat structural text format.

     <text>Base level text</text>
     <text li="disk">Bulleted list item</text>
     <text li="numeric">Numeric list item</text>
     <text li="numeric" level=2>Another list item</text>
     ...
     <text>Inline <span bold>bold</span><span bold italic>bold and italic</span></text>   
     ...

In this case it will be trivial[1] to write WYSIWYG editor that has 1:1 mapping between markup and screen representation.

That 1:1 mapping is mission critical for human editing - our mental model of text is flat.

In fact that markdown is an attempt to provide such flat structural text representation. Ugly one we shall admit.

Microsoft Word, AFAIU, uses also flat DOM model internally, that's why its WYSIWYG is quite good.

HTML version 2 was last version that allowed unambiguous WYSIWYG editing of HTML. The one that had no idea of CSS.

[1] http://blocknote.net - WYSIWYG HTML editor that uses internal flat model.

[crooked-v]

This entirely misses the point of Markdown: that it's completely readable as a document without needing to apply any kind of visual formatting to it.

[nicky0]

> 1. Dive into Markdown

Is that an obscure Mark Pilgrim reference or just a coincidence?

[jschulenklopper]

More than a coincidence, I think.

John Gruber wrote a post titled "Dive into Markdown", https://daringfireball.net/2004/03/dive_into_markdown, and mentioned Mark Pilgrim in that post as well. It seems that John made a pun, applying the well-known titles of Mark's books to Markdown.

I guess the RFC copies the post title (and the opening quote by Stanley Kubrick) to pay an homage to John's start with Markdown?

[kevin_thibedeau]

Meanwhile Restructured Text chugs along with a more capable syntax designed for extensibility from the start and without the problematic fragmentation of dialects.

[austincheney]

https://github.com/prettydiff/biddle Can parse markdown to formatted stdout (ANSI colors, wordwrap, and so forth) on the console in both posix and Windows.

[smartmic]

I am still struggling with Markdown. In my opinion, the lack of a common, standardized specification thwarts its practicability as universal internet standard.

I still wonder why not more powerful markup languages like asciidoc spread more.

[glaberficken]

Amateur question: Why can´t browsers just fetch a markdown file and render its html representation? (is this what the article implies?)

[verandaguy]

Browsers implement well-defined web standards, which Markdown unfortunately isn't. The original author, John Gruber (of daringfireball.net), hasn't been too supportive of having a single, fixed Markdown standard, and this has resulted in spinoffs with various syntaxes and features:

- GitHub-flavoured Markdown

- CommonMark

- etc...

On top of that, there isn't even some meta-standard which would allow hashbang-style preambles/doctype declarations to determine which version of Markdown is being served.

So, between the fact that there's no fixed de-facto standard and no de jure standard syntax or feature set recognized by any of the major standards bodies (IETF being one of these), it would be impractical for browser vendors to implement support for Markdown.

Finally, the standards that browsers implement take time both while being defined, as well as while being implemented; these are things that will be seen by billions of people worldwide, and there's extremely little room for error, so revisions are always necessary at every stage in development. For example, work on HTML5 can be traced back as far as 2004, meaning that from inception to release, development took about a decade.

[dom0]

Because there are dozens of more or less incompatible markdown dialects.

[xer0x]

OMG wow! This could be really helpful!

[slezyr]

  ```
  function test() {
    return "notice this feature?");
  }
  ```

Ummm...

[MBCook]

Did anyone ask Gruber for his help in this? Or is this like the stupid attempt at 'common markdown' a year or so ago to wrest 'control' out of his hands because he was 'a terrible steward' (or whatever the quote was).

If a single guy invented the standard, and you're not involving him (or at least getting his blessing), then this seems hostile.

I haven't seen him mention this on Twitter, which is what makes me wonder.

[zeveb]

I don't think Common Markdown was a stupid attempt; I thought it was a praiseworthy attempt to standardise places where differing Markdown implementations differ, needlessly harming interoperability.

I think that Gruber deserves a colossal amount of credit for inventing the single-most-common end-user-usable marked-up-text format around. That's independent of what he's done in the dozen years since December 2004, which is the last update he made to his Markdown project's page.

[jrochkind1]

He generally hasn't been interested in any kind of standardization, of which this is an example, no?

[tbert]

I assume you didn't open the link. I appears to be a summary of the type of data you can expect when reading a text/markdown document. It does not define a standard, but it lists contact info for many of the different implementations.

[Karunamon]

I had a quick skim.. it appears this isn't what you'd think is a "markdown RFC", it's more like a list of different implementations with links to each. Most critically, it is not an attempt to standardize a specific dialect, or wrest control away from its creator.

My bureaucracy detector redlined the moment I clicked through, but then reset after a page or two.

[numbsafari]

I think Kubrick quote near the beginning is an... homage.