Why is Markdown fashionable? – Russell Beattie’s Notes

Wednesday, October 26, 2022 at 11:59 PM

I actually detest Markdown. Really. However given the widespread use of Markdown, it might sound unusual that I’ve such aversion to it. In the event you someway 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 thought. My level is, I am not the one one.

First the great…

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 concentrate on what they’re writing.
2. The plain-text nature signifies that .md docs are light-weight and moveable throughout platforms.
3. The straightforward 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, in any case).
5. It’s developer-friendly. Like code, it’s in plain-text so is usable inside an IDE and simple to repeat/paste chunks of code into documentation.
6. It comprises 95% of the performance that most individuals have to create a doc.
7. It’s extensible: In the event you want extra content material in your doc – like a video, or further 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 probably simply be diffed and managed by way of git.
   
9. Parsing will be as simple as actually 10 strains of RegEx. 
10. Extensively supported at this level, with a lot of libraries, tasks and editors.
11. Meta-data will be thrown right into a YAML frontmatter part on the high.
12. It’s the one possibility obtainable, 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 checklist some the explanation why: 

1. It’s barely a spec – only a cobbled collectively bunch of common guidelines which each implementation breaks in a method or one other.
2. There are at the very least a dozen variations, GFM being the commonest, but additionally MultiMarkdown, Pandoc, CommonMark, and so on. And site-specific variations similar to Wikimedia, Reddit, WordPress and extra.
3. Every variation produces completely different default HTML output.
4. The HTML output is antiquated at finest. Although the fundamental construction of headers and paragraphs is mostly semantic, there is not any trendy semantic components similar to most 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 kind of further meta knowledge often requires utilizing YAML, the principles of that are a thriller to me. 
6. In an effort to be really 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 publish 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. Elements of MarkDown are really atrocious, even for those who 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 use a WYSIWYG device otherwise you don’t use it.
   2. Picture: hyperlinks are onerous to inform
   3. Blockquotes. Are individuals actually typing > earlier than every paragraph? No, they’re utilizing an editor.
   4. Numbered lists. Once more, you’ll want to use an editor to remain sane.
   5. What the hell are job lists in any case? Why do they exist?
8. The above signifies that anybody who writes Markdown usually 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 utterly hamstrung?
9. The markup is brittle as hell finally ends up inflicting bizarre edge instances, 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 manner for people who find themselves used to writing code to put in writing docs with out being bothered about the way it appears. However the truth is that the output must be readable and respectable wanting.
12. Any developer who does care about how the output appears – say for somebody making an attempt to arrange a brand new weblog or documentation – both spends hours making an attempt to determine numerous libraries or offers up and makes use of an current mission with combined outcomes. 
13. Goddamn it’s fugly. That is final, however truthfully, 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 does not present wealthy textual content. And the usual apps for creating paperwork are neither easy, open nor normal.

1. Phrase processors are typically bloated, non-standard, self-contained functions which have file codecs that aren’t suited to post-processing, or creating net pages. They’re barely usable for creating usable paperwork at this level.
2. Google Docs does not even have a doc format. It is all on-line or exported in numerous 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 not any normal HTML Doc format, and given the net’s flexibility, meaning there are dozens of the way to format a web page. Daring textual content could possibly be <b> or <sturdy> or a <span model=”font-weight:daring”> or <span class=”daring”>, and all are used usually.
4. The HTML “net design” apps that do exist – and there aren’t many left – are targeted on website design. They are not a device for use for writing, however for structure of already created content material.
5. HTML doc editors – aka phrase processors – targeted on writing and sharing docs don’t exist. (Till now.)
   

Which means 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 internet 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 anything. And once more, every has its personal customized manner of implementing every model. Oh, and the exported net web page inevitably doesn’t truly look precisely just like the doc you have been simply enhancing – margins and spacing are off, and so on.

Why don’t we have now an HTML-based wealthy textual content normal but?

I’ve zero thought. Actually, we appear to be getting farther away from one as Markdown recognition surges. 

The opposite day I learn a weblog publish by the oldsters at Mozilla – who’re presupposed to be the usual bearers of, um, net requirements, and was really shocked that they determined to transform all their documentation to Markdown final 12 months. What?? Actually, they stopped utilizing HTML with the intention to do it. 

The weblog posts begins out by saying that the rationale was as a result of Markdown is “rather more approachable and friendlier” then proceeds to checklist 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 does not do a lot apart from 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 utterly invisible to the author, so who is aware of what the tip end result shall 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 understand, <span class=”foo”>, then I have to be tilting at windmills. I get it.

That does not imply I am incorrect.

As I wrote in my earlier publish, we’d like an HTML Doc normal. 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 regular. Then it must inbuilt 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 truthfully. There’s a W3C Working Group devoted to Net Enhancing, however they’re simply targeted on a couple of APIs it appears, principally persevering with the concentrate on “net apps”. The ePub Working Group is barely targeted on read-only e-books, and aren’t involved in any respect about doing something to allow truly writing them utilizing net requirements. 

My subsequent publish shall be in regards to the three decade lengthy quagmire of “encapsulated HTML” codecs which might be on the market, because it’s an fascinating matter 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