Why are we still using Markdown?
bgslabs.org
bgslabs.org
We want to encourage people to produce written output with minimal friction. Barriers to writing--and especially barriers to producing documentation--should be minimized. Writing well is difficult enough!
Markup is overhead. Complex markup is even more overhead. Markdown is the best compromise we know of today that provides just enough structure and typographic capability, while imposing very little cognitive load on the author.
Besides, if you need something more complicated these days, you can have your favorite AI agent do it.
• I have to decide whether to use asterisks or underscores for bold and italic.
• I have to decide whether to use asterisks, hyphen-minuses, or plus signs for unordered lists.
• I have to remember all the various rules and edge cases about parsing.
In the worst case, the barrier to entry and exit are pretty low.
First you can switch from WYSIWYG to text editor instantly.
Then you have an outline where you can manipulate your “markdown blocks” [i.e title and its content] by drag n drop. Or extract a “markdown block” as a new note, and leave a reference where it originally was extracted from.
And then [the killing feature], it displays the content of a link, web link or internal link, as a [kind of] iframe, if you prepend a ! to the link.
I think it would be easier for me to appreciate your comment if you named some of these other languages. Markdown is the only standardized one I regularly come across that I type by hand, these days.
What are you contrasting to?
As for Markdown specifically- the only thing I regularly mix up is the syntax for links. I frequently reverse the [] and (). But that's just because I don't use it enough to have the muscle memory.
HTML? Also my markup language I created for myself, which is currently not published.
In email, I naturally write things like "...on the example website (www.example.com)..."
Markdown keeps those () in the same place, and just adds the [] so you can delimit the visible text: "...on the [example website](www.example.com)..."
I remember it as passing parameters to a function that requires an URL as an argument. Maybe it's not the most straightforward way, but it works for me
It's a good example of "pave the path" design philosophy, where you do what users are already doing rather than trying to impose some platonic ideal of what the world should be like. And it works quite well at that.
For those of you who weren't there:
*bold*
_underline_
~strikethrough~
/italics/
> Quotation
- list
- list
- list
Strikethrough and bold are doubled to avoid common ambiguities. Your underline should technically work, but it comes out as an <em> (emphasis) tag, which is rendered as italics in most browsers.
* I had to escape all of these asterisks.
** I see this happen fairly often to people's comments here.
The bullet point problem is fixed by only bolding when the asterisks are on either end of word characters.
This is just terrible UI, why do you need garbage marks when you already have bold? And you can edit "as normal" if you like, but that only requires displaying asterisks during that tiny % of time you edit the word, not all the time when you read it or edit something else.
But you're not editing that text! You're editing some other text and see a bunch of asterisks all over the place. And this is especially bad in nested styles - try some colored bold word in a table cell - without hiding the markup you'll basically lose most of visibility into the text/table layout
> to reduce ambiguity
it does the opposite, you can't easily distinguish between an asterisk and an asterisk, which is... ambiguity
> can't distinguish between adding more bold text to currently bold text or adding non-bold text immediately
Sure you can. In a well-designed editor you'll see the style indicator right near your caret is so it's always obvious whether and how your typed text is styled or not.
In a not-so-well-designed editor you'll get that indicator far away from your caret or just get asterisks appearing when you need them.
In a not-designed editor you'll see them all the time even when they don't serve any purpose.
This might be why I also liked LaTeX. The markup itself is semantic and meant to help me understand what I am editing. It isn't just some keyboard-shortcut to inject a styling command. It is part of the document structure.
Only for the 3 primitive styles that were supported? 3 table cells of RedBold GreenLowerCaps BlueUnderlineItalic isn't easy anymore
But also - there wasn't a single app in the 80s with a different easy approach, right? So removing noise had a downside.
> styling command. It is part of the document structure.
Not for the most used markdown markers, where styling = semantic.
But yeah, this tension you are describing is also where other concepts like "paragraph styles" bothered me in later editors. I think I want/expect "span styles" so it is always a container of characters with a semantic label, which I could then adjust later in the definitions.
Decades later, it still repulses me how the paragraph styles devolve into a bunch of undisciplined characters with custom styling when I have to work on shared documents. At some point, the only sane recourse is to strip all custom styling and then go back and selectively apply things like emphasis again, hoping you didn't miss any.
And... I preferred WordPerfect's separate "reveal codes" pane, which reduced the opportunity for ambiguity. WP 5.1 has never been equalled as a general-purpose word processor.
edit: HN automatically finds this example and puts in escapes to make it work. From elsewhere in the discussion I just want AsciiDoc.
https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
Or italics can be //double slash// to avoid ambiguities with file paths. That still leaves the windows style //some/file/path as ambiguous But I’ll never accept single * as natural for italics.
*bold* and _italic_ would have been better.
As for /slashes/, which would visually be perfect for italics, the only reason they conflict between italics and filepaths is the fact that in both cases they are expected to be used at the beginning and end of a word. Maybe using an unnatural placement of )parentheses( could have worked as a non-conflicting indicator of italics.
Markdown was created in an era before the web had easily used components for structural syntax highlighting (tree-sitter) and where reliance on regex-based approaches was more common.
Using different delimiter for opening and closing is a good idea on its own, too. I think it makes parsing simpler and unambiguous wrt nesting.
I've imagined something like this:
`(monospace)
_(underline)
/(italics)
~(overstrike)
O, c'mon! That is clearly a giant heading in a display font, squeezed in the middle and wider at the top and bottom. (-;
- Superscript with hat symbol (^)
- Hidden content (also known as spoiler tags, content warnings, click-to-reveal, etc...) with two pipe symbols (||) at start and end of hidden content. Interact with the content to show the content inside.
- Table syntax to show tabular data and align content with pipe, hyphen, colon symbols
---
After that, I'd look at the extensions that are only useful for the use-case you're targeting:
- Subscripting with tilde symbol (~)
- IDs, Classes and Attributes
- Task lists
- Sections / Containers
- Language labels for code blocks
- Math Support (mathml, latex, katex, etc...)
- Table of Contents / Footnotes
- Definition lists
- etc...
echo 'Hi there! Have a [hyperlink](https://www.gnu.org/software/groff/manual/groff.html).' | lowdown -st man | groff -man -Thtml
So if I set MANROFFOPT=-rU1 in the environment, I can get clickable links in man… if the man page author included them that way in the first place. I'm not sure how common that is in the wild, but grepping the ones on my system, I find firejail(1) contains a link to a GitHub issue embedded in that way, and it does indeed work when I hit ^O^N to seek to it and then C-mouse1—though the mouse gesture I have Alacritty using for links doesn't seem to work through tmux (there might be a way involving twiddling the tmux terminal-features setting, but I ran out of steam before trying this), and I didn't see a great way to get either grotty or Alacritty to style them on display instead of having them blend into the surrounding text, so it's still kind of scuffed in practice. (Though I bet the cool kids have moved on from Alacritty by now?) less displays the link target in the status line when you use the navigation commands, so it's not inaccessible, but for opening selected links directly from less with the ^O^O gesture rather than leaning on terminal support, it looks like you need to explicitly set the LESS_OSC8_ANY and/or LESS_OSC8_‹scheme› environment variable to a shell command that outputs a shell command pattern to substitute the link into; if I set LESS_OSC8_ANY='echo xdg-open %o' then it passes it to my Firefox. I wonder if they'd take a patch (or if any existing distributions patch it) to use that as the default?
That was a fun little rabbit hole to go down, thank you.
… wow, hang on, I just checked for Bash, and it has an Info file but it says it's just an intro and the manual page is the definitive version‽ That's… hah. There must be some timeline jank around that; ambiguous NIH vibes around Info aside, I wouldn't have expected it from an actual GNU program! Did Bash show up before Info existed?
A man page source isn't a binary format, so your statement that they're "plain text" is technically correct. (The same is also true of TeX and LaTeX files, and even PostScript if you want to stretch the definition of "plain text" until it snaps.) But the renderer is groff or (legacy) troff with the `an` macro set. less(1) (or, originally, more(1)) is just the pager that consumed the former's output (if the output format is ASCII, which is one of many) and handled paging on the terminal for the convenience of the user.
In my old Sun workstation (and even early Linux desktop) days, I rarely used man(1) in the terminal because 1/terminals were usually too small and weren't usefully resizable like they are today, and 2/unadorned monospaced fonts don't look nearly as nice as properly typeset pages do. (Color terminals were just coming on the horizon, and text could only be emboldened, not italicized.) Instead, I typically used xman whenever I could. The best way I can describe xman is as if you were rendering man pages into PDFs and viewing them in Preview on the Mac. Man pages were much more comfortable to read that way.
.Lk https://dotat.at/ "Tony Finch’s web site"
It's a very old idea
In the paper, Copernicus postulated the principle that "bad money drives out good", which later came to be referred to as Gresham's law after a later describer, Sir Thomas Gresham. This phenomenon had been noted earlier by Nicole Oresme, but Copernicus rediscovered it independently. Gresham's law is still known in Poland and Central and Eastern Europe as the Copernicus-Gresham Law.
The wikipedia page about "worse is better" re: software linked above states:
It refers to the argument that software quality does not necessarily increase with functionality: that there is a point where less functionality ("worse") is a preferable option ("better") in terms of practicality and usability.
(1) I can never remember, whether I need to use [] or () first, when embedding an image. In Org mode syntax one simply uses [] for both parts.
(2) Or whether ** is bold or italic or * is bold or italic. Other formats use the well known / to mean italic, which optically already makes more sense and also doesn't interfere with something being bold or not, because it is a separate symbol. This makes Markdown also harder to parse btw..What about something like AsciiDoc (or reStructuredText)?
* https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
* "Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code": https://news.ycombinator.com/item?id=33468213
Simply things are still simple, but there seem to be more advanced options for those that want/need them.
Writing is a demanding kind of encoding. At the same time, we all expect but rarely get good, accessible, searchable documentation. Why? The one barrier that cannot be removed is the need to retain semantic structure.
In TFA, the author writes:
The Bad -- We don’t know what we want.
We consistently fail to manage meaning. It's strikingly paradoxical because the art of programming is all about meaning. We organise code semantically because it is essential to do so (not just for compiling, but also) for extending/refactoring/review/retrieval/understanding.
We need to write with the same considerations. This need not be complicated. Yet we persist in using the wrong utensils for the recipe.
> Markdown is the best compromise we know of
It reduces keystrokes and makes the handraulic act of writing easier. But... it addresses only part of the problem.
As an example of a small improvement, HTML5 offers a minimal set of semantic tags: <summary> <article> <main> <section> <details> <aside> <figure> <figcaption> <time>
It may be a simplistic set of tags, but it is an improvement over easy-to-type text blobs.
There's the stuff that wows people and the stuff that people actually USE.
What's wrong with .txt ?
Yet, I am the same person who refuses to code in anything but Rust due to how not-awful it feels to me. Strange how a person can hold a completely opposite view for two instances of the same problem. Being human in a nutshell.
Well, indeed, Markdown is an inadequate tool for that. Let the author use more powerful tools, be it HTML, LaTeX, SVG, etc.
Markdown is fine for its intended purpose: very light formatting, very simple header structure. If I were not that lazy, i would come up with something opposite to CommonMark, some MarkDownDown, that does away with alternative ways to format things, most escaping, and most advanced syntax. The goal would be to have an easy-to-implement, unambiguous, safe and simple subset good for use anywhere. Intentionally limited.
(For daily use I prefer Org Mode, due to its vastly superior support in my preferred editor.)
> Rules for emphasis should be simpler. The fact that doubled characters are used for strong emphasis in commonmark leads to many potential ambiguities, which are resolved by a daunting list of 17 rules. It is hard to form a good mental model of these rules. Most of the time they interpret things the way a human would most naturally interpret them---but not always.
*bold*
_italic_
*_bold italic_*
_*also bold italic*_
---
If you're writing a parser, you might have text nodes, and bold/italics nodes which can contain each-other and text nodes. Example:
- bold node
-- italics node
--- text node
But if you add html support, you're going to run into strings like this:
<b><i>text content</b></i>
How easy is it for you to represent that?
What about:
not bold or italic <b>bold but not italic <i> bold and italic </b> italic but not bold </i> not bold or italic
What about:
</b> not bold <b> bold <b> bold again? </b> is this still bold? </b> what about now? <b>
• Markdown (most of my notes these days, supplanting my previous use of plaintext.)
• Single-file HTML (when my use case for fancy documents exceeds markdown's limits. While you can embed HTML into markdown, renderers vary in what they allow or sanitize, and vary in how you can (ab)use style tags. I've even taken to looking up CSS rules for printed documents, since my intended target is often pdfs or actual print at that point. Occasionally, JavaScript!)
• Google docs (Android phone nonsense!)
I'd mutter something about "using the right tool for the right job", but that's probably giving myself too much credit.
Copying my thoughts from there which haven't changed:
>To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?"
Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant.
Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax.
I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
*****
My thoughts on strictly-defined XML-ish syntaxes are the same: they're harder for humans to read, write, and modify, which defeats the primary purpose and benefit of Markdown.
Very few people have to write a Markdown parser. Many orders of magnitude more have to read and write Markdown. Optimize for them even if it makes writing the parser painful.
<b>This</b> <i>is</i> *valid*
<ul>
<li>*Mark*</li>
<li>_down_</li>
</ul>
It's "allowed" to use raw pointers, malloc, and any number of things in C++ code. In general, if you do any of them in a modern codebase you're doing it wrong.
Markdown is popular because it is simple. I have never had to teach anyone Markdown. They look at the file and immediately see what's going on and can copy the style.
Occasionally someone may have to look up something like table syntax, but no one in my career or personal life has ever asked me to explain Markdown to them, which is rare for a technology that is so widely used.
This has not been my experience with other markup languages.
Bonus: It starts simple but can be used to do whole books if needed.
If you introduce something with advanced functionality onto a team, soon enough someone's going to use pieces that others don't fully understand later.
Now everyone touching the document has to understand includes and document metadata and whatever else someone added. Suddenly you have includes and cross-references and what used to be a document where you could read the raw non-rendered form linearly top to bottom is a confusing mess unless you render it. Markdown is almost always just as legible raw as rendered.
Everybody sort of knows it sucks as a formatting language. But we love it anyway. The benefit of being able to get a typeset document from a nice looking plaintext document is just too convenient. It is why specialized markdown editors make no sense to me. Why would you target something as shitty as markdown if you have a specialized editor? But really, if you at all care about the semantics of your document don't write it in markdown. But more importantly please don't kill the utility of markdown by adding semantics to it, all that noise just make the plain text look bad.
Not too long ago, I used to think that Markdown was the Bee‘s knees. But having been forced to write some documentation in plaintext, I learned that plaintext is significantly more readable than raw markdown.
I think one of Markdown‘s biggest sins is how it handles line breaks. Single line breaks being discarded in the output guarantees that your nicely formatted text will look worse when rendered. I understand there are use cases for this. But this and the „add a trailing space“ workaround are particularly terrible for code documentation.
My experience has been the complete opposite. Markdown parsers that don’t discard single linebreaks (e.g. GitHub-flavored markdown) turn my nicely formatted text into a ragged mess of partially-filled lines. Or for narrow display widths, an alternating series of long and short lines.
Markdown parsers that correctly discard single linebreaks make sure that the source text (reflowed to fit a max number of characters per line) and the rendered text (reflowed to fit the display width per line) both look reasonable.
Your at-rest format allows you to use any tool to edit it. The specialized editor becomes a preferred tool, but not the only tool nor the most important one. Markdown and it's ecosystem came before the editor.
Because Markdown is the standard text formatting language. It’s the format everybody works in.
> But really, if you at all care about the semantics of your document don't write it in markdown
But it’s the standard text formatting language everybody uses.
God, remember when that was that goal of HTML and the web?
What a beautiful couple of years that was.
On top of that come issues like the lack of pagination support in browsers, which make long document impossible to read and practically require to add custom UI inside the website itself.
ePub works much better, with readers giving control over line spacing, font size, pagination and proper markup for TOC and other metadata, but despite ePub being based on xHTML, browsers have ignored it (only old Edge supported it for a little while).
And on no planet is it human readable without parsing.
What a rediculous thing to even say.
HTML was designed for humans to read and write long before Claude or compiling everything from typescript or whatever, when websites were all written by hand. In text editors. Even if you were using PHP and templates or CGI you wrote that shit by hand, which meant you had to be able to read it and understand it. Even if you were using Dreamweaver, you had to know how to read and write HTML at some point. WYSIWYG only gets you so far.
Is HTML more difficult to read than Markdown? Sure. It is impossible? Not even remotely. Teenagers did it putting together their Geocities websites.
You can be as snarky as you like, but facts are facts.
HTML markup is pretty readable (except when it becomes soup) and I read and write raw HTML documents all the time. I like it better than markdown.
It's even more readable in a code editor that distiguishes tags from content.
Both of them.
You know, like when you write <h2> in HTML or \section{} in LaTeX?
Also, as I use it, Markdown is effectively plain text. I very rarely look at "rendered" markdown. I guess in practice I actually use "plain text" that just happens to look a lot like markdown by this article's definitions.
But everything else, headings and bold and italics and lists, I’m honestly not sure I can tell the difference. It’s like watching movies with subtitles when you’re sufficiently experienced: your brain just fills in the gaps and you don’t even notice
Though I agree simple usage is good enough in practice, there are a lot of edge cases that can cause subtle bugs.
This blog post makes no sense to me.
Yes, there is a problem with "many ways to do the same thing". The solution is ease - use a linter or autoformatter. No more bikeshedding.
If you plan to use a clean yet expandable syntax, look at Typst. One of its core design principles (https://github.com/typst/typst?tab=readme-ov-file#design-pri...) is:
> Simplicity through Consistency: If you know how to do one thing in Typst, you should be able to transfer that knowledge to other things. If there are multiple ways to do the same thing, one of them should be at a different level of abstraction than the other. E.g. it's okay that = Introduction and #heading[Introduction] do the same thing because the former is just syntax sugar for the latter.
Have used asciidoc, HTML, word, latex, and rst.
Markdown is the least painful of all. It's not perfect but the others are worse.
(My custom stack uses markdown (or Jupyter notebooks converted to markdown). Pandoc plus some custom filters creates typst (for PDF) or epub.)
1. Use a proper Markdown parser. The grammar is easy to define EBNF style most implementations I see now days use some recursive descent parser, etc… Regex implementation was used in original authors parser when it became popular.
2. You can resolve ambiguities and define more consistent symbols that make sense. Most markdown implementations are decent and follow common sense best practice syntax.
3. The beauty is its simplicity. You can pick it up in a few minutes and utilize it anywhere you damn near see a text box.
4. Parsing to HTML isn’t the only option! I mostly use TUI markdown viewers that render the document via ANSI escape codes beautifully. Check out glow project. But once you parse and have a AST, you can easily walk it and render it in other ways as well. Again though. Everyone can read a text document and a html document. You can render it to a PDF if need be.
5. Do we really need a whole new markup text2<format of some kind>? Markdown is simple fast and widely supported. So I have to say.. I prefer it over most things and that includes Rst.
If you need real beauty and power you can move to LaTeX or something… My two cents anyway.
This may surprise you, but that is very common in programming languages.
Html has that same problem. Think <b>, <strong>, <p style=“font-weight: 900;”>, etc.
That’s life. Get used to it.
Maybe we can bring back all the fun tags by making them acronyms? <marquee> can be "make a really quite entertaining effect".
My point wasn’t that they are identically - my point is that 99% of the time they achieve the same effect. Or they would be if I had swapped the <p> tag for a <span> tag.
Then, in the solution section, doesn't identify a solution.
No thank you, I'll stick with Markdown.
If you’re used to CommonMark features, this is all you need.
[1]: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
What do you all think of Djot?
Looking at the repo's issues, I'm a bit concerned that it's already fragmented since some enthusiasts have implemented features far beyond, or against, Djot's spec. People seem impatient for v1.0...
- Djot requires
- writing nested lists
- with blank lines in between
- successive list items at the same level
- can skip the blank line
- but not this list item
Djot could have avoided the blank line requirement by not trying to join hard-wrapped lines back into one paragraph / list item. That would work for me because I only soft wrap my text. Djot’s choice to support hard wrapping caused all of its users (including those who hard wrap) to have worse nested list syntax.
Markdown though, especially if you're not using way too much of it and mostly using it sensibly, just to give your document some structure, can be read as plain text by pretty much everyone, and will be implicitly understood. Sure, they might not understand the exact different between a word with asterisks on either side and one with underscores on either side, but they'll get that you meant to emphasise that work. They'll also understand a list shown with asterisks, while <ul> and <li> tags will get too verbose for them and clutter the actual content (I don't really care, but I get why they do).
Programming languages (and the like) are for humans, not for computers or for creating formal systems.
Understanding this simple fact will save you (and by you I mean me and the type of people who frequent sites like this) a ton of headache.
A critique of MD carries no wind in my sails when it can't even appreciate why marrying multiple contemporary chat-grade formats into a document format might be a helpful thing.
Of course there are problems as you veer away from chat-like messaging, but it does a lot, and allows HTML when it can't go any further.
Almost everyone who complains has some parser or rendering related agenda. No one cares if you can't nest asterisks inside underscores. Most of these edge cases don't read well as Markdown, which defeats the purpose.
We already had plain text for that. Markdown was invented to be converted to HTML. It has no utility over plain text otherwise. The link and image syntax is doing what HTML tags do, but are less readable for people than just pasting the URL. The relationship to the machine isn't incidental, it's intrinsic.
My cat is an idiot.
My cat is an idiot.
My cat is an idiot.
This is my single biggest complaint about reStructuredText. You create headings by putting underlines and (optional!) overlines around the section heading text. But all of the following are valid title adornment characters:
! " # $ % & ' ( ) \* +
, - . / : ; < = > ? @
[ \ ] ^ _ ` { | } ~
==
H1
==
Normal text
--
H2
--
H1
~~
Normal text
!!
H2
!!This sentence is a great example of why such a pointless debate continues. Don't disparage HTML as "only" a markup language; it's a markup language. That's no 'better' or 'worse' than a programming language, just different.
A thread on markdown creator's stance https://x.com/nalband/status/1625541479295860752
All you need is Emacs! Nothing more!
Having explicit header levels (similar to HTML's <h[0-6]>) is another annoyance, as that makes inclusion of one org document into another problematic and requires restructuring (somewhat workaroundable with "#+begin_src org").
Outside of Emacs, yes. Within Emacs, there's a keybinding to paste a tree and have it fit.
The author of this article appears to be unaware of pandoc, and even better quarto. I started with pandoc and various plugins and my own scripts but moved to quarto, it is excellent.
We all need headers and paragraphs, right. But I might want file listings. Or command-line snippets with my own color coding and marks. Or C declarations and precise references to them in text. Or todos. Or bibliographic information. Or I want to express the difference between emphasis and italics. Or I don't. And so on. With XML I grow my own notation that fits like a glove. There's no boilerplate, everything is there for a purpose.
Besides, it is not that incompatible with plain text. Here's plain text:
abc def ghi
<text>
abc def ghi
</text>
And save for two extra words and 5 extra symbols, which in many cases (like config files) draw out the actual content
> XML is a) exactly what you need and b) as precise as you need it,
So how can I precisely get rid of that noise?
Or a million other examples I've wrassled with over the literal decades.
Whatever sophisticated semantic scheme you move into the markup layer, is gonna get messed up. And then your fancy schema is just noise, very expensive noise. Markup layer needs to glue as closely to natural language constructs as possible, and then glue a little more closely than that, and let the bulk of the information derived come from natlang. It's boring, but it works, and it's easier than ever to get quantitative information out of natlang.
Keep the domain stuff out of the markup layer.
All that said, Asciidoc forever baby. Write actual books in it. Not really more complex than Markdown[1]. Beats up DITA, takes its lunch money. Win win win.
[1] Unless you go legit insane with `include` and `ifdef/ifndef/ifeval`
And there is your answer to the clickbait title -- we're still using markdown because there's no alternative that is so much better that it is going to dethrone the one that has all the momentum from being the first good-enough take on this that got any traction.
Markdown in the same directory as the code it documents is very readable by humans and LLMs.
Given LLMs proficiency in markdown and that reading it in view and edit mode is comparable I bet many engineering teams ditch confluence/Google docs for documentation in favor of just markdown plaintext docs adjacent to code (my team has moved design/RFCs to this as well, get feedback via PR commits, turn an LLM loose to implement design)
Also if you really don’t like it I bet you could just ask the LLM to translate it. No point wasting the human input characters or tokens on a ton of <></> etc
Markdown though, that's my slightly fancy readme. It has just enough structure that I can easily read and understand it on the command line.
I can easily grep it without need for an advanced parsing engine.
If you need something with font and style weight then go for HTML.
But if I see README.html with a project, it's going to put me off wanting to contribute. I do not want to learn that project's style guide for how to add some new parameters to a table or remember that they want to specify italics in one of a dozen different ways.
if you tell somebody they can use HTML, they get frustrated when you tell them that tags other than anchor, bold, italic, list, heading, and paragraph aren't supported. but if you tell somebody they can use markdown, then they implicitly understand that the content they're submitting won't be rendered as green text on a purple background, and don't try to accomplish that.
Markdown apologist here - I think MD is the greatest thing since sliced bread and I use it a LOT. In fact, one project I work on has an entire git repo of just MD docs. It’s easy to maintain, and even non-tech people can author them with ease. In fat, I love that raw MD is entirely human-readable, and even if someone fat-fingers some of the syntax, it’s still very forgiving.
Don’t forget, many MD renderers support regular HTML embedding, including <style> tags, which makes it a very flexible choice.
I don’t think it’s going anywhere!
I do love writing in Markdown, but my reasons are adjacent in some ways. It's a flat file, the syntax is easy to on-board new users with, adoption is widespread, and the HTML escape hatch is available. I only adhere to the syntax because I can usually expect a parser to exist for whatever environment I'm in.
I don't think this is the best we can do (or have done). I find myself conflicted about where to go next. Gemtext is nice! Except, what I often want is more expressiveness and consistency. This will probably be, for me, a spec that can still be run through a "reasonable" Markdown parser. When the output breaks, it still comes out as readable plain text (albeit with some weird ASCII scattered through my prose).
Markdown is like that.
We use it because it's an incredibly human way of writing and reading data without having to wade too deeply into the various forms of overhead that allow machines to read, process, and display it.
There are bunch of reasons why it came to dominate.
And this is what Markdown is for: its just enough above plain text such that you can get at least 95% of what you need for a blog post, whilst still have the source be easy to type and proof read.
# Hi
I am a <ins> simple </ins> _programmer_ doing
<span class="fancy-text"> elegant </span> programming.
<div class="animation">
And here is my portfolio
</div>
I am a <span style="color:green">super *grinch* yall</span>
<p>I am a <span style="color:green">super <b>grinch</b> yall</span></p
Similarly, the div in the first example produces div, p, close-p, close-div, because the rule isn't "find he closing tag". The rule is something like "if the line starts with html then stop parsing and just copy until the next blank line.
All that said, I know the rules and generally know how to follow them. Of course I still run into the issue that even though there's commonmark, every site and tool is running their own variation which are incompatible.
[0]: https://typst.app
A similar but better markup is ASCIIDOC; it's formally defined and comes with a Technology Compatiblity Kit (TCK) that can be used to certify the compliance of an implementation with the spec.
If you have a better idea, make it happen.
The author merely described the parameters of a solution and didn’t even attempt to solve it.
In essence, we aren’t even left certain that a better solution that satisfies all stakeholders is possible.
Pandoc can convert Markdown to .icml this is an Adobe InDesign format which allows you to go from markdown to a professional typesetting solution including figures, footnotes etc.
Of course if you write a physics or math paper there are better solutions, but for the majority of things you could write markdown is good enough and that is the reason so much of the content you encounter is in markdown.
I’m reminded of the time Microsoft allowed mistakes in html writing. They attempted to parse a wide variety of common user errors. The effect of this was no standard and nobody else able to write a Microsoft compatible parser.
I dislike Nim lang because of this. At least Nim defined the specification. Still though I think it creates more cognitive load learning every legal variation and it makes searching more difficult.
I think to authors point if Markdown actually had a strict simple definition with one way to do it and no embedded html we would be better off.
The issue is that simple.
Personally, I always default to the simplest of tools. That's why I truly believe that anything meant for actual human use needs to have reasonable defaults. No "look at all the configs you can have", but a "let's get you what you need".
##[color:red] Heading 2
or using code blocks with particular headers which render out as normal text with the styling applied, like this:
```styling: 'ruleset here...' Lorem Ipsum Dolor ```
this does require a lot of work to consider what might be ergonomic for a particular element (by element I mean ATX headings, blocks, etc.), though.
https://pandoc.org/demo/example33/8.3-headings.html#extensio...
There are also attributes for image position/size, etc.
And I say this while putting up with lousy Markdown rendering on a pet project (Django). Really needs a separate project which lets you massage the html to get the display looking it’s best.
The need markdown solves is document formatting without needing to know or use a tag-based markup language and remaining easily human readable and editable.
That said, this is actually not the most widespread requirement. And when people need to solve this requirement, there often not tons of options. So some flavor of markdown is often the least problematic option.
- Reverse the link syntax braces, so the URL is in [], and the link text is in ()
- Allow table cell content to have line continuations
- It's pretty easy for humans to read & write
- It's very easy for AI to read & write
- It's quite token-efficient relative to its expressiveness
- It can be used in many different contexts, so it's actually surprisingly good for interchange.
There are many formats that are better-suited for a given purpose, but Markdown remains a very attractive compromise for many applications.
Most md editors don't support collapsing or folding sections, even though they could. VSCode had this feature where indentation is used as a simple hint to support collapsible sections, but md treats indentation as a code hint.
Per keyboard stroke, you write much more content with MD than HTML.
Even without a specific browser/reader Markdown is relatively non-intrusive to read. You cant read HTML without an extra tool/effort to discard tags.
And you can parse MD with regular expressions, or can you? ;). (tip hat to infamous Stackoverflow discussion)
People forget how important good UX can be, sometimes.
We're using Markdown, YAML, and JSON bc they're easy to use; they're "highly memetic" (easy to learn, easy to teach, easy to spread)
They don't require many months to learn like XML, back in the day
I’ve never attempted a markdown parser let alone any parser, so pardon me for asking a stupid question: doesn’t the markdown parser just let through HTML? Why does a markdown parser need to parse html?
† Obviously, for physical reasons given our current understanding of cosmology, no _implementation_ of a language can ever really be Turing-complete, but some language definitions are theoretically compatible with Turing-completeness, and others aren't.
If we are still using XML/YAML/JSON etc despite all their faults and shortcomings, Markdown can (and will) last decades.
Markdown is only going to get more popular as AI agents usage grows.
Use the best tool for the task. markdown is really good for talking to AI as a human for example.
Same goes for JSON, YAML, etc.. use what makes sense to you. I like markdown but I have issues with it as well. I like html, but i despise it sometimes. One-size-fits-all is the real enemy.
My view is that for all *langs (markdown, config, data, code, styling,etc..) we should leave the proverbial cave and come down from the trees, and talk about interoperability and best practices. Contracts, expectations, and exceptions.
There is this pattern where we invest in some software technology, and it becomes this ideology people fight over. Or invest a lot into it and fall into sunken-cost thinking.
Being able to rapidly figure out the best tool/solution, and readily tear out the old and patch in the new with minimal loss and friction, that should be the next era of tech. Not a repeat of the old, with a slight twist. I don't need another JSON, Markdown, HTML, CSS, C, Rust,etc.. especially with the advent of LLMs (hype aside), syntax is important but it isn't what it used to be. I want to be able to write in Markdown and know that if there is a better format, I can easily stop using it and reliably transpile all my existing Markdown, and tooling that works with Markdown to use that new format.
Adaptability and communication are the biggest dead-weights holding back technological progress.
Check out my "Advent of Markdown" where I go through surprising markdown behavior: https://mastodon.social/@timokoesters/115643467322561173
It's not possible. HTML is worse. You need at least something, which on parsing does not segfault.
Markdown is great at small-to-medium documents; LLMs seem to like it too possibly out of a combination of fairly logical design and lots of training examples.
Custom extensions like |||warning\nDisconnect from the internet befor trying this!\n||| get you a bit further and don't tie you into HTML.
The moment you need multiparagraph items including code blocks inside a numbered list that also has an unnumbered list child of which some of the items are images ... the person who set you that task probably doesn't understand good design, but regardless, I find you need something with an explicit tree structure, that is there are markers for both the start and end of each node such as <td> ... </td>. That necessarily makes the document harder to write, though at that complexity it'll probably be hard to read too.
HTML is terrible when you consider these properties. It's not easy to read, and is annoying to write and modify. Ditto for any other XML-based markup language, or even something like RST. LaTeX is right out.
Ultimately the author seems to suggest plain text should be what people use? That misses the point. Plain text is great for a lot of things, but if you're going to generate HTML (or something else) from it, you need something that at least has some structure. Markdown hits a nice sweet spot where it has enough structure such that you can reasonably generate rich-text document formats from it, but not so much that non-technical users can't work their heads around the format.
If what is to communicate, plain text is good enough. If you want to control how information is consumed, fuck of, die already.
... Which is additionally frustrating, since the links at the bottom aren't actually links (so you have to select them to copy and paste into your address bar)
I'm half wondering if they're using a very strange CMS to publish this blog. The fact that they seemingly cannot use the correct double-quote character in their code blocks lends a bit of support to this theory.
...and? What a weird article. Of course two different pieces source code can produce identical output. Every single mainstream languages are like that too.
> It has so many poor decisions baked in that if you try to use it it will actively fight against you the moment you think you know what you’re doing.
That misses the point. The point of Markdown is simplicity, not perfection. And that is also the reason why Markdown will prevail.
This is the needless complexity you wished away
Why are we using Markdown? Why do I use it every day?
It's easy to write. It's easy to read. Despite the OP's complaints, quality parsers exist.
pandoc can turn it into almost any format. We will still be writing markdown in 50 years, because the design bridges a bunch of compromises very nicely.
BTW TempleOS terminal comes into mind. I really love the hyperlinks.
Nobody uses markdown like that bro. We like markdown because it's easy to read both rendered and raw.
HTML is not a markup language anymore; it has become a lunatic application platform, and the last thing I want when trying to read some text is the intrusion of some lunatic's application.