> markdown is a lightweight representation of html
This is my main problem with the article, as this is decidedly incorrect.
Markdown was designed as a tool of conversion of de facto standard of formatting text in email messages and Usenet posts of early nineties. The basic 7-bit ASCII nature of those technologies inspired people to informally annotate the text with special signs to denote formatting like emphasis, section titles and the like.
True, HTML shares a lot of similarities with that nameless standard, so John Gruber in 2004 wrote a basic script [0] to convert the latter to the former, never expecting it to become such a universally used actual standard.
The very first sentence in that link says “Markdown is a text-to-HTML conversion tool for web writers.”
Gruber did not take a "de facto standard" from Usenet and simply write an HTML converter for it. He designed his own markup, borrowing from Usenet and other conventions. The “Acknowledgements” section at the bottom of your link alludes to this fact.
Markdown was from the beginning intended as a markup syntax for web CMSs. To say it is a lightweight representation of HTML is correct. The whole point was that every part of the syntax produce a direct HTML equivalent.
Gruber writes that Markdown is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.
> To say it is a lightweight representation of HTML is correct.
It's correct in the context of (2) but not (1). In the context of (1), Markdown is a lightweight markup language for rich text. For example, Pandoc can convert Markdown to formats like PDF, LaTeX, and ePub.
It's also true in the context of (1), since the syntax specification specifically falls back to HTML for difficult things like tables.
This is made abundantly clear on the Syntax page[0]:
> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.
> Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.
> For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.
Markdown is very coupled to HTML, and is hobbled as a result compared to formats like Tiddlywiki and Org that not only have sophisticated syntax for all kinds of content like tables, but also directives to the parser itself to render particular blocks using an external tool. I wrote a bit about this in 2021 in response to query about why Org mode doesn't use Markdown[1].
> Markdown was from the beginning intended as a markup syntax for web CMSs.
As a matter of history you're right, just as JSON was intended as nothing more than the literal syntax for JavaScript programs. But it turned out to be a lot more widely applicable.
> To say it is a lightweight representation of HTML is correct.
No, it's a representation of writing. It represents the input not the output.
The first few years after I released Markdown, it was far less popular than I expected and hoped it would be. But it grew, and then for a years it was as popular as I’d expected. But then it kept growing, and now it’s far more popular and widely used than I’d ever thought possible. I genuinely now think it’s used in many cases where it shouldn’t be, and exposed to non-technical users who should be using something WYSIWYG, not markup.
I disagree. Markdown has always been about HTML - to the point that Markdown parsers support dropping actual HTML tags mixed in the the markup.
The fact that Markdown was inspired by email conventions doesn't make the statement "markdown is a lightweight representation of html" any less correct.
I thought a goal of Markdown was to be a set of conventions that were readable on their own as well as being transformable to a rich text/HTML representation.
You can read a Markdown document pretty easily using "less" or any other character-based interface.
The same is not really true of reST.
Maybe I'm confusing that with some other plain-text markup convention?
all of that is true, but markdown targets HTML as its "native backend", if you will. it is not feasible to render markdown -> pdf without having an intermediate HTML representation.
this is clear from the fact that HTML can be inlined in a markdown document; this is part of the spec (in so much as there even is a "spec" for markdown, anyway).
reST is also designed to have human readable source. You might not like it compared to markdown but it has to serve as a the docstring format of Python and does so fairly well.
> to the point that Markdown parsers support dropping actual HTML tags mixed in the the markup.
Some Markdown parsers support some HTML. You cannot, for example, add a YouTube video embed to a GitHub comment. Webpages that allow Markdown quite reasonably limit what’s accepted.
Usually, the colloquial conflation of Markdown with CommonMark and the numerous Markdown-esque dialects is helpful language, I've defended it here before.
> Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
It's not possible to read the original specification without agreeing that, yes, Markdown is specifically a way to generate HTML. It also has a nice syntax which has become popular in contexts where embedding HTML isn't a good idea, and there are some tools which allow Markdown to be converted to other formats as well (usually, but not always, these disallow most HTML tags, meaning that they aren't Markdown sensu stricto either).
I would say that all of this supports Hillel's basic point here: Markdown is in fact tied to HTML semantics, in a way which makes it painful to do things with it which aren't tied to those semantics in the same way. Dialects in the Markdown family exist which make this less painful, and they do so by diverging from the original Markdown spec.
> Markdown qua Markdown, unambiguously supports HTML tags.
The section I quoted (and responded to) didn’t say “Markdown supports HTML tags”, it said (emphasis added) “Markdown parsers support (…)”.
So unless you’re arguing that a tool cannot be considered a true Markdown parser¹ unless it parses HTML, the distinction is irrelevant. I wasn’t making a general argument, I was responding to a specific claim.
> You can verify that yourself
Yes, I am quite familiar with that subpar piece of code and specification. I have spent some time implementing a Markdown parser myself (the output wasn’t HTML) and Gruber’s resources were by far the worst. For various reasons he has been an awful steward of Markdown; its ubiquity is despite him, not because of. Forgive me if I don’t find the author to be the authoritative source anymore.
I think you’ve kinda lost the thread. From the top comment:
> Markdown was designed…
Surely Gruber is an authority on that.
And anyway, “ markdown is a lightweight representation of html” is true enough that calling it “decidedly incorrect” is wrong. Certainly it’s not a point that’s supported by going to author intent.
Dear HN: stop leaving comments like this. It's arguing over semantics and makes for boring conversation. It also violates HN guidelines for leaving comments:
- Please respond to the strongest plausible interpretation of what someone says, not a weaker one that's easier to criticize. Assume good faith.
- Please don't pick the most provocative thing in an article or post to complain about in the thread. Find something interesting to respond to instead.
If you disagree with the substance of the article, say you prefer Markdown to rST, then address that. Explain why despite the author's preference for rST, you prefer MD. It's silly to argue over this single sentence about exactly what Markdown is or isn't.
Markdown, Markdown, is nothing to do with email and Usenet formatting. It was a specific syntax, poorly defined, which has since become a broad family of mostly similar syntaxes; and it was inspired by various conventions from things like email and Usenet, some of which predate computers (e.g. pretty sure I’ve seen or heard of asterisks being used for italics in old typewritten stuff); but Markdown is all about HTML, its syntax is extremely constrained by HTML, and any attempts to separate it from HTML are fairly thoroughly doomed.
Saying that it has nothing to do with email/usenet is a bridge too far in the other direction, it was very much inspired by such formatting, something it never hid: https://daringfireball.net/projects/markdown/
> the single biggest source of inspiration for Markdown’s syntax is the format of plain text email
Yeah, it was inspired by those things, as I said, but it was never connected to them, and is quite incompatible with them.
I also express things that strongly because I’ve observed a distinct tendency to interpret Markdown as the successor of those things or the inventor of such syntax ideas. Whereas in fact, Markdown was not the first lightweight markup language, and is not the only one, and isn’t even the LML unquestionably closest to plaintext email conventions (reStructuredText is an obvious contender; overall, I’d consider reStructuredText a little closer than Markdown, but it’s subjective).
Perhaps my intent would be more clearly expressed by inverting it: email formatting has nothing to do with Markdown.
Yeah, that's what I feel gives markdown an edge over nearly anything else; markdown is adopting conventions that were meant to be readable without any kind of rendering. I can very easily tell what my markdown document is going to look like before I render it with Pandoc, because it's basically just taking stuff people were using with plain text that was meant to be read directly anyway.
I haven't used rST, but looking at the examples it looks considerably less readable out of the box.
* one
* two
* buckle my shoe
| inspiring quote
| - some famous guy
foo
a kind of bar
bar
part of a foo
:red: stop
:yellow: speed up
:green: go
- code:: python
def fun():
pass
Go here_ for more info.
- :: here: https://google.com
My **strong** text is well *emphasized*. Very ``literally``.
This is my main problem with the article, as this is decidedly incorrect.
Markdown was designed as a tool of conversion of de facto standard of formatting text in email messages and Usenet posts of early nineties. The basic 7-bit ASCII nature of those technologies inspired people to informally annotate the text with special signs to denote formatting like emphasis, section titles and the like.
True, HTML shares a lot of similarities with that nameless standard, so John Gruber in 2004 wrote a basic script [0] to convert the latter to the former, never expecting it to become such a universally used actual standard.
[0] https://daringfireball.net/projects/markdown/