Why is Markdown widespread? – Russell Beattie’s Notes

Wednesday, October 26, 2022 at 11:59 PM

I actually detest Markdown. Actually. However given the widespread use of Markdown, it may appear unusual that I’ve such aversion to it. In the event you by some means actually prefer it, or are so used to it by now, you could be tempted to assume I am the oddball. However I am positively not alone in my dislike of the format:

You get the concept. My level is, I am not the one one.

First the nice…

Markdown positively has some advantages, in any other case individuals would not use it. Off the highest of my head:

1. It separates the design of a doc from its content material, permitting writers to deal with what they’re writing.
2. The plain-text nature implies that .md docs are light-weight and moveable throughout platforms.
3. The easy variety of formatting guidelines is well pulled into any publishing system and styled as wanted.
4. It appeals to techies -Markdown’s precept customers – who wish to use vim or emacs to put in writing up documentation and notes (or say they do, anyhow).
5. It’s developer-friendly. Like code, it’s in plain-text so is usable inside an IDE and straightforward to repeat/paste chunks of code into documentation.
6. It incorporates 95% of the performance that most individuals have to create a doc.
7. It’s extensible: In the event you want further content material in your doc – like a video, or additional formatting choices – these can simply be added with HTML tags or customized textual content markers that may be post-processed.
8. As a result of it’s plain-text, it might simply be diffed and managed by way of git.
   
9. Parsing might be as simple as actually 10 strains of RegEx. 
10. Broadly supported at this level, with numerous libraries, tasks and editors.
11. Meta-data might be thrown right into a YAML frontmatter part on the high.
12. It’s the one choice accessible, actually, as how else are you going to put in writing paperwork?

So simply suck it up and use Markdown

As a result of, as identified by others earlier than me, Markdown sucks. Let me record some the reason why: 

1. It’s barely a spec – only a cobbled collectively bunch of normal guidelines which each and every implementation breaks in a technique or one other.
2. There are no less than a dozen variations, GFM being the commonest, but in addition MultiMarkdown, Pandoc, CommonMark, and so on. And site-specific variations resembling Wikimedia, Reddit, WordPress and extra.
3. Every variation produces completely different default HTML output.
4. The HTML output is antiquated at greatest. Although the fundamental construction of headers and paragraphs is usually semantic, there is no trendy semantic parts resembling important, article, part, nav, header, footer, determine, image, and so on. Embedding movies, social media widgets, and so on. is not attainable in any respect. 
5. Including in any type of additional meta information often requires utilizing YAML, the foundations of that are a thriller to me. 
6. With the intention to be actually helpful, Markdown must be post-processed (so the textual content can be utilized for weblog posts, analysis papers or on-line docs, for instance) and must be prolonged by way of embedded HTML or customized tags. For instance, Markdoc provides in tags for put up processing, Hugo provides in templates for weblog posts, and so on. And the nightmare which is MDX is… simply… wow. Not even as soon as.
7. Components of MarkDown are actually atrocious, even in case you love the final simplicity of it:
   1. Tables: The rationale you don’t see many tables in Markdown is as a result of they’re ludicrous. It is advisable to use a WYSIWYG device otherwise you don’t use it.
   2. Picture: hyperlinks are arduous to inform
   3. Blockquotes. Are individuals actually typing > earlier than every paragraph? No, they’re utilizing an editor.
   4. Numbered lists. Once more, it’s essential to use an editor to remain sane.
   5. What the hell are activity lists anyhow? Why do they exist?
8. The above implies that anybody who writes Markdown repeatedly utilizing a WYSIWYG editor or an IDE already, so the entire ‘plain textual content’ factor doesn’t matter. Why not use a format that is not fully hamstrung?
9. The markup is brittle as hell finally ends up inflicting bizarre edge circumstances, difficult even the most effective parsers. (###**that is __test__** … Is that daring with italics? Italic daring? In a heading? Wait…)
10. The libraries for manipulating Markdown appear to be both RegEx based mostly, or in any other case use an Summary Syntax Tree. In the event you haven’t tried manipulating a doc utilizing an AST, let me guarantee you it is a non-trivial effort. The APIs are both so low-level as to make any change a 50 line script, or they find yourself utilizing a badly made model of the usual DOM API. I spent a number of hours making an attempt to persuade one library to easily wrap a component with one other earlier than lastly giving up, loading up JSDOM and doing it in 3 strains of code. 
    
11. Markdown won’t ever get past builders. It’s a approach for people who find themselves used to writing code to put in writing docs with out being bothered about the way it appears to be like. However the reality is that the output needs to be readable and first rate trying.
12. Any developer who does care about how the output appears to be like – say for somebody making an attempt to arrange a brand new weblog or documentation – both spends hours making an attempt to determine varied libraries or offers up and makes use of an present undertaking with combined outcomes. 
13. Goddamn it’s fugly. That is final, however actually, that is my primary gripe. It’s 2022, we shouldn’t be utilizing ascii-text to put in writing paperwork.

OK, so use one thing else…

Like what? Plain textual content would not present wealthy textual content. And the usual apps for creating paperwork are neither easy, open nor customary.

1. Phrase processors are typically bloated, non-standard, self-contained functions which have file codecs that aren’t suited to post-processing, or creating internet pages. They’re barely usable for creating usable paperwork at this level.
2. Google Docs would not even have a doc format. It is all on-line or exported in several codecs – all besides .docx are read-only. In the event you do not feel like storing your docs on Google’s servers, you are out of luck. 
3. Phrase processors and editors that assist HTML exporting – from TextEdit or WordPad to Google Docs and Microsoft Phrase – create HTML that’s non-standard, bloated, and ugly. Each has their very own methods of formatting. This is not that shocking, given there is no customary HTML Doc format, and given the online’s flexibility, which means there are dozens of the way to format a web page. Daring textual content might be <b> or <robust> or a <span model=”font-weight:daring”> or <span class=”daring”>, and all are used repeatedly.
4. The HTML “internet design” apps that do exist – and there aren’t many left – are centered on website design. They are not a device for use for writing, however for format of already created content material.
5. HTML doc editors – aka phrase processors – centered on writing and sharing docs don’t exist. (Till now.)
   

Because of this if you wish to write a doc in HTML as simply as you create a Google or Phrase Doc, you’re out of luck. It is not that phrase processors at all times create horrible output – Google Docs does an honest job of exporting an online web page as an .html or zip file – nevertheless it’s at all times a one-way course of. Good luck importing that again into the editor or Phrase or the rest. And once more, every has its personal customized approach of implementing every model. Oh, and the exported internet web page inevitably doesn’t truly look precisely just like the doc you had been simply modifying – margins and spacing are off, and so on.

Why don’t we’ve an HTML-based wealthy textual content customary but?

I’ve zero concept. In truth, we appear to be getting farther away from one as Markdown reputation surges. 

The opposite day I learn a weblog put up by the oldsters at Mozilla – who’re speculated to be the usual bearers of, um, internet requirements, and was actually shocked that they determined to transform all their documentation to Markdown final 12 months. What?? In truth, they stopped utilizing HTML in an effort to do it. 

The weblog posts begins out by saying that the explanation was as a result of Markdown is “far more approachable and friendlier” then proceeds to record the varied Mozilla-specific Github tasks that one must obtain and set up (not together with Node, Yarn and Git), and the a number of steps wanted to really generate the docs. Once more… what??

And naturally, Mozilla too has its personal variant of Markdown, which builds on GFM. And naturally, since Markdown would not do a lot moreover headers, paragraphs, daring, italics and bullets, they want customized macro tags to make it do what they want. Which is after all each non-standard, in addition to being fully invisible to the author, so who is aware of what the top outcome might be: 

I imply, kill me now. If Mozilla, of all organizations, have dumped HTML in favor of Markdown and think about the above higher than, you already know, <span class=”foo”>, then I should be tilting at windmills. I get it.

That does not imply I am flawed.

As I wrote in my earlier put up, we’d like an HTML Doc customary. It is not a matter of expertise at this level, it is a matter of merely deciding on a manageable subset of HTML and CSS after which calling it a normal. Then it must in-built to each browser on the planet. I am utilizing my very own Hypertext HTML Doc editor to put in writing this, however I should not have wanted to undergo the hassle. Mozilla ought to actually be ashamed of itself for not doing it first, fairly actually. There’s a W3C Working Group devoted to Net Modifying, however they’re simply centered on a number of APIs it appears, mainly persevering with the deal with “internet apps”. The ePub Working Group is simply centered on read-only e-books, and are not involved in any respect about doing something to allow truly writing them utilizing internet requirements. 

My subsequent put up might be in regards to the three decade lengthy quagmire of “encapsulated HTML” codecs which might be on the market, because it’s an attention-grabbing subject of dead-ends and disagreements between browser makers. Then after that I will be posting on a proposal for what an HTML Doc spec would appear to be. 

-Russ