The text/markdown media type | Hacker News Reader

The text/markdown media type

tools.ietf.org

152 pointstreve63 comments

The following RFC which sketches out a system for registration of markdown variants is much more interesting:

https://tools.ietf.org/html/rfc7764

Maybe, eventually, I'll be able to open a markdown textarea on a new website and be able to predict what markup will actually work!

Yep, but I can't remember the difference between Chrome Markdown, Firefox Markdown and Edge Markdown. - me, in the future. I have a hard enough time with GitHub Markdown and Reddit Markdown, as it is.

Obligatory: http://commonmark.org

That was a jab at browsers and their history of not supporting specs identically. HTML5 is also a "strongly defined" specification and it didn't help.

Looks like fenced blocks are part of the spec - will you be adding them to SO?

codinghorror no longer works at SO

http://blog.codinghorror.com/farewell-stack-exchange/

Yea! Great read.

Perhaps what we need is a registry in which we can store (functional) descriptions for converting markdown variants to e.g. HTML and back.

With the author so against standardization of his child, why aren't them pushing text/commonmark instead?

Exactly my thought, also markdown is inconsistent at places

Well, it's a Request for Comments; I think that yours is a pretty good comment to submit.

That's a interesting point never occured to me to comment on these. Went to the ietf website but there was no apparent way to comment. I'll try later on a pc

There's no way to comment on the website directly, so I think they are requesting that comments be submitted via email. I found this towards the bottom:

> Contact Information:

> (individual) John Gruber <http://daringfireball.net/>

> <comments@daringfireball.net>

I think you would rather want to contact the author of the RFC than Gruber.

  Author's Address

   Sean Leonard
   Penango, Inc.
   5900 Wilshire Boulevard
   21st Floor
   Los Angeles, CA  90036
   United States

   Email: dev+ietf@seantek.com
   URI:   http://www.penango.com/

You're probably right. I admittedly just searched for the word "comment".

Correct, the author of the Internet-Draft is the one to contact.

As noted by stronglikedan, the process to comment on an RFC is to send email to the author of the RFC, or alternatively, to the email list for the IETF Working Group from which the RFC came.

In this case, that would be the general Apps Area Working Group ( https://datatracker.ietf.org/wg/appsawg/charter/ ) and so comments could be sent to that list. Although sending to the author is probably the best initial route.

If the author receives enough comments to justify a new version, the process would then begin to publish a new version that would then obsolete the older version.

I would note that this particular document (the original RFC 7763 that is the origin for this HN thread) started discussion back in July 2014 with https://tools.ietf.org/html/draft-seantek-text-markdown-medi... and evolved over time until this publication now.

sigh I never understood why markdown (given it's lack of formal spec) "won" the light markup battle... I still think restructuredtext is syntactically better equipped and pleased to read...

3 reasons (for me)... all of this are harder to write and to remember in restructured text: source code blocks, links and images. Also sections definition is totally fuzzy for me http://docutils.sourceforge.net/docs/ref/rst/restructuredtex...

Markdown can work more like your mind. Restructured text is still too much like programming.

I agree on the section definitions. It's very hard to remember which underline I need to use because every project (or even document) can just define their own order implicitly. The sphinx project recommends a specific order somewhere in their documentation that I look up every time I need to write rst, but markdowns just-count-the-hashes is much easier.

I personally prefer Asciidoc(tor). The syntax for the basic stuff (headings, source code, links) is at least as easy as for markdown, but it also allows more advanced cases (tables, splitting into files, text substitutions, etc.) without resorting to writing html or using external tools. Asciidoctor also directly supports the markdown style for headings, block quotes, etc.

I see markdown more for writing a quick note or something that will not exceed a few pages.

Same here. Nothing can be built upon Markdown mostly because it allows raw html. Many nice and solid extensions have been made for rst.

Not true. I personally built a markdown extension to be able to use classes. Still escaped all html.

You don't have to allow raw HTML in your Markdown. It's just nice when you have trusted input (e.g. writing a blog).

If you don't allow raw HTML, markdown doesn't support underline. I've run into this more than once with users.

I guess that's a feature. Underlines on the web usually denominate a link, so offering underlines for non-links would just confuse readers needlessly.

(inb4 "But my use-case is different." Yes it is, but I'm talking about the web in general.)

To quote rule #10 of Butterick's Practical Typography[1][2]:

Never use underlining, unless it’s a hyperlink.

[1] http://practicaltypography.com/summary-of-key-rules.html

[2] http://practicaltypography.com/underlining.html

Users want what they want. I'm using markdown for a question text within an Android questionnaire system, and my users are MDs who don't like to be told "no, underlining is a bad idea", so our markdown is littered with <u></u>

Probably because it was designed by a writer, for use by writers as-is, inspired by existing plain-text email conventions.

Other light markup formats were designed by programmers, primarily for computer consumption, with readability by humans as a secondary goal.

This ^

It's a people problem, not a tech problem. I love writing in markdown because when I write, my mind works differently than when I code.

Ideally I could do anything that sort of feels right and the computer will just figure it out.

Markdown is the closest to that^ that I've ever used. It gets out of my way, which is what I want from a tool.

The lack of pure fancy spec is a feature

There are some cases where it fails, and those are ones where it makes no sense from a plain text perspective: two spaces at the end of line for a line break, and the image syntax (especially when you want the image as a link).

My guess would be because there is no Github Flavored reSturcturedText or anything similar. When large organizations that make software used by lots of people pick one of the options, it greatly increases the chances that that option will "win" over other, potentially better, options.

I found RST quite brittle (single underscore vs double underscore?) and hard to remember/type.

Markdown is generally less expressive (I would love if MD had RST's "include" directive) but I find it much easier to format a doc in MD.

Markdown won for me because I never had to learn to use it; I just write text like I'd be writing it anyway, having grown up on plain-text email and the like, and for the most part it just works.

FYI: Following the HTML model I've started a Can I Use ___ ? version for markdown e.g. Can I Use footnotes, tables, heading ids, citations, definition lists, etc. -> http://manuscripts.github.io/markdown-can-i-use Still early. For an example page see Can I Use Heading Attributes? -> http://manuscripts.github.io/markdown-can-i-use/heading_attr... Cheers.

Hurry up :)

Figures, captions, and tables are the ones I need to know.

I don't know if this is how you'd do it in markdown. My text tables are generally done this way:

    +-----------+-----------+-----------+
    | label a   | label b   | label c   |
    +-----------+-----------+-----------+
    | r1f1      | r1f2      | r1f3      |
    +-----------+-----------+-----------+
    | r2f1      | r2f2      | r2f3      |
    +-----------+-----------+-----------+

GitHub Flavored Markdown version: https://help.github.com/articles/organizing-information-with...

See [Pandoc's Markdown](http://pandoc.org/README.html#pandocs-markdown) that has everything. Will add all pandoc extensions over the next couple of days to the Can I Use ___ ? site. Cheers.

PS: To quote:

Extension: implicit_figures

An image occurring by itself in a paragraph will be rendered as a figure with a caption. The image’s alt text will be used as the caption.

Extension: table_captions

A caption may optionally be provided with all 4 kinds of tables. A caption is a paragraph beginning with the string Table: (or just :), which will be stripped off. It may appear either before or after the table.

And so on.

Markdown is a case study in "worse is better". It's a great idea, the fact that human/machine friction must be reduced to the essential for this kind of application, and that 99% of the times you need just the basic features: titles, italic, bold, lists, unformatted code blocks, and a few more. But this initial intuition, was not supported by a good design, since the evil is in the details. I hope somebody will build a new syntax based on this initial intuition, but doing a better work.

The key point to understand, IMHO, is that Markdown is an user interface. That's why strongly-engineering-minded people fail to provide something that people want to use, and why instead Markdown won.

Markdown as a media type will have arrived when the first spam email is sent in markdown.

Figure 1 alone is a good reason to peek at the RFC. So glad someone is keeping RFC-style "diagrams" alive :)

Related discussion on the CommonMark (markdown standardization initiative) forum: http://talk.commonmark.org/t/ietf-request-for-input-text-mar...

Shouldn't it be text/plain? I would've though that a specific mime-type defeats the format's original purpose.

Well, text/html is also pretty non-specific.

Exactly! I thought the point was that it was plain text that can be transposed to html. This mime-type designates it as a mark-UP, defeating the whole point!

Mime type parenting is a thing. There's plenty of IANA-registered mime types which have text/plain, application/zip etc as parents.

The pushers("Pandango, Inc.") run a webmail service, so I think the intention of this is that if you wanted to write an email with more expressive styling, you could use markdown instead of having to write HTML.

? who talk about websites, javascript and whatnot?

There is computing beyond web. This is a mime type, which is a slightly wider area.

FYI: Another markdown news byte. I've started a dedicated Markdown news channel trying to cover tools, book formats, extension, tips & tricks and more. Follow along on twitter -> https://twitter.com/manuscriptsnews Cheers.

Is the intent of this RFC to move towards useragents accepting markdown to render? If not, what's the purpose of an IANA registered type?

Webmail.

Penango (the company of the author) is a webmail company and so I would imagine that they wish to declare a mimetype so that they can default to supplying a MIME part that is text/markdown as the body of a message.

Ah, thanks. I guess a simple markup for email would be nice, but cannot see it being adopted enough to make it worthwhile for senders.

It's quite a nice solution... as you can believe that the text part is formatted reasonably well enough that you could present it as the text/plain part to external systems, and yet you know that you can also transform it to create the text/html part for other systems.

Whilst you only need to store the one part, the text/markdown.

It also gives you the ability to run a sanitizer after the markdown transformation, so that if you are a webmail host (as they are) you've got this really nice place to perform sanitization of what will be the email HTML before you send it to your web page.

Does anybody know if RFC-1563[1] was adopted by many e-mail clients?

1: https://tools.ietf.org/html/rfc1563

LaTeX is given as an example of a markup language alongside HTML.

Is it allowed to be both that and a turing-complete programming language?

I would rather say that (La)TeX is a turing-complete programming language that includes an extensive typesetting library. :)

It's still markup for probably the majority of its users.

Is it right now to expect browsers to render markdown file natively?

No - this spec is just for defining a media type. I doubt that browsers are going to touch Markdown anytime soon, given the number of flavors we have right now. However, you can do it with a plugin: https://addons.mozilla.org/en-US/firefox/addon/markdown-view...

There's a typo on page 6: [f0o]

Read the context: that's deliberate.

Reply on news.ycombinator.com