Which is fitting. It evolved long before the term 'markdown' itself existed, a practice having been used in email and usenet and BBSes for many years before. The 'spec' is just trying to codify the already-existing usage, which evolved organically in many different areas by many different people.
>You need to use a WYSIWYG tool or you don’t use it.
No, no you absolutely don't. Almost no one uses a WYSIWYG for markdown. That would completely negate the point.
>anyone who writes Markdown regularly using a WYSIWYG editor or an IDE already, so the whole ‘plain text’ thing doesn’t matter.
Probably 99% wrong. I've never met anyone that chose to make things more difficult for themselves by using a clunky WYSIWYG instead of just typing the markdown in a text editor. Sometimes that's an IDE, but that's beside the point. Plain text does matter.
>Markdown will never get beyond developers.
Gonna have to go way back in time and alter history in order to change that. Like, before HTML or the web. It was used by everyone, certainly not just developers.
I thought this must've been written by someone very young who never even saw the internet or tech until a few years ago. Yet the author claims to have become a programmer in the mid-1990s and somehow still doesn't understand the concept of plain text or how the internet developed, and how markdown came about - that is a little baffling.
My brother wrote his master thesis in LaTex. Being a non-techie (he's an archeologist) I had to do all the 'fixing'.
We switched to LaTex after both Word and OpenOffice Writer made working with the document a non-option.
I also used git to manage changes.
This was 2009.
He could not have done it without my help with this setup. But he could also not have done it without me in Word/Writer because these apps just behave 'funny' once you reach certain complexity in your document.
Fast forward to today.
My partner is writing her PhD thesis (she's an anthropologist and hates anything that has a keyboard).
Not in LaTex but in Markdown.
It lives in a GitHub repo. She is using VSCode with some extension that translates Markdown to LaTex and then to PDF so she can have a preview (inside VSCode no less) any time.
It took me half a day to research the options, settle on that one and to set it up on her laptop (she could have never done that still though).
I spent about two hours to teach her the workflows after.
Thanks to VSCode's built-in git support she manages that also from within the app. Including branches and merges.
After the initial two hours she never needed any help from me.
I think there is a business opportunity here.
Particular people in the humanities seem to dread writing stuff for one because modern word processors are just monstrous and instable as f*ck once you reach a certain document size/complexity.
I think you if you use something like pandoc it allows to at markups for centering and citation refs, which I'm guessing was used for .md => .tex to .pdf. But they will be rendered plain text in makrdown preview
MD => .tex to .pdf works with citations, but when I last used it I still had to write the tables in pure latex. With any even vaguely complex figures or subfigures, I had to resort to latex. The bulk of the text could be in MD, but I had to write non-trivial portions in latex.
- It is a what you see is what you mean editor
- It supports some markdown annotations to support your writing flow
- it exports in LaTeX, Markdown
- It creates a PDF based on LaTeX and allows to choose a template with some configurations
I was using md for nearly all of my works in college. But beyond that, something complex like PhD thesis I cannot even imagine the workflow. Really interested to know more details.
When she is unsure about a re-structuring of part of the thesis she makes a branch. It happened twice so far.
Same reasoning for branching when your are single author of a repo. containing code, I guess. A major refactor or structural code change or trying sth. "crazy".
My partner wrote her Social Science dissertation in LaTeX and also used branches. They are particularly helpful when you hand out a version to others for feedback or proof reading while still working on the document yourself.
1. The article conflated lightweight markup languages as a class and Markdown in various places, and you’re making it worse by performing that conflation in different places.
Markdown was a specific invention which took parts of ancient customs (some from at least as far back as the typewriter era), but applied various other rules never before seen. It was absolutely not just a codification of already-existing usage. As probably the clearest demonstration of this: no one would ever have used  for images before Markdown. Interpret the remark “it’s barely a spec” in this light: it’s speaking of Markdown specifically.
2. The source quotation was talking about tables, not Markdown as a whole.
I make markdown tables by hand. Very simple ones. And simple is good.
Statements like “no one” are silly because they are easy to disprove and then get into “well maybe you do, but I don’t; therefore…”
There are lots of tables in markdown. I’m not sure how you definitively know if they are made by hand or cut and pasted from a helper tool.
Anyway, it’s a dumb argument to make. The beauty of markdown is that if you don’t understand something, just don’t use it. It’s not like there are many tables in blog posts or comments any way.
> Statements like “no one” are silly because they are easy to disprove and then get into “well maybe you do, but I don’t; therefore…”
You know exactly what the intended meaning is, because it’s a common idiom. For example, “nobody goes there anymore.” This is pseudopedantry just like intentionally misinterpreting phrases of the form “this or that” as nonexclusive disjunctions is. It can be used humorously, but taken seriously it’s just tiresome.
I do not think the post you are replying to, intended any sort of humor and I also think they made a correct and important point. I would have posted if they had not already done so.
> No, no you absolutely don't. Almost no one uses a WYSIWYG for markdown. That would completely negate the point.
> Probably 99% wrong. I've never met anyone that chose to make things more difficult for themselves by using a clunky WYSIWYG instead of just typing the markdown in a text editor. Sometimes that's an IDE, but that's beside the point. Plain text does matter.
You repeat this point but the trend of markdown apps is to this direction. Have you never met anyone who uses Obsidian? Bear? Ulysses? Even Notion is just markdown+, which is why it's one of the import/export options. And no, these apps do not defeat the point of using markdown.
Does slack even use markdown? It seems to me that it just uses some markdown-like sybtax as a shortcut for generating its rich text. Like Google Docs will start a list after -<Space>.
Ehhh there's "Markdown" and there's "markdown". Slack definitely has markdown, and any argument to the contrary is a "No True Scotsman" fallacy. I personally use hyperlink text, bullet lists, tt/bold/italics, quote blocks, pre blocks.
A few years ago, Slack was "plain text entry box for markdown"
In ~2019, it changed to "WYSIWYG with markdown converted to WYSIWYG as you type". If you type "Hello *world*" the * will disappear and the "world" will be bolded - and you can also get bold with Ctrl+B or pressing a 'bold' button or pasting bold rich text.
There's an option to disable it [1], so if your slack experience is different you might have WYSIWYG disabled.
And if you think markdown usually means *foo* producing italics, and **foo** for bold, all I can say is yes.
There's an option to post in markdown instead of WYSIWYG. The one and only reason I use Slack's WYSIWYG instead of markdown is because their markdown parser doesn't handle links. If they just fixed that, I could stop using their WYSIWYG and its atrocious handling of inline code blocks.
Because it’s still not Markdown, not by a long shot. https://api.slack.com/reference/surfaces/formatting#basics may call it “mrkdwn”, but it bears only a very superficial resemblance to Markdown—in significant chunks it’s closer to one or two other lightweight markup languages than to Markdown.
Have you tried recently? There was a period when I also had WYSIWYG enabled solely because markdown links weren't working for me, but that's been fixed (at least for me) for a while now.
I don't know all of your mentioned apps that well, but the ones I know just hide the markdown and provide shortcuts and buttons to insert it. I for one almost never use the shortcuts or syntax insertion buttons in Bear, instead writing like I would in notepad.exe and enjoying the clean looks. I guess one could call that kind of hybrid between WYSIWYG and plain text…
There is really little way of knowing who is actually using these apps vs who is just firing up an editor. Just because apps are being developed in this direction doesn't automatically mean they are becoming the norm. The fact they are leaning towards WYSIWYG makes sense to me when you try to think of other features you could have for editing Markdown that something that, say, Vim can't do... I cant really think of many
No, but there is fun ways to do it. when i used Latx a lot, i had an awk script that wrote the table in my file from a CSV. Also, now i think most data inspection tools (panda and mysql at least, probably others) spit their data in the terminal in markdown form, so its a cpy pasta anyway.
the only issue with markdown is image alignment. And to be honest, WYSIWYG editors are shit at this too. I'd rather not loose my time.
considering that the only option to format text in programs like discord is a "light" version of markdown I would say many younger folks have at least a basic understanding of how markdown works.
> I've never met anyone that chose to make things more difficult for themselves by using a clunky WYSIWYG instead of just typing the markdown in a text editor.
That's basically what Obsidian does. If you right click on the editor pane, you can select "edit mode" which makes it act move like VSCode (pure text with bolding/italics), but the default move is WYSIWYG
Ah, I see that now, Source Mode vs Live Preview. But either way you're not using a toolbar and mouse for basic formatting and it's not hiding invisible control codes from you as you edit like in a standard WYSIWYG editor. The sort of things that make Word documents so hard to edit.
Even in Live Preview mode, every character is visible when the cursor is in the area.
Slack has nothing to do with Markdown. The plain text that its text box turns into formatting bears no meaningful resemblance whatsoever (it’s more similar to some other lightweight markup languages, and really it’s just completely its own thing), and you mostly can’t interact with it in that format anyway. (See also https://api.slack.com/reference/surfaces/formatting.)
The page you linked says "This formatting is similar to Markdown markup" so it has something to do with it. Given paragraphs, quotes, lists, and code are interchangeable it is certainly regrettably that links, bold, and italic are different but *bold* vs **bold** is still a meaningful resemblance in my book.
Similarities: _…_ for italics, `…` for code, ```…``` for multiline code (… though this is an unofficial syntax not part of Markdown, though it’s very close to ubiquitous), <…> for delimiting URLs, a > prefix for quotes (which is the most common syntax by far, since it was established decades earlier in email), and entity-encoding of &, < and > for some reason (which, given that they don’t support any other entity-encoding, and don’t use the ampersand, and don’t support escaping any of the rest of the syntax, is all-round weird, like although they weren’t actually following Markdown anywhere else they decided to in this one place for some reason and made a total hash of it).
The only similarities that are not extremely common conventions independent of any specific lightweight markup language are triple-backtick code fences, and entity-encoding.
Differences: no paragraphs, line breaks are hard rather than soft breaks, *…* for bold (in Markdown that’s italics, and **…** or __…__ is bold), lists (apparently this syntax doesn’t actually support lists, driving home how this isn’t even Slack’s “normal” format—I’m not sure how lists are actually implemented, given that you can produce them in the web UI), links, strikethrough, emojification, and all the other stuff from Markdown that’s missing (including any other form of escaping or entity-encoding).
Seriously, the resemblance is very superficial. The name is the part that’s closest, by a considerable margin; not the actual language.
They say “similar to Markdown” because that’s the best-known lightweight markup language, so it’s the obvious reference point.
You're incorrect. They include buttons for generating some markdown and a separate preview option but at the end of the day, people are writing markdown. I feel pretty certain that most people who use either of those tools regularly eventually learn the syntax and just type it out because it's faster
The author is mixing up two different things: the concept of markdown (text with a little bit of light formatting mixed into it with easy-on-the-eye syntax) and the existing specification of Markdown-with-a-capital-M (and its flow on effects).
The concept is fine. The author may not want to manually write markdown, and may think that no one else wants to either, but they are wrong. It's very very useful to have a way to store formatted text without the horrors of full blown HTML. You can stick some markdown in a CMS database, render it on a webpage, and get the most common formatting: links, bullet points, bold. Great.
On the actual spec/implementation: yes, it's a complete disaster. Especially the way it is kind of mapped on to HTML, so you get weird things like writing "1. blah; \ 1. blah" makes a numbered list with a 1 and a 2.
But mixed in there, the author seems to have some weird assumptions that people are using Markdown primarily to write documentation, and this is somehow Markdown's fault. I genuinely don't understand this, or their point 13 "It’s 2022, we shouldn’t be using ascii-text to write documents."
Clearly we do need something like Markdown, but the existing attempts (including Mediawiki's "wikitext") all reveal that design a markdown syntax looks easy, but is actually extremely difficult to do well.
> On the actual spec/implementation: yes, it's a complete disaster. Especially the way it is kind of mapped on to HTML, so you get weird things like writing "1. blah; \ 1. blah" makes a numbered list with a 1 and a 2.
There is a trade off here though. When people sit down to write something that doesn't have weird edge cases they're not likely to end up with a lightweight markup like Markdown.
So simultaneously the spec may be a complete disaster and a contributing factor Markdown's success. Much like how the human brain is very bad at adding numbers together and has so far effortlessly out-competed alternative species that had brains that were great at numbers but not vision processing (being great at adding numbers is so useless for an animal I assume the skill never evolved, but imagine there was a creature somewhere with amazing additive powers for the sake of argument).
Having an unambiguous spec could theoretically be a disadvantage to adoption outside of a very carefully designed markup.
I've heard very similar arguments, for Perl, a couple of decades ago.
And yeah, it's not entirely wrong. Perl was useful, too.
But I desperately want the thing that is for markdown what modern JavaScript, Python and Go have become for Perl.
I want a markup language that supports the most basic things, looks reasonable on the eyes in un-rendered form (so we don't need terrible rich text editors everywhere), and is very friendly to being embedded in bigger documents of its own type or plaintext. It should be possible to have that with a proper, unambiguous (both for humans and for computers) spec.
reStructuredText met a lot of what you are looking for in that "modern" markup language, though reStructuredText doesn't have much of a life outside of the Python ecosystem still.
For their major gripe that point 13 is a pretty weak one. Text editors can present a Markdown document any way you want, and even a WYSIWYG editor is possible if you like that.
Besides, Markdown fully supports alternate character encodings, not just ASCII (that would make Markdown really obsolete). Most people surely use UTF-8 for Markdown documents.
> Clearly we do need something like Markdown, but the existing attempts (including Mediawiki's "wikitext") all reveal that design a markdown syntax looks easy, but is actually extremely difficult to do well.
Related to that, there's also an obvious "network effect" at play here. Every Mediawiki uses "wikitext" so to use Mediawiki you learn "wikitext". As a user you don't want to have to learn more than one of these syntaxes so you use whatever is most common. I think that's the tautological answer to headlining question "Why Is Markdown Popular?" network effects, specifically "Markdown is increasingly popular because Markdown is already popular". It's used in enough places and has to be learned by enough people that generally people learn Markdown. Once they've learned Markdown they expect to use it everywhere else (and so Markdown spreads).
(I had a time where I preferred reStructuredText and its increased power and capability and internal consistency over Markdown. At this point because of network effects, I've decided to just focus on Markdown like "everyone else", though.)
I came to the same conclusion years ago and made myself and "alternate" markdown-like format that superficially looks the same, but has a grammar compatible with parser generators like ANTLR.
Took me about a week to produce something that could generate a nice document object model, and spit out HTML (or anything you please).
The concept is powerful. The specific Markdown implementation however is too messy for proper tooling.
No, it is specifically markup which tries to be nice to read even unrendered. Reading HTML source code is rarely nice and that is also a form of markup language.
This wikipedia page includes reference to WhatsApp... Should it?
I understand that you can use bold, italic, underline, but that is where the comparison ends - the answer to Features is "No" in the comparison table versus others. Not all other comparisons include it.
It's almost as if someone shoe-horned it in for greater visibility. "Hey look at our app, it's better than competitors because it's listed here!" Yet it's competitors offer the same or more.
The article actually fails to answer the question in the title. It's a long list of reasons the author believes it should not be popular. But it clearly is massively popular. So maybe there's something wrong with his line of reasoning?
Anyway, Markdown emerged out of the Ruby community. So it's not strange that there is no specification. Ruby is a dynamically typed language so, ruby programmers tend to not specify a lot of things like types or schemas. And indeed the Ruby language it self is a bit under-specified. The spec is simply "whatever ruby does is what it does", which sucks for alternate implementations like JRuby. The same is true for Markdown. Whatever the original markdown library does was the spec. And it has since been loosely implemented by others doing their own Markdown derivatives. Like the widely used Github flavor. Which is also a ruby based implementation, I think. So it is similarly under specified.
However, the lack of a specification is not much of an issue since markdown is used by humans to be turned into something human readable with some html formatting. Either it's readable or you fix it. And it's simple enough that any markup typos in markdown are usually not that big of a deal. The main goal of Markdown is to get out of the user's way so they can focus on content rather than formatting.
As for editors. There are plenty of editors that support markdown. Many of them even have live previews. So, it's great for that.
In my experience it works pretty well for non-developers. I added it to our email client years ago as an alternative to the WYSIWYG editor, and quite a few non-developers liked and used it. Also see Reddit, which uses it. While the Reddit userbase does skew somewhat towards the tech-y, there's also loads of non-tech folks on there.
As for the larger point: do I have a great love of Markdown? Not really; I think some of the other similar formats are better. But it works "well enough", and switching syntaxes is hard so I "just use Markdown" . I hate the "GitHub flavoured Markdown" with a passion though; the way it deals with newlines is just fundamentally broken and it's inconsistent even on GitHub where some things are GFM and some things are not (which they need to be, because GFM is fundamentally broken) leading to sillyness like copy/pasting text from one part of GitHub to another part ending up with badly formatted text.
Either way, whatever the faults of Markdown may be, I sure as hell prefer it over any HTML subset. Writing <i>emphasis</i> is just too distracting compared to *emphasis*; there's few things I dislike more than having to focus on the presentation as I'm writing something.
In every company there will be a few who just can't grasp Markdown, but they can't grasp any markup language, and struggle in WYSIWYG editors (like Microsoft Word, LibreOffice Writer, or Google Docs) too (usually not grasping the concept of the document outline created by applying header styles correctly).
The best option there is to simply help them and correct their output (again and again); there is no technological silver bullet to solve it.
Newlines in Markdown are pretty weirdly implemented, certainly! The canonical markup seems to be to make paragraphs by having two newlines (which all tools do), and to have an actual newline within a paragraph by ending the preceding sentence with two spaces and a newline. I'd love it if all tools did that, but an argument raised on the issue tracker of one of these (CodiMD) was that moving to the correct behaviour would break many existing documents where people had gotten used to lines breaking at the presence of just a single newline.
It's always going to be hard to settle on a solution that works for everyone; I also struggle with things like Google Docs. But if people struggle with Markdown and word processors ... yeah, I don't know what else can be done.
> an argument raised on the issue tracker of one of these (CodiMD) was that moving to the correct behaviour would break many existing documents where people had gotten used to lines breaking at the presence of just a single newline.
Yeah, I don't expect the current situation to be resolved any time soon.
> Writing <i>emphasis</i> is just too distracting compared to *emphasis*;
The big thing for me is that Markdown is not just quick to touch-type but also is easy to read in plain text documents. I can easily infer what the formatting means when reading Markdown even without learning it.
I'd be happy with another plain text ASCII format but Mardown just happens to be the one that's been widely adopted.
Being able to keep documents in the same version control system as your code is also a useful tool IMHO. I hate it when management insists on keeping documentation in something like Confluence. If checkout an old version of the code I want a matching old version of the documentation from that time.
> The big thing for me is that Markdown is not just quick to touch-type but also is easy to read in plain text documents. I can easily infer what the formatting means when reading Markdown even without learning it.
And this is the whole point of markdown. It’s for the source version to accurately represent what the output document would show. So emphasis isn’t just a tag. It’s represented by surrounding text with *s, which shows emphasis even in the source document.
A URL is easy once you understand that you read the stuff in the [] and mentally ignore the stuff in ().
The point of markdown is not to transform it into HTML. The point of Markdown is to be able to write a plain text document which is sufficient on its own. The fact that it can be transformed into an HTML output is a bonus (although a planned one).
In a sense this idea is conveyed in the name itself. It’s the opposite of markup, in that the markup symbols aren’t intended to be separate from the content but are part of the content itself.
> Being able to keep documents in the same version control system as your code is also a useful tool IMHO. I hate it when management insists on keeping documentation in something like Confluence. If checkout an old version of the code I want a matching old version of the documentation from that time.
I'm a big fan of this as well; another huge upshot is that you can write the documentation at the same time as the code and bring it along during the code review.
I agree and have had success teaching job-devs to use and even create markdown files for project documentation and stuff like that.
It’s also frequently coupled with “learning git” and I’ve found it helpful in governance processes where someone needs to approve or make sight revisions to something before approval. It’s better than signing word documents and emailing them around.
> While the Reddit userbase does skew somewhat towards the tech-y, there's also loads of non-tech folks on there.
Every time someone tries to do a list (eg cooking recipes) they fail hard, because both the need to have a two newlines for a one newline and a unnumbered list for a numbered list is thing which surely is out of knowledge of Average Joe. Even consulting a help doesn't help sometimes.
"New" Reddit solved it by having a WYSIWYG editor, but even then things get out of hand sometimes.
All complaints basically seem to boil down to these two:
* It's not standardised
* I don't like using it
I think the two big advantages of markdown are simply:
* It's readable without having to parse it
* A lot of people do like using it
Replacing it with HTML, as useful as HTML is for its intended purpose, sounds like an incredibly bad idea. There's a very good reason why markdown won: its readability. Except for tables, but that's why people don't use them. It's not meant to be suitable for every conceivable purpose, it's meant to be readable.
Using a rich text editor for it sounds like a bad idea to me, because you don't know what the raw text is going to look like. And yes, I do type > for blockquotes. It's not very hard to do.
Should we have a single standard for markdown? The lack of one seems to be the primary disadvantage of markdown, but personally I'm not sure it really needs a standard. It's pretty simple and I don't think it really needs to be portable. But it would certainly be nice to have a standard.
Use of block quotes is rare anyway. It's just very practical, easy to adjust, its output fairly well matches your expectation. It covers 99% of your everyday needs.
> Adding in any sort of extra meta data usually requires using YAML, the rules of which are a mystery to me.
That's not the fault of Markdown and not part of Markdown at all. Markdown doesn't say anything about metadata. Use of YAML at the top of Markdown documents was invented elsewhere (Jekyll, I believe), and any tools can use whatever they like.
> Numbered lists. Again, you need to use an editor to stay sane.
Or you can just type 1. in front of every line and let the Markdown renderer take care of numbering.
> What the hell are task lists anyways? Why do they exist?
Again, not a standard Markdown feature. They are a GitHub invention for adding checkboxes to issues and tracking the progress of things. They're convenient for places like GitHub, but if you're writing some documentation, you can just ignore them.
> The HTML output is antiquated at best. Though the basic structure of headers and paragraphs is generally semantic, there's no modern semantic elements such as main, article, section, nav, header, footer, figure, picture, etc.
YAGNI. And many of those would not necessarily be part of the Markdown document - in a blog, the <article> would be outside of Markdown and instead part of the main template (which is by necessity HTMLish).
> Embedding videos, social media widgets, etc. isn't possible at all.
Why not? I can just copy-paste the embed widget from YouTube and paste it in my Markdown. The (Gruber) spec allows HTML inside Markdown. A thing that knows how to turn a link to the social-media-site-du-jour into a nice widget is outside the scope of a simple markup language (it would need a large database and constant updates).
Just get into copy pasting stuff from word to some browser rich text field - people will expect it works flawlessly but I know it will break in dozen different ways.
Problem is not with markdown - problem is with rich text in general.
Markdown is useful as it limits the options to make stuff easier. Argument that you need post process it to be useful is not that good - because that is the point of markdown you have "raw" data that is easy to post process any way you want. If you need some really fancy embeds and changes then maybe it is just not the right tool?
I don't use tables in markdown (besides maybe 3-rows 3-columns) but if you need more you probably should just stick with word/excel. I don't see a way to make tables in ASCII/UTF that would not suck.
It's almost like we need some kind of lightweight markup language like HTML that lets us focus more on the content, with less boilerplate... so something like markdown in other words, then?
I don't think the problems Russel mentions are as big of a deal. I've never encountered an issue due to the inconsistent spec. The basic markdown practices are so simple they just work, and when they don't it's clear you need to make a slight adjustment. At worst you are missing something you want to use that's not available in the flavor at hand. In the places I commonly write markdown there is no need for a complex tool-chain to render it as HTML, it's either a real-time part of the apps I use, or I consume it as plain text.
I'd be curious how Mozilla is finding it. I know it's a favorite among bloggers, but I'm not sure about such rich documentation as MDM, the quality of which has never been better in my view.
I think we need to invent new ways to store and retrieve enriched/inter-related/hierarchical data in a way that's convenient, interoperable and ubiquitous. I can't think of any though, can you? Something like a relational database, but lightweight like plain text, but richer, like a website.
I think the author is missing a fairly major point, that Markdown was intended to be a way to process text written the way people already wrote it.
ASCII is absolutely the best way to write documents, if you're working in a primarily ASCII environment. Crabbit old bastards like me who remember the dialup BBS days consider Markdown-like text to be standard - underline things with a row of hyphens, mark a heading by underlining with # symbols or = symbols depending on how "strong" you want the heading to be, emphasis words with *asterisks like this* and italicise with /slashes like this/ (okay they got that one a bit wrong but still the point stands). Make a bulleted list by indenting a bit and putting a * at the start of the line, and so on.
Before Markdown-the-specification and set of libraries to transform text to HTML existed, there were already a wealth of documents in somewhat Markdown-like syntax. Being able to transform them into something that "kids these days" with their high-resolution 800x600 pixel bitmap displays can view in a cool font came long after.
There's nothing stopping you forking a project like Github did and making a Jrib-Flavoured-Markdown parser. I'd use it, just to get the italics and bold right.
The author clearly doesn't understand the appeal of it.
Some of the points don't make sense. For example, he says it separates the design from the content. Er, no, it doesn't. It puts the design in the content, but in a human readable and writable way, like an old type-written document.
The chief selling point of markdown for me is I can write simple, portable and usually short documents which can be easily read and edited in a text editor, and that you can put under version control. And you can transform it into other rich text formats if you want a pretty document too. In that sense, it's a bit like LaTex, but not as hard to understand or use.
I would agree that the lack of standardisation is a problem, and that doing complicated things in it starts losing the benefit. But for simple documents it's just great.
Edit: I guess it does separate the design from the content, if you mean things like choosing what fonts to use when transforming it into a different rich text format. I was erroneously thinking he meant the structure of the document.
I'm always having to look up the link format for reddit, and I always seem to get it backwards one-way-or-another first try. That's where markdown breaks down, at least for my uses. When you get beyond headings, lists, bold and italics, the complexity increases sharply.
Whereas HTML is reasonably consistent and simple in it's syntax, which grows from basics to complex structures.
<b>this is bold</b> is really not much different <a href="">This is a link</a> and the heirarchy of <table> <tr> <td>.
My mnemonic is that the parentheses are a following sidenote that can always be skipped by the reader in normal writing. The hyperlink to follow for more information is the parenthetical.
Then the brackets are literally bracketing the text that should be styled as a hyperlink.
You're appealing to the law of averages here; all things aren't necessarily equally easy to remember. There's no arbitrary order that has to be remembered with an anchor tag: all tags start with an angle bracket, what they are (if we include the "/" in the name), and a list of attributes, and are closed with another angle bracket. If some elements were opened with square brackets and closed with angle brackets, it would be harder to remember. It would be worse if there were also others that opened with angle brackets and closed with square brackets.
It will always be easier to remember a 10-letter name than a 10-digit number.
My sister, ex-chef curently a biology student at the uni, have no idea how to develop or how to fix her computer issues. She uses joplin, and edit her markdown notes through a text editor. She told me it took her 5 minutes to understand how to add images (and she still don't understand how the alignment works, but to be fair, only LateX is working well for this).
In fact, not using a WYSIWYG editor have an advantage if you're not a professionnal Word user: you don't loose time fiddling with the setting, selectionning texts, not getting why you should backspace twice here and once there (Fuck you Jira) and remove all "automagic".
I made a post about powershell yesterday and explained that to me, while PS was more pwerfull than bash (and easier), my lack of understanding and trust made me wary. Someone responded to me on a tangent on ExtJS: `it's a really good example of "simple vs. easy"`. This is the case here. Markdown is just simple (for the user).
I think my brother tried to taught her vim and build her a customized vim with markdown, surround, biology french dictionnaries[0] and a better autocomplete, but i don't think she uses it (because while it is easier, it is not simple. Hey, same thing!).
[0] I had no idea you could do this, but he made it so that if she was in the "marine biology" folder, she have a different dictionnary than if she is in the "microbiology" or "chemistry" folder. This made my LaTeX-fu even better than in was.
Hi,
It's said that the father of LISP, John McCarthy, lamented the W3C's choice of SGML as the basis for HTML : « An environment where the markup, styling and scripting is all s-expression based would be nice. »
“I don’t like popular thing. It sucks. There should be something better.”
Markdown is popular because it’s useful. It’s useful because it’s easy and free and portable.
I know html very well, I use markdown because it’s faster to take notes or make simple posts. Also I can teach someone in 5 minutes and they can be productive editing headers and bullets and text.
I'd like Markdown if things were non-arbitrary. Is asterisk or underline italics? Does the href go before or after the link text? And I have no idea what the format of lists is, I guess you just put "-" or "1." and it automatically recognizes it?
> Also I can teach someone in 5 minutes
I bet you can teach people the subset of HTML that includes the Markdown features in about five minutes, too.
Did the author just look past Slack, Reddit, Discord, Teams, and more? I am honestly lost how one could make such a statement when its already in so many places where the primary audience is non-developers. They even list Reddit in their own post, but still make this statement?!
I actually love using plain text to create documents, but I'm also bothered by the irregularity and non-extensibility of Markdown, which is why I created xidoc: https://xidoc.nim.town/
Let me commend you on this effort. I would definitely consider using it in a situation where markdown did not suffice. It does require nim and nimble to be installed but that doesn't bother me.
At least the installation is easy, unlike many projects written is other languages where you need to manually install a billion dependencies and edit some obscure configuration files :)
> The HTML output is antiquated at best. Though the basic structure of headers and paragraphs is generally semantic, there's no modern semantic elements such as main, article, section, nav, header, footer, figure, picture, etc. Embedding videos, social media widgets, etc. isn't possible at all.
While most other complaints sounded more like the typical markdown grumpiness I've heard before, I do find this an interesting argument. Why even have article, section, etc. if markdown ensures we're never going to use it? It's not like these are truly exotic tags that are complicated in their usage. Of course if you allow mixing html tags with markdown this is a bit of a non-problem in practice.
The point of Markdown isn't to replace HTML. It lets you write a plaintext document that can be post-processed into a rich text document (including HTML). It doesn't define the rich text template, styling, or anything else. It certainly isn't meant to have a 1:1 relationship with every HTML element.
With Markdown I can type up a document in the most brain dead of editors. I can then effectively read that document in the most brain dead of readers, event just printing it to a terminal. That simple document I can run through any number of post-processors and get great looking documents in a variety of delivery formats.
I agree that that is the "point of Markdown", but that is also not as relevant as how it is actually used.
It's one thing to use it as a better BB-code in chat programs, forums and on Github, as other comments mention. However, the article seems to be complaining about how it is used to write websites and articles even when patching the holes in Markdown end up being more of a hassle than just using HTML (that MDN screenshot looks horrible). That goes beyond the example you are talking about.
The other argument, that perhaps the issue with rich text formatting isn't the rich text formatting, but the fact that historically rich text formatting tools tended produce awful HTML, also sounds like there might be something to it (not sure if that's still true though). I cannot imagine that it would be that hard to produce minimal HTML that supports 90% of basic rich text needs one has, in a way that is perfectly compatible with any classless CSS framework you then decide to throw at the output.
> However, the article seems to be complaining about how it is used to write websites and articles even when patching the holes in Markdown end up being more of a hassle than just using HTML (that MDN screenshot looks horrible).
Anyone using Markdown for such things is using the wrong tool. That's not the fault of or a failing of Markdown. If someone can't differentiate between the improper use of a tool or failings of the tool maybe they need to not make sweeping statements.
Where Markdown is superior to simple HTML is it does not encourage the sort of nesting that makes HTML painful as a grammar to parse. The simpler grammar (blocks delineated with newlines) actually makes the semantic meaning of the markup easier to deal with so a processor can emit clearer HTML/LaTeX/whatever.
There seems to be some conflating going on here. As the author mentioned, the spec space is a scattered mess. For the same reason, all markdown to HTML compilers are following their own rules (unless they specifically call out the recommendations of one of the specs.) So if you are getting crappy HTML output, get (or write since it's so simple) a better compiler. Many markdown to HTML tools will let you apply templates and specify which tags to use for a given piece of markup. For the layperson that's probably asking a lot but for the technical crowd, it's your own fault if you aren't happy with the output
Most of the tags you mentioned should only have a single one in the document, generally speaking, so insert them yourself as part of the template. You could make an argument for wanting to have different <section>s which I figure could be built when you encounter a level 2 header or similar. If you want to create more complex documents, use HTML. Markdown isn't the right tool
Currently finishing my third (full-length academic) book in markdown. Wrote the second book in markdown too. Wrote the first book in MS word. Never going back.
Here's the thing. Word is a buggy bloated piece of shit application with an incomprehensible and ever-changing UI that requires 20 mouse clicks hunting through badly labeled menus to do anything. Latex is far too complicated for prose that doesn't have equations all in it, and is also unsupported by publishers outside of the sciences. Alternative word processors (OpenOffice, Pages, the desiccated shell of WordPerfect) are either buggy, ugly, unmaintained, lack critical features, or all of the above.
So I just write in markdown in emacs. Markdown mode in emacs works very well, I have hardly any customizations on top. One file per chapter. References in zotero, insert citations in better bibtex. Compile it all in pandoc.
When I want to revise I just concatenate the files and compile it to PDF and read my own work there. When I want to submit to a publisher I just compile it to word. I have a makefile that handles all of that for me. Then I make a few tiny tweaks in the garbage program and submit.
This is the best workflow I've ever found for academic writing, because pandoc-enhanced markdown and better bibtex enhanced zotero give you everything you really need for academic writing (like control over reference formats), and nothing you don't need (endless nightmarish word bloat). And you can just store it all in a GitHub repo.
Markdown is popular because it implements just enough features to be useful while not presenting a high threshold for "just writing things down". It exists because traditionally, people who design markup languages have not done a particularly good job in designing something that is suitable for adding a just enough structure to text to make it useful both as text and as rendered document.
(If you want to look at a particularly egregious example of hubris, arrogance and total lack of empathy for users and implementors alike, look at ISO 8879:1986. The cheapest way is probably to get hold of an annotated standard is probably by buying Goldfarb's SGML Handbook. Please burn after reading though - to keep it out of the hands of impressionable kids)
I had a long discussion about using HTML+CSS with one of the designers of CSS many moons ago, and sure, in theory we could have used that. But you need only do a "view source" on any web page you regularly visit to realize that it is anything but low threshold.
I think in order to make HTML a friendly document standard it needs to be easy to type on mobile. At least in my experience it is quite painful typing HMTL tags (needing to dance between 3 keyboards). This could be implemented with a built-in WYSIWYG style editor on mobile (maybe piggy-back on the contentEditable stuff?). I would love it if there was a standard native rich text widget for HTML.
On one of my sites (message board), I use Markdown but custom HTML tags for extensions like file attachments. You can allow these custom tags in your HTML sanitizer and replace them at render time with output from some template. So dragging and dropping a file would add <foo-file data-id="uuid-goes-here"> to your input box. Seems like a decent middle ground with common things easy to type with Markdown and special magic as HTML tags.
This is a great point. I've written a lot of stuff just using HTML, even doing the table formatting, by just opening up BBEdit and going to town. It's really easy once you learn the basics. There are (were?) a lot of secretaries who deeply loved WordPerfect because of the ability to open up the codes window so they could fix weird formatting errors. They're just a couple of steps from authoring directly in HTML if they so wanted.
But it didn't occur to me that a non-trivial amount of stuff is composed on somebody's phone. A WYSIWYG editor on mobile is certainly doable, but screen real estate is precious on a phone. Markdown certainly helps with that.
> There’s a lot of issues with this post, which basically completely misunderstands what markdown is, what its purpose is, and why it’s successful.
A lot of mystery issues that you are claiming but also not clarifying; at least the post attempts to make a case for something. I don't even know why you don't like Markdown's list markup. Give us a hint?
It's also amusing given that Microsoft teams has at least limited support for markdown. Depending on how you define a markdown user, it may be a that the majority of people typing markdown have never written a line of code but have discovered the convenience of markdown from being power users of Microsoft teams.
Slack and Discord have probably made more people into casual Markdown users who do not even know that they are using Markdown. When I told my wife Obsidian lets her keep notes using Markdown she was not convinced, once she tried her response was 'oh, it is just like one big Slack message window'.
While I agree with many of the points, the proposal that we need a a new standard based on HTML is a bit weird. I guess the author hasn't read the HTML5 spec which is a total monstrosity and suffers from problems similar to Markdown. If you want a document format where essentially every document is valid, you have to specify each and every corner case which gets messy very quickly. Just look at the HTML5 spec. To my knowledge, there isn't even a formal, unambigious Markdown spec. CommonMark comes closest, but it's still a mostly informal spec often based on examples. In my opinion, the best option is still XML, or better yet some slimmed down version without DTDs and with a saner solution for namespaces.
People are lazy by default, they prefer simplicity and convenience. HTML compared to markdown has better results, but is less convenient and more complex. That's all what is there.
I used to write notes in HTML and for example creating list in HTML is annoyingly slow and tedious process, while creating list in markdown is just writing one symbol. Done.
Then you will get to create inline code or block of code, suddenly you need to write span (or div) pointing on a CSS class where you will specify formatting of that inline code. So you need to link CSS file or have CSS code in header of your HTML file. In markdown you will just use one symbol (or three for code block). Done.
I wrote a 98,000+ word novel in Markdown. Pandoc renders it perfectly to Word. The text included a title page, epigraphs in italic, headers of various levels for parts, chapters, scenes. All I had to do in Word was make sure my paragraph styles were set up the way I wanted (and that Pandoc knew what they were supposed to look like), then run a macro to get rid of the cr/lfs between paragraphs.
I don't know if the novel was any good, but it looked good. Markdown was certainly adequate.
What I had more in mind was e.g. linking between different documents, images, tables, footnotes etc. I guess most of these are possible (depending on your Markdown flavor), but largely very awkward.
And on other hand tools suitable for more complex things are probably too much for one page documents. So it is really choosing right tool for right job.
Asciidoc was originally designed to be directly translatable into Docbook XML, and thus slot into a Docbook-based production system. So it covers a lot more ground than MD was originally intended to.
There's also rst, which was developed with documentation in mind.
If you want to write beautiful documents. Use something else, be it html+css, word, latex and so on.
But at the same time accept that these are potentially time consuming and complicated to do by hand or even with tools.
Markdown and likes are for the case of fast and minimal styling, while still being human readable and writable. Which is very reasonable trade-off. And I will take it every day.
Don't try to force something like tags for writing as that would be just horrid.
I can generate a LaTeX document from a Markdown document. Or an HTML document. Or a Word document. I'm not going to send or print Markdown, I'm going to generate some delivery format from it.
There are usually a few "models/reasons" to explain adoption.
These models/reasons (mentioned below) all have their own "threshold or critical values" depending on model-and-industry
1. Simplicity: (a.k.a accessibility) MD is def simpler than let say HTML.
I can teach someone MD in a day and they will be 'productive' in it for a wide variety of tasks. I can't teach someone HTML + CSS in a day AND be productive.
2. Price: If you are x5 cheaper than your competitor but provide lets say 0.7 of the feature set you probably going to win
(PS. X5 and 0.7 are the variables to be solved and not real numbers)
3. Better: If you are x10 better and let say only 2.5x more expensive you probably going to win as well.
4. Established-Network(audience): Good example is SQL or USB. Neither is really fantastic and there are certainly better and cheaper solutions out there. Yet it's hard to argue with something in tech that is "good-enough".
Would love to see some big-ass economic study of these and their critical values. Examples: VHS-BetaMax, WhatsApp-SMS-Blackberry, USB-XYZ etc.
Not really, it's because org-mode is completely almost unusable outside of Emacs. Unlike Markdown, it looks terrible as truly plain text. And Emacs, while great in so many ways, is is an esoteric paradigm (same with vim, but many of us are hooked on it anyway).
Ubiquitous keyboard layouts, text editing and markup paradigms are all due for a massive shake up, but agreed they have a lot to learn from the Emacs stuff.
Consumers should be able to control the presentation of the content they view. They should provide the theme. Markdown could provide the minimal content and linking.
It seems like it would be possible to remake all the major web properties this way while returning control back to the consumer and preventing egregious advertising, tracking, and popups. Reddit, Google Search, substack/medium/etc all could be remade in this more consumer-centric viewport. The markdown browser would be a strong promise a lot of anti-user behavior.
The modern browser is more an application development platform - let's treat it that way. A web browser's presentation should be in control of the consumer.
I think part of why it's popular is that it's a sexier implementation of HTML, and as a writer, I found it frustrating to hand in edits to editors (for news websites) in Word format. Being able to give people a plain text version of my article and have it translate anywhere was/is amazing, and it's much smoother to write "" or "*" than it is to put "<em>" or "<strong>".
I use Markdown a ton because it's easy to use converters to get that HTML code for blogs or have it built into plugins for Notepad++, Sublime or Atom.
Any author that writes "it's a matter of simply deciding on a manageable subset of HTML and CSS and then calling it a standard" with a straight face may not understand the meaning of many of those words.
Actual standardization (of the open web variety) is inherently hard.
Nobody (and I do mean not one person) agrees with anyone else on which subsets of HTML and CSS are necessary.
Heh. Author here. Not sure how I missed this since I'm on HN daily. Must have come and gone quick! I had no idea. I haven't seen this much rabid hysteria aimed at something I've written for a while! Nice. Given that I practically live here, it's not unexpected, but still... Wow.
> The HTML output is antiquated at best. Though the basic structure of headers and paragraphs is generally semantic, there's no modern semantic elements such as main, article, section, nav, header, footer, figure, picture, etc. Embedding videos, social media widgets, etc. isn't possible at all.
I don't think that's what Markdown is for.
I think Markdown is meant for the content that would appear inside the `article` tag. You're not meant to use it to create an entire website layout.
I chose markdown for a large project due to the reduce storage size and forced simplicity and abstraction.
I have to work with static data which will not change for 10 years, the only way to keep it alive is upcasting the internal structure and updating the conversion to html.
The project lives in a scientific environment but is used by a wide variety of people.
The project is now 5 years old and until next week there was no wysiwyg-editor (I'm currently working on it).
It's an electronic testing and examination environment for German universities.
It's very far from big data, but we have to support very small universities with very limited tech budget. We pre-generate and store the exams to ensure that we do not have any compatibility issues in the future (e.g. by changing minute elements of the randomisation).
The biggest database currently is about 700GB and I assume that we'll reach an equilibrium at around 2 TB.
In an article linked from this one, they advocate for, wait for it, yet another markup language (albeit a subset of html).
> What I would want is a simple .htmd standard file format, which - like all the "lightweight markup languages" out there - is just text containing a strict subset of HTML (no forms and iframes) and CSS which basically mimics the output of Markdown.
So, basically, they want Markdown with angle bracket. Yay? No. Yuk.
I've been keeping my personal notes as a folder of text files formatted with Markdown for 10+ years.
I honestly really don't like it in some ways. My work involves a ton of characters that trip up Markdown interpreters, and I end up having to escape them (brackets, asterisks)--and not all editors treat them, or the escape characters, the same way.
But nothing else fits my use case as well, so I've stuck with Markdown.
To me it comes down to one basic thing: I can create decent looking text content without using my mouse/trackpad or F-keys. It's about as easy to write as it could possibly be. Additionally, I don't have to worry about the editor inserting weird annoying-to-parse markup elements mid-text as I've seen in Word documents (in the docx XML).
My biggest attraction to Markdown has been avoiding ANY use of browser-based WYSIWYG editors.
Multiple times the author asserts that people will resort to a WYSIWYG tool for some Markdown formatting. I expect this is largely true, but I can't be the only one who has sworn off WYSIWYG in the browser but it ends being so frustrating.
HTML is not for writing but for creating UIs. That was why it was created anyway. Markdown was specifically created for writing. It has no other purpose.
Saying that Markdown is bad is really naive. There are not many ways to specify formatting without it getting in the way of your writing. Markdown is popular because it strikes the right balance where reading a markdown document requires a lot less visual strain compared to the same HTML document. It requires the least amount of letters to specify formatting - italics is 2 chars, bold is 4 chars, underline is 2 chars etc. Lists are mostly inferred and require no additional formatting. Compare that to HTML which requires 5+n chars (where n is the number of chars in the tag name) regardless of which format you want to use.
Markdown does have it's quirks but they don't come up 99% of the time unless finding them is specifically your intention. Knowing whether *__hello__* is bold italic or italic bold is not important unless you are writing a parser.
The downsides of Markdown are much, much less than the downsides of HTML. Writing is not the same as designing a website or a UI. It's not meant to be pretty and typesetting + styling should not be the concern of writers.
Html was absolutely created for writing, though it later got hijacked as a system for creating UI's inside of the browser doing the browser wars of the 90ies, but if you look at the original specs, it's a way of marking up documents and it was very much readable even without a rendering engine.
Prior to html and the web revolution people would use different macro packages for either troff or TeX and, and in the first years of HTML people would absolutely write it by hand thinking very little of it but then again that was before style elements css and javascript.
After the browser wars almost everyone who working with documentation had their own perl, or ruby scripts to take some simplified markdown syntax into html and there is of cause a risk of markdown itself getting bloated to the point where people need scripts to turn simple meta formats into correct markdown.
Nobody has anything to say to me about text formatting specifications when their blog has so little text contrast. I know, not the same issue, just pointing that out.
To expand on the hivemind, it was pushed by an Apple-sponsored tech blogger while Apple was continuing their push to market their laptops to frontend web developers. A bunch of Apple laptop developers then started embedding it although the spec had weird issues. The best substitute was Asciidoc, and it also made a few strange choices and is nearly too complex to justify using over HTML. So, with no good light alternative, Markdown won.
Which is fitting. It evolved long before the term 'markdown' itself existed, a practice having been used in email and usenet and BBSes for many years before. The 'spec' is just trying to codify the already-existing usage, which evolved organically in many different areas by many different people.
>You need to use a WYSIWYG tool or you don’t use it.
No, no you absolutely don't. Almost no one uses a WYSIWYG for markdown. That would completely negate the point.
>anyone who writes Markdown regularly using a WYSIWYG editor or an IDE already, so the whole ‘plain text’ thing doesn’t matter.
Probably 99% wrong. I've never met anyone that chose to make things more difficult for themselves by using a clunky WYSIWYG instead of just typing the markdown in a text editor. Sometimes that's an IDE, but that's beside the point. Plain text does matter.
>Markdown will never get beyond developers.
Gonna have to go way back in time and alter history in order to change that. Like, before HTML or the web. It was used by everyone, certainly not just developers.
I thought this must've been written by someone very young who never even saw the internet or tech until a few years ago. Yet the author claims to have become a programmer in the mid-1990s and somehow still doesn't understand the concept of plain text or how the internet developed, and how markdown came about - that is a little baffling.