The main point of Markdown is that it has a very important feature that other languages don't have: it's supported in a lot of places. Most of the alternatives mentioned in this thread or in the article are things that require custom tools, that can't be used in most of the places that currently do support markdown. It's common in a lot of places. Even Google Docs has a well hidden feature that allows you to paste markdown.
It's one of those good enough things where the things it doesn't do are outweighed by the notion that you can just use it pretty much everywhere.
It's a Betamax vs VHS type discussion (both are at this point obsolete and forgotten). HTML used to be pretty limited as well compared to things like SGML or any of the wonderful things people used for structured documentation in the eighties. Most of which are long forgotten. It still is pretty limited compared to those probably. But the point with HTML is that that's what browsers supported and not other formats. Many of the limitations were addressed over time.
Markdown could be improved in a similar way over time. We have ambiguous standardization, lack of features, mutually incompatible implementations, etc. The whole thing actually resembles HTML4 before people started addressing such concerns. Evolving Markdown seems like the easier path than replacing it with something else.
The other major feature is anyone can learn it in 5 minutes and fit all the instructions on an index card.
Many years ago I introduced it at a newspaper full of OG reporters who were a little nostalgic for the clatter of typewriters and the kid who would run the drafts around the newsroom.
On the first day they thought it was weird. On the second—and I'm not exaggerating, it was 24 hours—they loved it, because unlike MS Word/most WYSIWYG junkers, it did exactly what they told it to, without fussy formatting or invisible characters.
I've done this several times since, with all kinds of non-technical users who would never, ever tolerate something like LaTeX.
The whole point is to dumb a problem down so that people can focus on substance instead of form. It’s typesetting for people who aren’t technical and to lower the barrier for technical people for documentation of what they’re working on so far that you can ridicule people who still refuse to document their shit.
Any time you can make a developer chose between belligerence or stupidity to explain their behavior, they will either change the behavior or go with belligerence because they’d rather be dead than thought stupid. In either case you have maneuvered them out of being able to continue to be obstructive to team dynamics.
So you “solve” social problems with technical solutions not by making the solution better, but by making it the dumbest thing ever so only an idiot wouldn’t understand it.
It’s called markdown because it contains simple markup. Some of that is structural, no argument, but it’s also layout. Just enough to keep readers on board with what you’re saying.
Yeah, I don't see the point of this article: Markdown has already won.
I have some clients where I will send docs in MS Word/PDF format, but that kind of proves the point: the recipient sets the format. They may not explicitly say anything, but I'm not going to send something if there's a risk of receiving a "how do I open this?"
Also, code blocks are the worst example of it's limitations: just use backticks. Sometimes I want to have a big table or diagram and find that Markdown (/Obsidian) doesn't quite scratch my itch, but then there's always HTML...
What sorts of limitations you have with Obsidian? for diagrams I use Mermaid and it's work flawlessly within Obsidian.
For anything fancy, advanced and customized, I use Obsidian Canvas, it's a new feature they released recently. So far, I don't need anything outside Obsidian to do any kind of note taking/writing.
Important and often underlooked feature of markdown is that it's very readable as plain text. A lot easier to read than say latex or html.
I like to think of markdown as a high level markup language that gets compiled down to html. There is always a fallback to write html directly in markdown.
It was always THE main feature, that you can have something from both worlds in a win-win scenario. I don’t understand why someone would invent new html instead of appreciating markdown for it’s elegant simplicity
> Markdown could be improved in a similar way over time
I think that is unlikely to happen any time soon.
The problem is there isn't any kind of authority that can improve it. The closest we have is commonmark, which is more of a deacriptive specification rather than prescriptive.
The inventor of markdown, John Gruber (yes that John Gruber of daringfireball fame) has always distanced himself from any efforts to make it a "standard" too, in part why we ended up with the name "CommonMark" for that project...
While it is true, that Markdown is available in more places, it is also true, that it as well "requires custom tools". Just that those tools already got put in place by people developing things. There is no technical reason keeping developers from supporting other languages as well. It's more of a social issue, that they don't.
I also doubt, that Markdown will be able to be extended with the same "ease" HTML has been extended. Markdown does not have a systematic syntax like HTML does. It is not parser and machine friendly. It may be human friendly, but that doesn't make it easy to extend. In HTML on the other hand, one could, theoretically, just come up with a new tag name and introduce a new tag. Mind, we are talking about using both formats for writing a document. Of course Markdown doesn't have the same burden of already being the workhorse of the web and being directly interpreted by browser rendering engines. That however is an aspect that resides outside of the actual format considerations.
We already got tons of Markdown dialects and most of them don't gain particularly much traction, because they are only supported in niche tools. The only one of them that could be considered standard is maybe common mark, with its extensive test suite. Specialized ones like Pandoc Markdown for writing papers exist, but will most likely never leave their niche.
What I could imagine is, that maybe the changes from dialect to dialect could be outsourced into "extensions" and then one would need to pick "syntax conflict free" extensions. But since the format itself is kind of ad-hoc, and not systematic like HTML with its tags, it seems also unlikely, that such an extension system would work well.
But markdown does not require custom tools. The entire point of md is that you CAN use a renderer to make it pretty, but just reading the raw text in a text editor also works just fine.
But none of those is as simple and elegant as markdown. You can write html in text editor like in ages past, but what would be the point of doing that.
> You can include arbitrary HTML tags in Markdown at any place you need them.
That is well known and I am sure the author is aware of it. The problem they are describing is not whether HTML is technically allowed inside Markdown. It's that when you are writing Markdown, you are writing Markdown, not HTML, and that comes with some problems.
> It is perfectly capable of what the author claims it isn't.
In theory, yes. In practice, using Markdown becomes much less appealing once you start dropping raw HTML all over the place. The whole point of choosing Markdown is that you do not want to spend your time typing <p>, <a>, <li> and the rest. You want to write in Markdown, with only occasional HTML when absolutely necessary.
That is exactly where the author's complaints become relevant. If the solution to Markdown's limitations is routinely switching to HTML, then the argument becomes circular. If you are expected to write HTML to address the author's complaints, why bother with Markdown at all? If the answer is just "write HTML", then you may as well skip Markdown in the first place.
> The whole point of choosing Markdown is that you do not want to spend your time typing <p>, <a>, <li> and the rest. You want to write in Markdown, with only occasional HTML when absolutely necessary.
Why is that a problem?
> If the solution to Markdown's limitations is routinely switching to HTML, then...
Why would you do that, instead of only switching if you had to?
Why would the alternative be "just HTML" and write all the nonsense you said one doesn't have to?
Most markdown engines allow short tags to stand in for html, so for frequent features you can just use a short tag.
Alternatively you can extend markdown. I wrote a simple text based game engine that was markdown based but I needed some arbitrary additions appropriate for a game.. so I just added a few elements.
The author addresses this too. Once you start down this path, you go down the road of non-standardization which means losing portability, etc. I don’t see how this is a point against the author?
None of the author's other suggestions are portable either. So what if pandoc markdown is only understood by pandoc's tooling? DocBook is only understood by DocBook tooling. The difference is that pandoc markdown is already 95% similar to every other flavour of markdown, so migrating to a new system (if necessary) would be relatively simple. Also, the difference is that XML is a pain to write and I'm not sure semantic tags matter all that much.
Maybe portable isn’t the right word. I read portable as meaning the format’s semantics are consistent across platforms. The way I read the author’s complaint was that once you start tacking on extensions to markdown, you run into the problem of seeing if other markdown platforms being able to support your variant of markdown. Hence the part about CommonMark vs GitHub-Flavored Markdown vs etc. Having actually run into this before when working on CMSes in the past, I get why the author sees this as a problem. I don’t think everyone will agree with the authors viewpoint, but I just happened to think that this thread is completely missing the point that the author is trying to make.
> I read portable as meaning the format’s semantics are consistent across platforms.
By that definition, a format which is only implemented on one platform is 100% consistent. I agree Markdown is uniquely fragmented, but it's also uniquely widespread.
Markdown is an extensible core for writing platform-specific languages. I think comparing markdown in general to something like DocBook is comparing apples to oranges. Instead compare (e.g.) Pandoc's specific markdown variant to DocBook.
> I think comparing markdown in general to something like DocBook is comparing apples to oranges.
Hmm let me rephrase the issue I have with the comments in this thread. If your position is that markdown doesn’t belong in the same category as the others, then yeah, I agree. But I also think that’s basically rejecting the premise of the article and there isn’t a discussion to be had. If you disagree with the core premise, then it doesn’t matter what is said, there’s no discussion to be had.
However, the original parent comment is stating that the author’s assertion is false because you can extend markdown. I don’t see how that logic doesn’t run into the semantics and “portability” problems that the author is writing about.
I think you can have the discussion, but you also have to be careful about how you have it. Markdown is a family of languages; if you want to evaluate markdown against something like asciidoc for a particular use case, you have to pick the members of the markdown family which are best-suited for that use case and evaluate those flavours individually.
Take the comparison between markdown and asciidoc. You can't say, "asciidoc has semantic structure and markdown doesn't," because pandoc markdown does have semantic structure. If you need semantics, you can use pandoc markdown, which is a very fully-featured language that suffers from none of the issues the author points out. Yes, other flavours of markdown exist too, but so what? This one has great tooling and suits your needs.
Of course, you can't use pandoc in (e.g.) Reddit comments. But you also don't really need semantic markup in Reddit comments. It's a different flavour of markdown in a different application that is solving a different problem. Or consider MDX: Yes, `Command` is a react component, but maybe it needs to be a react component. Maybe it has a "run this command" button, or it generates an interactive graph of some sort. If you mark that up in asciidoc, you need a whole separate system to attach your components to your markup. That's just using the wrong tool for the job.
There are real limitations to this: You can't arbitrarily mix and match HTML and Markdown. As soon as you introduce an HTML block, you're locked out of Markdown syntax.
AsciiDoc lets you mix and match however you want. Or, put differently: AsciiDoc's superiority over Markdown extends even to being better at shelling out to HTML.
While that's true, I'd take Markdown + extensions to allow inline HTML or custom tags over AsciiDoc any day, even at the cost of losing some compatibility - converting that to plain Markdown is usually easy enough.
Not op, but markdown is much more likely to render well in different contexts, without post processing. My editor understands markdown, GitHub understands markdown, the link preview renderer in <random collaborative tool> understands markdown. It’s the lowest common denominator
That's true, and it's why we're all using it. But those different renderers all support different ill-defined interpretations of Markdown. You can forget about all of them accepting raw HTML.
It has sufficient differences to what is already accepted "everywhere" that I would have think about syntax more often than I'd like. That is enough. The minor inconveniences of Markdown incompatibilities are smaller than the inconveniece of AsciiDoc. It simply doesn't offer nearly enough potential advantages to be worth the hassle.
I often use <img> with "width" on GitHub, so that I do not have the scrollbars on the main page, and one can click on the image to see the original size. It is ugly, but what is the alternative in Markdown? Several images instead of one?
I also used pandoc and markdown, and never bothered going back to ascidoc, full HTML, or latex.
Footnotes are the only not always included extension to mmarkdown I need for slides or argument flows that are not killed by sidenotes, and some sites and toolings support that in markdown.
Even table of contents is not a problem, so what else is left? Formula setting? Buttons for UI vs function? Buttons plus Inline JS for step by step state modification?
I am not programming, I want text and something to be easily pasted into Word-like rich text, which seems to be the default text editor for emails for 90% of the population.
Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great.
For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me.
But in the end, no markup language will make you write better. It’s kind of like saying that ballpoint pens are limiting your writing, so you should switch to mechanical pencils.
Yes, the author conflates two different use-cases.
Markdown is the answer for "how do we enable people that don't want to invest a lot of time into producing content that's somewhat better than plain text?".
It's not trying to solve the problem of "how do we enable people that are willing to invest time into learning to produce the best possible and most structured content possible?" and I doubt that there will be language that will serve both of those use-cases very well.
The problem in practice is that quickly one merges into the other. You start with a markdown readme, then you have markdown documentation for a small project. But then one day you need full documentation for your project with cross links, translations, accessibility. With Markdown you end up bolting these things on and each flavor does it a bit differently.
Perhaps some of the blame can be laid with the poor UX of technically superior systems. restructuredtext (apart from the terrible name) built with Spinx can do impressive things but becomes a huge pain to configure. All the XML-based tools like DocBook are very complete but try to get started actually building something - apart from having to author them in XML (which is already a kind of punishment), then you have to figure out XSLT stylesheets, 2000s-era design Java tools for processing them. And just look at the DocBook landing page! AsciiDoc has improved their onboarding recently but does have the issue of feeling like a markdown-ish alternative that's just a bit different for no clear reason.
One downside here is that as more and more tools focus on the first use-case, people start using those tools by default when they actually fall into the second use-case. And there's often a pretty high barrier to switching once you've produced a lot of content, so a bunch of projects are using the wrong one long-term.
Arguably having a ton of hard to write, hard to maintain docs is waaay worse than Markdown that gets attention in PRs (MRs).
Especially that the things in the article seem irrelevant compared to actually adding and handling non-text content IMHO. (Mermaid diagrams for example.)
Sure a validator would be nice, but that's why a simple preview is available in most collaboration platforms.
typst looks interesting -- but how are you writing it? from what I looked at, it looks like theres an official web editor and a vscode plugin with limited support. this feels pretty limited, as someone who came in expecting something like obsidian.
> I'm not aware of any limitations in the Tinymist plugin.
I looked into this a while ago, and couldn't find a workflow I could live with. Have things improved? What's the workflow like for working on an image in, say, OmniGraffle to include in the document? Does text search in embedded PDFs work these days? LinkBack so I can edit the images easily inline?
Typst really does look good. Can one get an editor with live PDF preview ? It would be useful mainly for immediate feedback on markup correctness; then an HTML output ought to be "close enough".
Tinymist in VS Code does this out of the box (and looks like it can be set up in other editors). That or you can configure it to save out a new PDF automatically on save or as you edit the document and just open it in a PDF viewer that'll reload when the file changes.
I use Org-mode w/ GNU Emacs for all of my blogging(shameless plug: amitav.net). I like Org-mode because it's easy enough to write, looks nice enough, can be exported in quite a few formats, and the code block handling is chef's kiss. It supports quite a few languages and has a feature I've seen in no other editor before, where you can chain together code from different code blocks, and evaluate it, inside of the document itself. I tried out a few different blogging platforms with first class Org-mode support ([Blorgit](https://orgmode.org/worg/blorgit.html) and [lazyblorg](https://karl-voit.at/tags/lazyblorg/)), but they ended up taking up a bunch of time to set up, so my current process is just manually exporting my Org files to HTML, then using rsync to send them over to my server, then I have a Ruby script which just appends an index to the bottom of each file and serves it. I find Org-mode a lot more expressive and natural to write than my previous blogs which were in Markdown.
Hmm, have you checked out Ox-Hugo? It's a pretty great system for exporting to a hugo blog from a single org file. But then I guess your blog would have to be hugo-based
Org mode is unfortunately really tied to Emacs and so featureful that I imagine it's hard to port elsewhere. Maybe if an LSP gets built for it we'd start see it elsewhere.
By suggesting DITA as a valid alternative to Markdown, for any use, this has so completely lost the plot that it blows up whatever credibility Brian might have on the subject. It's disappointing, because I know of Brian and otherwise respect his work.
Short of writing in raw Postscript, I can't think of a more completely different set of strengths, audiences, and applications. I had to get to a company with more than 5,000 employees, 20 product lines, and 5 required i18n locales to find one where the overhead, god-awful ergonomics, and half-broken tooling of DITA were appropriate for the scale of the work _and also_ resourced enough to paper over every miserable facet of its implementation.
If you're using Markdown today _at all_ for a task, DITA isn't appropriate for it. If DITA was appropriate for the task, you never would've picked Markdown to accomplish it to begin with. Don't waste your time with it either way.
I'm really surprised I didn't see any mention of LwDITA yet. It can be expressed in XML, HTML, or Markdown. For us it is the sweet spot between the too little provided by Markdown, and the too much provided by DITA or DocBook
I feel like this article makes a lot of valid observations, but then wraps them with a false dilemma.
If it had tried to convince the reader of understanding what formatting needs are required before choosing a format, I would have entirely agreed with it.
Instead I'm left feeling mildly offended, and disagree with it.
I am surprised TeX [1] and LaTeX (pronounced tech and lay-tech) are not mentioned in this post. When I was a physics undergrad it was required that we wrote our senior thesis in it as well as any studies we meant to publish. Interestingly, my lab worked closely with a lab from the chemistry department and apparently their standard was MS Word docs. I was given to understand that this setup was fairly universal for both disciplines.
Latex seemed arcane coming from the background of HTML but it was pretty easy to pick up and is human readable.
Aside from the markup language itself, what is cool about TeX is its versioning. Since the idea is that at some point it does meet all of its goals it is essentially approximating its own perfect form. As a result as it gets closer to that goal its version approaches the value of Pi [2]. The current version is 3.141592653.
Tex has been around for 47 years so if you are looking for stability, look no further.
Some someone who learned document editing and drafting through LaTeX in my undergrad, I gotta say I'm not sure I'd recommend it anymore to people looking for a new tool.
To me, Typst is the 'weirdly missing' option here. I really see it as the most promising successor to LaTeX, which is not something I say lightly given that I spent years scoffing at the idea of Typst ever displacing LaTeX in my life.
I watched Typst from afar for many years. I finally took it out for a spin about a month ago after version 0.14 dropped.
In less than an hour I reproduced my résumé—complete with fancy functions to typeset employment entries on a grid system. In under 24 hours I was tinkering with the Typst source code.
Typst is amazing. Syntax is clean and consistent. The compiler is so so fast. Docs are excellent. And it is very close to TeX when it comes to typesetting quality. There are a few tiny rough edges that any \usepackage{microtype} enjoyer will miss, but stuff is improving rapidly.
(Also, XKCD disclaimer: this was not an LLM—I just use em-dashes a lot because TeX made them easy to type and I got used to having them.)
Typst seems to be a cloud based solution with monthly fees? How’s that even relevant to the discussion of open source, free, local tools like latex/markdown?
Absolutely not, no. At least not any more than LaTeX is a cloud based solution with monthly fees (Overleaf)
The language, ecosystem, and compiler are FOSS. There is a cloud editor / collaboration platform that is paid, but nothing about the language requires that you use it (I use it almost exclusively through emacs)
No, Typst the typesetting software is FOSS (Apache license), as is a bunch of the surrounding ecosystem (e.g. the LSP for editor support). The people making it also ofter paid SASS stuff for features enterprises like, but there is no need to use them.
Getting people to write documentation is already an uphill battle, the reality is it needs to be made as frictionless as possible or they won’t do it. IMO this rules out (La)TeX entirely: it’s just too much work that nobody wants to deal with.
I also have a philosophical issue with writing documentation in TeX: TeX is a typesetting program, i.e. it’s a presentation format meant to look a certain way on a page, while documentation should be agnostic to appearance as much as possible. But that’s more a personal objection.
I was the only student who did the thesis in MS Word because why the fuck not. Of course I had to use a LaTeX font, and there was a bug with PDF export, but other than that, it was fine.
Long ago I've read a study somewhere that people using LaTeX take more time and effort to accomplish same tasks compared to MS Word, but they are more happy about the process. Seems to match my impression that LaTeX is "by tinkerers, for tinkerers".
Documents written in the 1980s in LaTeX still compile and look great today. Good luck doing that with an old MS Word file, especially if it has equations in it.
Really weird to see this person mention MyST as a form of Markdown, and then go on to talk about reStructuredText as their first example of a markup language "that gives you more control over structure than ... markdown".
The whole point of MyST is to provide a markdown-like alternative to rST. It literally has directives, roles, structural semantics, etc. It just doesn't have the unlearnable syntax of rST and the so-called governance of docutils (the de facto rST parser) (see e.g. discussion on https://github.com/sphinx-doc/sphinx/issues/8039 and linking issues)
Thanks for making this point! I'm chiming in just to add that the Jupyter Book project that builds MyST tooling is now using a new TypeScript stack instead of Sphinx, for any interested newcomers!
But yes, ^this. We are building around a shareable AST precisely because structure really matters.
Been constantly using it for ~10 years and it works great. I read the article and its not incorrect, but its also kind of arguing that markdown users have problems that they themselves would say they don't have. If you need something else, use something else. With all that said, great title, they convinced me to waste ~3-5 min digging in.
I use markdown because it's easy to read without rendering. All of the alternatives in the article seem worse
If I wanted more structure, I'd just write html; or mix html into the markdown.
Pandoc lets me do things like generate libreoffice or microsoft word documents from the markdown, using a reference document for styling of headings etc. This also gives me good enough control to generate OK looking pdfs. It's not LaTeX levels of control, but it's much easier
I don't want to do extra work to hypothetically make things easier for an LLM.
Feels like a great argument...for, I don't know, a bunch of moderately technical high-schoolers who were somehow raised on markdown instead of Microsoft Word and want more power?
I think Typst looks really interesting for some scenarios, but inadequate for others.
I like RST a lot for Python documentation, because of all the directives for types, admonitions, and lots of domain-specific stuff. I wouldn't use RST if I'm writing a book, or a research paper.
In the same way, Typst looks like a great candidate for those last examples, but is likely unsuitable for documenting a library written in Python.
typst is great, but there are many many steps between “markdown isn’t sufficient” and reaching for typst.
1. typst only really has pdf output at the moment
2. so much less tooling available (linters, site builders, converters etc)
3. much less of a markup format, extremely tightly coupled to a specific tool (typst compiler)
again, love typst, but it has (atm) so much fewer applications
Markdown is meant for less technically skilled users and cases where you just want to type something with a bit of structure and not bother with full html. Making universal claims of it being bad ignores the proper user cases for it. Author can write HTML as much as he wants, but don't tell the world that MD is bad.
I'd rather use Markdown for writing and even user submitted content whenever possible instead of gag HTML or some other overcomplicated markup language. Sure, there's various different flavors of Markdown, but on average it's better than overcomplicated attribute ridden XML or even XSS prone HTML (where nobody even knows what section is and everything ends up being a div).
Just give me a good enough baseline, that's it. Markdown is close enough to that for now. I don't need that much semantic meaning in the text. Something like mdbook (https://github.com/rust-lang/mdBook) is more than enough for my needs, compared to shipping docs in once again, gag DOCX files and PDFs.
Good that there are solutions for more advanced use cases, though, but be careful with that complexity where you don't need it.
I love this post. While I don't mind markdown for quick notes which require basic formatting (headlines, bold, maybe a link), time and time again, I've found myself having to build parsing libraries and scripts for specific use cases just so the content can be interpreted correctly.
Take for example my blog, which I've had since 2016. It has been rebuilt into various systems over time and every time I had to migrate, there was a manual step of going over all posts and making sure they're displayed and interpreted correctly. In my last and current iteration, I've designed the system so that content is also stored with some hierarchical information (from html) like <section>, <article>, <address> etc, only applying styling to it when rendered.
I don't think we should stop using Markdown, but when something requires more than 200 lines of introductory text, more semantically enabled source feels necessary.
The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format. Markup formats in my opinion need to be defined in terms of a proper grammar, so that we can easily adapt that grammar in any programming language to build a parser and have support for that format in another language. The Org format in Emacs also suffered from this, but now there is an effort to make a grammar for it, I believe.
That said, I have used reStructuredText for writing a technical master thesis, and for that it worked wonderfully. If you buy into the ecosystem or use Pandoc to convert to LaTeX/TeX, and build a PDF or whatever you need, it will work well. But if you want to use it as a basis for HTML pages from other languages, which don't have a parser for reStructuredText, then you are in for trouble.
> The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format.
The same is true of Markdown (the canonical parser being John Gruber's at https://daringfireball.net/projects/markdown/) but that didn't stop third parties from extending it in their own implementations. For example, canonical Markdown doesn't support tables at all, but GitHub added custom markup for tables to their parser ("GitHub-flavored Markdown") and it became a de facto standard.
Oh, I am surprised the original didn't include tables. Guess it has been too long, since I looked at his page.
reStructuredText of course has support for tables[1].
I think writing a grammar for reStructuredText is a larger effort of course than writing one for Markdown, which is not to be underestimated.
Though extending reStructuredText is way less necessary, because it already includes a concept for custom "directives" (iirc that is what they are called). For example I have once made a custom directive to link to other documents, so that I have a local "wiki" like structure made out of files and folders. In Markdown no specific syntax exists for things to be implemented as extensions. Customization authors need to include special things in their parser instead, or come up with an extensibility concept themselves.
I think the point you are trying to make is, that there seems to be something else making the difference in adoption of the formats. Do I interpret your comment correctly?
I don't agree with this article. I mean sure there's no standard but there is pandoc, and quarto, both of which fill the gaps this article claims. And I also don't write content for LLMs so I don't care whether they can understand it.
The tenor of the article is more like: Markdown is holding LLMs back.
And it assumes the semantic enrichment comes for free.
While I agree that other formats allow for that and it's nice to see the solid options: nope, nobody in our team has the time to do such a chore and we are fine with the information we leave for each other.
It's analogous to the whining of the semantic web folks.
The semantic web hasn't happened as a whole. Same problem there: who would curate all the data?
The author seems to forget that markdown is just an extension of html. If markdown doesn't provide something that html does, you just write it in html and it will be rendered correctly.
I'd also argue that the limitations of markdown allow me to focus on actual content and less on the presentation. I have little use of all the features of a markup language if I can't remember how to use them.
It is not features but structure and undetstanding that is missing.
That said I am not sure what the solution is to that since your docs may need structure my docs dont need. Therefore you cant solve the "semantic" outside of a "namespace" of what you agree in your organization.
E.g. you may decide architecture diagrams are in Mermaid but that is by no means a stanfard and my org uses embeded svg.
So to go full circle... you are right just use HTML. After all it's semantic isn't it ;-)
> It is not features but structure and undetstanding that is missing.
I don't think this belief is valid. The whole purpose of markdown is to serve as a easy to read format that is publishable as plaintext and has minimalist standardized formatting and styling. It's something for humans to read and write without requiring specialized tooling.
For this purpose, "structure" is neither a requirement nor a valid concern.
> E.g. you may decide architecture diagrams are in Mermaid but that is by no means a stanfard and my org uses embeded svg.
That's a trait of your organization, not Markdown. Mermaid is ubiquitous, and used extensively in virtually everywhere in the internet. If you chose not use it that's a personal call you're making, and not related to Markdown at all.
It’s good to spread awareness (or just remind folks) that alternatives to Markdown exist. The right tool for the job depends on your circumstances. If I were scaling a docset for a team of contributors primarily consisting of technical writers, .adoc or .rst would be my preference. If I were scaling internal docs-as-code infra for software engineers, I’d use Markdown.
> Your content isn't just for human readers. Machines use it too. Your content gets indexed by search engines, and parsed by LLMs, and those things parse the well-formed HTML your systems publish.
I love RestructuredText. My blog used to be on RST, because I hate markdown. I moved to Hugo and Markdown because I wanted to put out content, not fight the weird system that was Sphinx (My RST blog was running on it), and ablog, the Sphinx blogging framework didn't work with Furo, my favourite theme. I just use Hugo, and I use Claude to fix the css.
Certainly not holding me back. I can go from crappy notes on a notepad to a polished and branded PDF release including TOC, tables, images and formulas, info/warning boxes, lists, code snippets with syntax highlighting, header/footer, etc in literally minutes. What else do you need?
Example: I want to explain the role of various files in the development directory. I start with a couple files; then I describe a command that creates a third file. And then I do this several more times, filling up the directory.
It wold be nice to show the starting list of files, a command, and the resulting list of files. It would also be nice to maybe color-code source and target files for each step, both in the command and in the listing. It may also help to typographically distinquish base files that are written by hand and generated ones. A few pictograms to tell apart files and directories would also be useful.
And it would be nice to somehow keep this a single process so that a command references a source state and produces the target state and the list of files is computed automatically.
(Doing this right now with XML and XSLT, targeting PDF via XSL-FO. Drew pictograms in SVG right in the XSLT. Haven't got to the automatic part yet, just got an idea that this is a natural way to go.)
I want figures. I want linked references. I want custom styling for images, and for blocks of text (eg warnings, notes, etc). I want a TOC and numbered chapters and sections. Sometimes I want a bibliography. Or a table generated from data within a JSON file.
You don't need this stuff for a readme file. But IMO markdown isn't powerful enough for blog posts, documentation or longer form content.
I use docusaurus as markdown renderer which adds most of what you need.
Mermaid.js for figures.
Never needed a data table from JSON but would be easy to add a custom component for this.
So yes for me markdown is definitely powerful enough for blogging and complex technical writing - has been for the last 6 years- with a few small extensions and I’ll eat my hat before I use anything xml based or reinvent html…
I hear you, but to be clear - you're not using markdown any more. A quick look at the docusaurus website suggests it uses MDX, which explicitly does not support commonmark. MDX documents cannot be rendered with other markdown renderers. And normal markdown text can also be incompatible with mdx.
If markdown were actually good enough, you wouldn't be reaching for bespoke extensions to markdown to make it more capable.
No. Should I? It looks like a markdown renderer with a huge pile of custom extensions.
It looks like they've added support for some of the things I need (eg references). But not other stuff. It has hardcoded block support for Note and Warning. But it looks like I can't program my own?
It supports front matter, but only in a few predefined styles? And it looks like I can't define my own rendering / styling for image blocks? Like, if I want to make images clickable and be shown full screen, I can't do it using quarto?
Like I said in another comment, if you're writing a markdown-like document that can only be rendered properly in one bespoke tool, you're not writing in actual markdown any more. Like if I had my own C compiler with a bunch of custom extensions, code written which uses all of those extensions isn't really C code. With actual markdown, you can send people the markdown content itself and they can render it locally using whatever tool they like.
Use a tool like quarto if you want. But the need for something like this proves the point that markdown on its own isn't sufficient. If you're reaching for a markdown-incompatible document format, why stick with markdown at all, and not React, or ascii doctor, or typst?
People keep reinventing LaTeX, but poorly. Most of the issues described have already been solved by it at least 20 years ago, especially the semantics part. The tooling is mature, well understood and supported on all operating systems.
As far as custom shortforms for fully tagged angle-bracket markup is concerned, people are reinventing SGML which can handle markdown and other custom syntaxes since 1986.
Markdown inline syntax is straightforward to capture using SGML SHORTREF. What's more difficult (impossible) are things such as reference links where a markdown processor is supposed to pull text (the title of a link) from wherever it's defined before or after its usage.
Haven't heard about archforms in a while ;) but it's not a technique for custom syntax, and since markdown is specified as a Wiki syntax with canonical mapping to HTML, there's no need for the kind of simplistic element and token renaming possible with archforms.
For example added an <nbsp> attribute to turn all spaces into non-breaking spaces, and used archforms to remove the attribute afterwards.
But yeah, maybe for Makrdown you don't need archforms. On the other hand, perhaps there is some super clever way to use archforms to get your reference links working.
Not at all. I use to maintain myriad of packages with restructured text, asciidoc, XML, perl pod and tex, but markdown all supercede it.
I could easily represent the long word spec for the DWG format in markdown with gh tables, rendering it to pdf, and it's even better than the original word. Just to represent our diffs.
I could easily produce C++ technical reports in markdown, rendering to pdf and HTML, which was perfect.
The rST docs are much easier to maintain in markdown than in rST.
> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices.
This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain in order to re-create 'the semantic web' - a flawed concept that has failed to catch on.
If the LLM needs context on content that humans don't need, the LLM needs fixing, not the content.
> With Markdown as your source, you can't easily go to another format.
File->Print->PDF.
Was that hard? (I admit it's still bizarre that Chrome puts 'Save As PDF' under Print).
(Apparently you can also go via LaTeX if you love a CLI)
> If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain
AsciiDoc is much better than Markdown for docs intended for humans that are more than short, README type of documents. Any advantage it has for documents intended for LLMs is a side effect of that.
The history of tech is full of "X is better than Y. We should use X", only for X to die. It doesn't matter what is better; it matters what is used. For better or worse, Markdown is what is used.
This is the kind of dismissive sneer the HN guidelines advise against.
You can write dev docs for humans and still want machine readability (without caring about whether some LLM can make sense of the docs).
Machine readability is how you repurpose your own documentation in different contexts. If your documentation it isn't machine readable it might as well be in a .doc(x) file.
> Web developers already went through all this with HTML. Prior to HTML5, you had <div> as a logical container. But HTML5 introduced <section>, <article>, <aside>, and many other elements that described the content.
Isn't the semantic web super dead? As in dead, buried, and decorated with countless generations of moss and lichen growing on its gravestone?
I find the semantic web stuff is really interesting but it seems to have more success where there are complex up-front data modeling and collaboration requirements, maybe between orgs. There is a Genome database out there for semantic web and I've heard of banks using it in complex fraud detection systems.
I believe that Markdown shines because it is literally human language. It’s the equivalent of tearing a paper sheet from a notebook and writing stuff down. If I wanted formatted, semantic writing, I’d use LaTeX
I'm surprised Pandoc markdown is not mentioned. You can make that semi structured quite easily, and write your own transformations using lua. It's powerful enough to write math papers and export into both pdf and html.
Being held back is the point.. WYSIWYM is a better ideal than more fonts, but it still tends towards trouble. It is hard enough to get engineers to write and maintain small amounts of correct comments without adding boilerplate metadata. I think everyone on this site is familiar with gripes against Jira but they are supposed to take a brain holiday when evaluating documentation mediums? Who is going to make sure previous and next topic are correct after the addition of a new topic? The great thing about absent fields is that they don't end up with bad content.
This is, personally, a controversial topic- I can take both sides of the debate in my head. I use markdown intensely and feel the deficiencies deeply, but wasn't able to see how there are real alternatives given the ecosystem (e.g. Obsidian).
I do think things are ripe for changes in this space.
This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?
What about markdown do you feel limits you in your writing process?
The beauty of markdown is that it’s standardized. If you find your self midway through the book and feel a need to change formats, it’s easy enough to parse and reformat.
You're right to start with your requirements. Try to get detailed, like the list @WA wrote out, then match it up with appropriate tech.
I wrote a technical book and I also wanted multiple decent-looking outputs. In my case: HTML, EPUB/mobi, screen and print PDFs. I was struggling with Markdown+pandoc+custom scripts/styles, so I switched to Asciidoc. I wrote about that process here: https://adammonsen.com/post/2122/
Here are two examples where the author used Markdown and the result was beautiful and successful (although layout for printed editions were done with extra/other tooling): http://gameprogrammingpatterns.com , http://www.craftinginterpreters.com . I'm curious if Bob would/will use Markdown for his next book. My process is different than Bob's... I didn't need literate code and I didn't want to do _any_ layout/pre/post-processing, even for print. Asciidoctor worked for this, although there were some compromises (see my links above). Print-ready layout is a lot of work, however you do it.
Is this your first book? Do you have a publisher? Will it be printed on paper? Do you have a developmental editor / proofreader / etc? Do you have a plan for what you'll do after you publish e.g. talks/promos/tour?
Contact me if you want to chat. I'm happy to share my war stories. And good luck!
- cross references and automatic tracking of figures, tables etc.
- different styles besides blockquotes such as info sections, warnings, tips
Imho, cross-referencing chapters, pages, figures, tables and the lack thereof in Markdown is the first and most important thing to check how you would like this to be solved.
I prefer writing Markdown for notes, e.g. in Obsidian, I think it fits very there. Because now you can easily take your notes to most other note-taking programs, and letting AI interact with these files also works great.
If I needed more context / am writing a paper I'd choose something like Typst, but usually I don't need the additional overhead.
The whole point of markdown, really it's whole value preposition is that it has nice looking plain text. And don't get me wrong that is a hell of a value to many people, myself included. Yes it is a terrible markup language, And I would encourage anyone doing serious document work to use a language that provides better semantic structure. But I would also argue that all projects that try to add these structures to markdown are missing the point and destroying it by making the plain text ugly.
I recently moved my personal writing to John MacFarlane's djot. It's a markup language that grew out of his markdown improvements blogpost, where he explored the issues, and possible fixes, he discovered while creating the common mark standard.
org-mode could have had a chance if they had provided tooling outside the emacs ecosystem. But now LLMs have chosen markdown, so it's destined to forever remain an obscurity.
Reading all these debates about document structure and formatting and so on is so wearying. I predict as long as we have text written by people the debates will continue. Truly a case of the taste of the writers and producers being a key variable that no one system will uniformly satisfy.
I would like to point out that asciidork provides ability to get AST representation of asciidoc. It’s very nice package. Not the author but have used it.
It really is terrible. I've hated it ever since it was introduced, but it "won" before anyone ever adopted it, because there were webprogramming Apple/DaringFireball fanatics that pushed it everywhere they possibly could, and demanded that you acknowledge it as an ideal outcome.
The Apple/DaringFireball fanatics have gone, and the web programmers learned how to really program because they had node as an option, but we've been stuck with this ugly, limited non-standardized format.
I'm an AsciiDoc partisan. I think we should just standardize a subset of AsciiDoc that does everything that markdown does and let people just implement that subset if they want. AsciiDoc gets a bit hairy when you get into the weeds, but if there were some sort of graduated standard that layered on features, you could learn as slowly as you wanted, and only by necessity. AsciiDoc gives you what you need as a base to automate typesetting basically everthing, as far as semantics go.
edit: I have to admit that I do not like AsciiDoctor, but it's just because I hate introducing Ruby dependencies. The people behind AsciiDoctor seem really great.
I have been using Markdown for decade(s) at this point, and I have never felt held back. I love Markdown, I use it daily, and I like that it can be instantly understood in its raw format by anyone and rendered cleaning to rich text easily.
Uhh isn't the main strength of md that it's human-friendly to write? Same for yaml. In both cases, dramatically worse for processing, strictly weaker for semantics and rich formatting... And also doesn't make you want to kill yourself when you're editing it by hand.
You lost me at, "XML is not that bad if you are already doing <x>". Verbosity is insane, attribute vs element freedom induces crowd madness. But I do love the data-visiting parts, why can't they somehow get that into Markdown.
I've never struck any off these problems, and in order to use the tools he suggests I'd have to switch out the systems I use that just support markdown
I sometimes make documents that require more complex formatting, so I use html after 20 minutes fucking around in word and getting angry
I'm working on a HTML replacement right now. If I am to believe the author, it would solve her issue (I don't think so). But I don't know if I want to "share". Can I patent it? Good luck with that.
Going off-topic now, sort of.
The Open Source I see just isn't serious. We lose the right to have an opinion about a technology, to steer it, as that right is mediated by money, and it just evaporates, unless you can set the norm by being a major user, like a tech titan.
Markdown is special because we as developers are the users! Though tech titans dictate what we shall use. As developers we are seemingly in a concentration camp where others set the rules, and there is no escape, unless we surrender our work in the name of love, in the presence of those who absolutely don't, government included, and whose basic mode of operation is to make the profit on our work. It's just legalized demoralization, if not outright stealing.
If you're from a developing country you know what I'm talking about. There is no way to be creative and get paid. You are a beggar, no matter your talents. The end result is that human creativity remains untapped. That is the price we as a community pay every day. Heil the rise of AI, so we don't need each other any longer, and the abuse can stop ;-
There's crimes everyday, and we normalize them, if they are done by the trusted and verified, that talk about merit while they hire f*cks to do their bidding. As a community we are a harem, and they come to rape us, err, give us pleasure, whenever they feel like it, and expect us to love it. Well, don't you love your new toys? That is who we are. And we therefore tend to repeat the cycle in our homes, as "men".
In the end the framing as a technical issue is what marks us. It's is the safe zone, where we can deny the real issue, and cope. If you're a member of Nation Procrasti-me, you know what I'm talking about. Nation Procrasti-Me, Where Life Is Denied. And rent-seeking is the truth.
F*ck, how did we get so cooked? We shackled ourselves, duh. We are infants, or else outright dumb, dumb enough to give away our life force, for new toys to play. Worse, we dictate others do so too. That's when we stand on the side of the abuse, confidently like a toddler that just spread his shit all over the place and radiates "how good was that!".
My biggest problem with Markdown is that I hate writing in it. I find messing around with the syntax interrupts my flow.
Are others writing raw markdown/mdx or is there a CMS/Vscode plugin I should be using? (I have a few plugins already but find the writing experience pretty rubbish still)
Eh, we had plenty of such structured document formats in the past. Markdown has won simply because it's much less hassle to write while still being readable without a specialized viewer. Markdown is exactly at the right sweetspot.
The main point of Markdown is that it has a very important feature that other languages don't have: it's supported in a lot of places. Most of the alternatives mentioned in this thread or in the article are things that require custom tools, that can't be used in most of the places that currently do support markdown. It's common in a lot of places. Even Google Docs has a well hidden feature that allows you to paste markdown.
It's one of those good enough things where the things it doesn't do are outweighed by the notion that you can just use it pretty much everywhere.
It's a Betamax vs VHS type discussion (both are at this point obsolete and forgotten). HTML used to be pretty limited as well compared to things like SGML or any of the wonderful things people used for structured documentation in the eighties. Most of which are long forgotten. It still is pretty limited compared to those probably. But the point with HTML is that that's what browsers supported and not other formats. Many of the limitations were addressed over time.
Markdown could be improved in a similar way over time. We have ambiguous standardization, lack of features, mutually incompatible implementations, etc. The whole thing actually resembles HTML4 before people started addressing such concerns. Evolving Markdown seems like the easier path than replacing it with something else.
The other major feature is anyone can learn it in 5 minutes and fit all the instructions on an index card.
Many years ago I introduced it at a newspaper full of OG reporters who were a little nostalgic for the clatter of typewriters and the kid who would run the drafts around the newsroom.
On the first day they thought it was weird. On the second—and I'm not exaggerating, it was 24 hours—they loved it, because unlike MS Word/most WYSIWYG junkers, it did exactly what they told it to, without fussy formatting or invisible characters.
I've done this several times since, with all kinds of non-technical users who would never, ever tolerate something like LaTeX.
The whole point is to dumb a problem down so that people can focus on substance instead of form. It’s typesetting for people who aren’t technical and to lower the barrier for technical people for documentation of what they’re working on so far that you can ridicule people who still refuse to document their shit.
Any time you can make a developer chose between belligerence or stupidity to explain their behavior, they will either change the behavior or go with belligerence because they’d rather be dead than thought stupid. In either case you have maneuvered them out of being able to continue to be obstructive to team dynamics.
So you “solve” social problems with technical solutions not by making the solution better, but by making it the dumbest thing ever so only an idiot wouldn’t understand it.
It's not even typesetting. It just formalizes the semantic parts of any well written long document.
It holds people back because it's not meant to be a typesetting tool. It's mostly meant to look good in its raw format.
It’s called markdown because it contains simple markup. Some of that is structural, no argument, but it’s also layout. Just enough to keep readers on board with what you’re saying.
Yeah, I don't see the point of this article: Markdown has already won.
I have some clients where I will send docs in MS Word/PDF format, but that kind of proves the point: the recipient sets the format. They may not explicitly say anything, but I'm not going to send something if there's a risk of receiving a "how do I open this?"
Also, code blocks are the worst example of it's limitations: just use backticks. Sometimes I want to have a big table or diagram and find that Markdown (/Obsidian) doesn't quite scratch my itch, but then there's always HTML...
What sorts of limitations you have with Obsidian? for diagrams I use Mermaid and it's work flawlessly within Obsidian. For anything fancy, advanced and customized, I use Obsidian Canvas, it's a new feature they released recently. So far, I don't need anything outside Obsidian to do any kind of note taking/writing.
[dead]
Important and often underlooked feature of markdown is that it's very readable as plain text. A lot easier to read than say latex or html.
I like to think of markdown as a high level markup language that gets compiled down to html. There is always a fallback to write html directly in markdown.
It was always THE main feature, that you can have something from both worlds in a win-win scenario. I don’t understand why someone would invent new html instead of appreciating markdown for it’s elegant simplicity
> Markdown could be improved in a similar way over time
I think that is unlikely to happen any time soon.
The problem is there isn't any kind of authority that can improve it. The closest we have is commonmark, which is more of a deacriptive specification rather than prescriptive.
The inventor of markdown, John Gruber (yes that John Gruber of daringfireball fame) has always distanced himself from any efforts to make it a "standard" too, in part why we ended up with the name "CommonMark" for that project...
> https://daringfireball.net/projects/markdown/
> https://blog.codinghorror.com/standard-markdown-is-now-commo...
While it is true, that Markdown is available in more places, it is also true, that it as well "requires custom tools". Just that those tools already got put in place by people developing things. There is no technical reason keeping developers from supporting other languages as well. It's more of a social issue, that they don't.
I also doubt, that Markdown will be able to be extended with the same "ease" HTML has been extended. Markdown does not have a systematic syntax like HTML does. It is not parser and machine friendly. It may be human friendly, but that doesn't make it easy to extend. In HTML on the other hand, one could, theoretically, just come up with a new tag name and introduce a new tag. Mind, we are talking about using both formats for writing a document. Of course Markdown doesn't have the same burden of already being the workhorse of the web and being directly interpreted by browser rendering engines. That however is an aspect that resides outside of the actual format considerations.
We already got tons of Markdown dialects and most of them don't gain particularly much traction, because they are only supported in niche tools. The only one of them that could be considered standard is maybe common mark, with its extensive test suite. Specialized ones like Pandoc Markdown for writing papers exist, but will most likely never leave their niche.
What I could imagine is, that maybe the changes from dialect to dialect could be outsourced into "extensions" and then one would need to pick "syntax conflict free" extensions. But since the format itself is kind of ad-hoc, and not systematic like HTML with its tags, it seems also unlikely, that such an extension system would work well.
But markdown does not require custom tools. The entire point of md is that you CAN use a renderer to make it pretty, but just reading the raw text in a text editor also works just fine.
Same can be said about reStructuredText, AsciiDoc and many more.
But none of those is as simple and elegant as markdown. You can write html in text editor like in ages past, but what would be the point of doing that.
You can include arbitrary HTML tags in Markdown at any place you need them.[0] I am not aware of any Markdown tooling that does not support this.
So, no, Markdown is not holding me back. It is perfectly capable of what the author claims it isn't.
[0]: https://daringfireball.net/projects/markdown/syntax#html
> You can include arbitrary HTML tags in Markdown at any place you need them.
That is well known and I am sure the author is aware of it. The problem they are describing is not whether HTML is technically allowed inside Markdown. It's that when you are writing Markdown, you are writing Markdown, not HTML, and that comes with some problems.
> It is perfectly capable of what the author claims it isn't.
In theory, yes. In practice, using Markdown becomes much less appealing once you start dropping raw HTML all over the place. The whole point of choosing Markdown is that you do not want to spend your time typing <p>, <a>, <li> and the rest. You want to write in Markdown, with only occasional HTML when absolutely necessary.
That is exactly where the author's complaints become relevant. If the solution to Markdown's limitations is routinely switching to HTML, then the argument becomes circular. If you are expected to write HTML to address the author's complaints, why bother with Markdown at all? If the answer is just "write HTML", then you may as well skip Markdown in the first place.
> why bother with Markdown at all?
Maybe it's an 80-20 thang ? Your page is mostly MD that's easy on the eyes, but with "shelling out" for semantics like section or aside ?
> The whole point of choosing Markdown is that you do not want to spend your time typing <p>, <a>, <li> and the rest. You want to write in Markdown, with only occasional HTML when absolutely necessary.
Why is that a problem?
> If the solution to Markdown's limitations is routinely switching to HTML, then...
Why would you do that, instead of only switching if you had to?
Why would the alternative be "just HTML" and write all the nonsense you said one doesn't have to?
>why bother with Markdown at all?
Because a little html is less html than "everything in html".
Most markdown engines allow short tags to stand in for html, so for frequent features you can just use a short tag.
Alternatively you can extend markdown. I wrote a simple text based game engine that was markdown based but I needed some arbitrary additions appropriate for a game.. so I just added a few elements.
The author addresses this too. Once you start down this path, you go down the road of non-standardization which means losing portability, etc. I don’t see how this is a point against the author?
None of the author's other suggestions are portable either. So what if pandoc markdown is only understood by pandoc's tooling? DocBook is only understood by DocBook tooling. The difference is that pandoc markdown is already 95% similar to every other flavour of markdown, so migrating to a new system (if necessary) would be relatively simple. Also, the difference is that XML is a pain to write and I'm not sure semantic tags matter all that much.
Maybe portable isn’t the right word. I read portable as meaning the format’s semantics are consistent across platforms. The way I read the author’s complaint was that once you start tacking on extensions to markdown, you run into the problem of seeing if other markdown platforms being able to support your variant of markdown. Hence the part about CommonMark vs GitHub-Flavored Markdown vs etc. Having actually run into this before when working on CMSes in the past, I get why the author sees this as a problem. I don’t think everyone will agree with the authors viewpoint, but I just happened to think that this thread is completely missing the point that the author is trying to make.
> I read portable as meaning the format’s semantics are consistent across platforms.
By that definition, a format which is only implemented on one platform is 100% consistent. I agree Markdown is uniquely fragmented, but it's also uniquely widespread.
Markdown is an extensible core for writing platform-specific languages. I think comparing markdown in general to something like DocBook is comparing apples to oranges. Instead compare (e.g.) Pandoc's specific markdown variant to DocBook.
> I think comparing markdown in general to something like DocBook is comparing apples to oranges.
Hmm let me rephrase the issue I have with the comments in this thread. If your position is that markdown doesn’t belong in the same category as the others, then yeah, I agree. But I also think that’s basically rejecting the premise of the article and there isn’t a discussion to be had. If you disagree with the core premise, then it doesn’t matter what is said, there’s no discussion to be had.
However, the original parent comment is stating that the author’s assertion is false because you can extend markdown. I don’t see how that logic doesn’t run into the semantics and “portability” problems that the author is writing about.
I think you can have the discussion, but you also have to be careful about how you have it. Markdown is a family of languages; if you want to evaluate markdown against something like asciidoc for a particular use case, you have to pick the members of the markdown family which are best-suited for that use case and evaluate those flavours individually.
Take the comparison between markdown and asciidoc. You can't say, "asciidoc has semantic structure and markdown doesn't," because pandoc markdown does have semantic structure. If you need semantics, you can use pandoc markdown, which is a very fully-featured language that suffers from none of the issues the author points out. Yes, other flavours of markdown exist too, but so what? This one has great tooling and suits your needs.
Of course, you can't use pandoc in (e.g.) Reddit comments. But you also don't really need semantic markup in Reddit comments. It's a different flavour of markdown in a different application that is solving a different problem. Or consider MDX: Yes, `Command` is a react component, but maybe it needs to be a react component. Maybe it has a "run this command" button, or it generates an interactive graph of some sort. If you mark that up in asciidoc, you need a whole separate system to attach your components to your markup. That's just using the wrong tool for the job.
There are real limitations to this: You can't arbitrarily mix and match HTML and Markdown. As soon as you introduce an HTML block, you're locked out of Markdown syntax.
AsciiDoc lets you mix and match however you want. Or, put differently: AsciiDoc's superiority over Markdown extends even to being better at shelling out to HTML.
While that's true, I'd take Markdown + extensions to allow inline HTML or custom tags over AsciiDoc any day, even at the cost of losing some compatibility - converting that to plain Markdown is usually easy enough.
What are the trade-offs with AsciiDoc that would make you choose Markdown instead?
Not op, but markdown is much more likely to render well in different contexts, without post processing. My editor understands markdown, GitHub understands markdown, the link preview renderer in <random collaborative tool> understands markdown. It’s the lowest common denominator
That's true, and it's why we're all using it. But those different renderers all support different ill-defined interpretations of Markdown. You can forget about all of them accepting raw HTML.
It has sufficient differences to what is already accepted "everywhere" that I would have think about syntax more often than I'd like. That is enough. The minor inconveniences of Markdown incompatibilities are smaller than the inconveniece of AsciiDoc. It simply doesn't offer nearly enough potential advantages to be worth the hassle.
O’Reilly’s authoring system used to use AsciiDoc (may still do), made me hate AsciiDoc
mdx does tho. you could just not define any components, then you can nest markdown inside html no problem
> I am not aware of any Markdown tooling that does not support this.
Reddit surely doesn't, and I'd be very surprised if github did.
In practice, in any place you want untrusted users writing markdown stuff for formatting, you cannot allow arbitrary HTML for security reasons.
I often use <img> with "width" on GitHub, so that I do not have the scrollbars on the main page, and one can click on the image to see the original size. It is ugly, but what is the alternative in Markdown? Several images instead of one?
Github has a very limited subset of html that is allowed.
Slack doesn't allow html (although it also doesn't allow all markdown).
If you are converting to something other than html, such as a manpage, using html tags generally doesn't work.
Why's anyone still using Reddit? I heard they just locked down their API again, to verified developers now.
Network effect, the same reason why the magnificent seven are worth more than a trillion dollar each.
I also used pandoc and markdown, and never bothered going back to ascidoc, full HTML, or latex.
Footnotes are the only not always included extension to mmarkdown I need for slides or argument flows that are not killed by sidenotes, and some sites and toolings support that in markdown.
Even table of contents is not a problem, so what else is left? Formula setting? Buttons for UI vs function? Buttons plus Inline JS for step by step state modification?
I am not programming, I want text and something to be easily pasted into Word-like rich text, which seems to be the default text editor for emails for 90% of the population.
I also put interactive components in my markdown docs, I’m only using Markdown for content now.
Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great.
For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me.
But in the end, no markup language will make you write better. It’s kind of like saying that ballpoint pens are limiting your writing, so you should switch to mechanical pencils.
Yes, the author conflates two different use-cases.
Markdown is the answer for "how do we enable people that don't want to invest a lot of time into producing content that's somewhat better than plain text?".
It's not trying to solve the problem of "how do we enable people that are willing to invest time into learning to produce the best possible and most structured content possible?" and I doubt that there will be language that will serve both of those use-cases very well.
The problem in practice is that quickly one merges into the other. You start with a markdown readme, then you have markdown documentation for a small project. But then one day you need full documentation for your project with cross links, translations, accessibility. With Markdown you end up bolting these things on and each flavor does it a bit differently.
Perhaps some of the blame can be laid with the poor UX of technically superior systems. restructuredtext (apart from the terrible name) built with Spinx can do impressive things but becomes a huge pain to configure. All the XML-based tools like DocBook are very complete but try to get started actually building something - apart from having to author them in XML (which is already a kind of punishment), then you have to figure out XSLT stylesheets, 2000s-era design Java tools for processing them. And just look at the DocBook landing page! AsciiDoc has improved their onboarding recently but does have the issue of feeling like a markdown-ish alternative that's just a bit different for no clear reason.
> does have the issue of feeling like a markdown-ish alternative that's just a bit different for no clear reason.
Asciidoc is older than markdown. Kind of hard to be design something to be the same as something that isn't invented yet.
One downside here is that as more and more tools focus on the first use-case, people start using those tools by default when they actually fall into the second use-case. And there's often a pretty high barrier to switching once you've produced a lot of content, so a bunch of projects are using the wrong one long-term.
Arguably having a ton of hard to write, hard to maintain docs is waaay worse than Markdown that gets attention in PRs (MRs).
Especially that the things in the article seem irrelevant compared to actually adding and handling non-text content IMHO. (Mermaid diagrams for example.)
Sure a validator would be nice, but that's why a simple preview is available in most collaboration platforms.
Djot is another interesting alternative that tries to make Markdown more parsable and coherent: https://github.com/jgm/djot#rationale
I hadn't heard of that before but it looks like it solves a lot of my complaints about markdown.
I hope it gains more momentum.
Unfortunately it doesn’t seem to have a formal spec.
typst looks interesting -- but how are you writing it? from what I looked at, it looks like theres an official web editor and a vscode plugin with limited support. this feels pretty limited, as someone who came in expecting something like obsidian.
I've started experimenting with Typst for a few documents, and here's my stack:
- Zed editor with Typst plugin
- Tinymist LSP settings turned on to render on save in Zed, see https://code.millironx.com/millironx/nix-dotfiles/src/commit...
- Okular open to the output document. Okular refreshes the document when changed on disk.
It's not as polished as say, LaTeX Workshop in VSCode, but it gets the job done.
I'm not aware of any limitations in the Tinymist plugin.
And you can just write it in the plain text editor of your choice, and keep an eye on the PDF with typst watch.
> I'm not aware of any limitations in the Tinymist plugin.
I looked into this a while ago, and couldn't find a workflow I could live with. Have things improved? What's the workflow like for working on an image in, say, OmniGraffle to include in the document? Does text search in embedded PDFs work these days? LinkBack so I can edit the images easily inline?
you can just install the typst compiler yourself and let it run in the cli
You can write Typst in any editor you like, and the Typst compiler is FOSS available.
I write Typst code from emacs personally
Typst really does look good. Can one get an editor with live PDF preview ? It would be useful mainly for immediate feedback on markup correctness; then an HTML output ought to be "close enough".
Tinymist in VS Code does this out of the box (and looks like it can be set up in other editors). That or you can configure it to save out a new PDF automatically on save or as you edit the document and just open it in a PDF viewer that'll reload when the file changes.
LaTeX made me write better because of commenting above every paragraph.
What LaTeX helped me with was in taking more care of the content than the form/appearance.
I use Org-mode w/ GNU Emacs for all of my blogging(shameless plug: amitav.net). I like Org-mode because it's easy enough to write, looks nice enough, can be exported in quite a few formats, and the code block handling is chef's kiss. It supports quite a few languages and has a feature I've seen in no other editor before, where you can chain together code from different code blocks, and evaluate it, inside of the document itself. I tried out a few different blogging platforms with first class Org-mode support ([Blorgit](https://orgmode.org/worg/blorgit.html) and [lazyblorg](https://karl-voit.at/tags/lazyblorg/)), but they ended up taking up a bunch of time to set up, so my current process is just manually exporting my Org files to HTML, then using rsync to send them over to my server, then I have a Ruby script which just appends an index to the bottom of each file and serves it. I find Org-mode a lot more expressive and natural to write than my previous blogs which were in Markdown.
If org-mode wasn't so tied to emacs I suspect it would be the "default" text formatting syntax for a lot more people.
Hmm, have you checked out Ox-Hugo? It's a pretty great system for exporting to a hugo blog from a single org file. But then I guess your blog would have to be hugo-based
Org mode is unfortunately really tied to Emacs and so featureful that I imagine it's hard to port elsewhere. Maybe if an LSP gets built for it we'd start see it elsewhere.
By suggesting DITA as a valid alternative to Markdown, for any use, this has so completely lost the plot that it blows up whatever credibility Brian might have on the subject. It's disappointing, because I know of Brian and otherwise respect his work.
Short of writing in raw Postscript, I can't think of a more completely different set of strengths, audiences, and applications. I had to get to a company with more than 5,000 employees, 20 product lines, and 5 required i18n locales to find one where the overhead, god-awful ergonomics, and half-broken tooling of DITA were appropriate for the scale of the work _and also_ resourced enough to paper over every miserable facet of its implementation.
If you're using Markdown today _at all_ for a task, DITA isn't appropriate for it. If DITA was appropriate for the task, you never would've picked Markdown to accomplish it to begin with. Don't waste your time with it either way.
Wow, I've never heard of DITA, so I was totally unprepared for how funny this was going to be.
"Markdown is not great for writing complex documentation. Why not use XML instead?"
I'm really surprised I didn't see any mention of LwDITA yet. It can be expressed in XML, HTML, or Markdown. For us it is the sweet spot between the too little provided by Markdown, and the too much provided by DITA or DocBook
Ya don't often see this kind of vocal disappointment directed at DITA.
Can you provide more info about how exactly DITA+tooling fell on its face ?
> Markdown Lacks the Structure You Need
I feel like this article makes a lot of valid observations, but then wraps them with a false dilemma.
If it had tried to convince the reader of understanding what formatting needs are required before choosing a format, I would have entirely agreed with it.
Instead I'm left feeling mildly offended, and disagree with it.
I am surprised TeX [1] and LaTeX (pronounced tech and lay-tech) are not mentioned in this post. When I was a physics undergrad it was required that we wrote our senior thesis in it as well as any studies we meant to publish. Interestingly, my lab worked closely with a lab from the chemistry department and apparently their standard was MS Word docs. I was given to understand that this setup was fairly universal for both disciplines.
Latex seemed arcane coming from the background of HTML but it was pretty easy to pick up and is human readable.
Aside from the markup language itself, what is cool about TeX is its versioning. Since the idea is that at some point it does meet all of its goals it is essentially approximating its own perfect form. As a result as it gets closer to that goal its version approaches the value of Pi [2]. The current version is 3.141592653.
Tex has been around for 47 years so if you are looking for stability, look no further.
[1] https://en.wikipedia.org/wiki/TeX
[2] https://www.preethamrn.com/posts/piver
P.S.: manpage format is also quite simple to learn and it is always a really good addition to any CLI tool.
Some someone who learned document editing and drafting through LaTeX in my undergrad, I gotta say I'm not sure I'd recommend it anymore to people looking for a new tool.
To me, Typst is the 'weirdly missing' option here. I really see it as the most promising successor to LaTeX, which is not something I say lightly given that I spent years scoffing at the idea of Typst ever displacing LaTeX in my life.
I watched Typst from afar for many years. I finally took it out for a spin about a month ago after version 0.14 dropped.
In less than an hour I reproduced my résumé—complete with fancy functions to typeset employment entries on a grid system. In under 24 hours I was tinkering with the Typst source code.
Typst is amazing. Syntax is clean and consistent. The compiler is so so fast. Docs are excellent. And it is very close to TeX when it comes to typesetting quality. There are a few tiny rough edges that any \usepackage{microtype} enjoyer will miss, but stuff is improving rapidly.
(Also, XKCD disclaimer: this was not an LLM—I just use em-dashes a lot because TeX made them easy to type and I got used to having them.)
At a quick glance Typst seems to be very limited compared to LaTeX, especially for more unusual languages.
Typst seems to be a cloud based solution with monthly fees? How’s that even relevant to the discussion of open source, free, local tools like latex/markdown?
Absolutely not, no. At least not any more than LaTeX is a cloud based solution with monthly fees (Overleaf)
The language, ecosystem, and compiler are FOSS. There is a cloud editor / collaboration platform that is paid, but nothing about the language requires that you use it (I use it almost exclusively through emacs)
No, Typst the typesetting software is FOSS (Apache license), as is a bunch of the surrounding ecosystem (e.g. the LSP for editor support). The people making it also ofter paid SASS stuff for features enterprises like, but there is no need to use them.
> Typst seems to be a cloud based solution with monthly fees?
In the exact same way that git is: it isn’t, but one easy way to use it is.
Getting people to write documentation is already an uphill battle, the reality is it needs to be made as frictionless as possible or they won’t do it. IMO this rules out (La)TeX entirely: it’s just too much work that nobody wants to deal with.
I also have a philosophical issue with writing documentation in TeX: TeX is a typesetting program, i.e. it’s a presentation format meant to look a certain way on a page, while documentation should be agnostic to appearance as much as possible. But that’s more a personal objection.
I was the only student who did the thesis in MS Word because why the fuck not. Of course I had to use a LaTeX font, and there was a bug with PDF export, but other than that, it was fine.
Long ago I've read a study somewhere that people using LaTeX take more time and effort to accomplish same tasks compared to MS Word, but they are more happy about the process. Seems to match my impression that LaTeX is "by tinkerers, for tinkerers".
Documents written in the 1980s in LaTeX still compile and look great today. Good luck doing that with an old MS Word file, especially if it has equations in it.
Really weird to see this person mention MyST as a form of Markdown, and then go on to talk about reStructuredText as their first example of a markup language "that gives you more control over structure than ... markdown".
The whole point of MyST is to provide a markdown-like alternative to rST. It literally has directives, roles, structural semantics, etc. It just doesn't have the unlearnable syntax of rST and the so-called governance of docutils (the de facto rST parser) (see e.g. discussion on https://github.com/sphinx-doc/sphinx/issues/8039 and linking issues)
Thanks for making this point! I'm chiming in just to add that the Jupyter Book project that builds MyST tooling is now using a new TypeScript stack instead of Sphinx, for any interested newcomers!
But yes, ^this. We are building around a shareable AST precisely because structure really matters.
(I'm a core developer from Jupyter Book, the team that builds the new MyST stack — see https://jupyterbook.org/stable/community/history/ and https://mystmd.org/guide/background)!
Been constantly using it for ~10 years and it works great. I read the article and its not incorrect, but its also kind of arguing that markdown users have problems that they themselves would say they don't have. If you need something else, use something else. With all that said, great title, they convinced me to waste ~3-5 min digging in.
I use markdown because it's easy to read without rendering. All of the alternatives in the article seem worse
If I wanted more structure, I'd just write html; or mix html into the markdown.
Pandoc lets me do things like generate libreoffice or microsoft word documents from the markdown, using a reference document for styling of headings etc. This also gives me good enough control to generate OK looking pdfs. It's not LaTeX levels of control, but it's much easier
I don't want to do extra work to hypothetically make things easier for an LLM.
Feels like a great argument...for, I don't know, a bunch of moderately technical high-schoolers who were somehow raised on markdown instead of Microsoft Word and want more power?
No, seriously, who is this for?
This article doesnt consider Typst, which IMO ought to be the first port of call if Markdown isnt sufficient for your needs.
I think Typst looks really interesting for some scenarios, but inadequate for others.
I like RST a lot for Python documentation, because of all the directives for types, admonitions, and lots of domain-specific stuff. I wouldn't use RST if I'm writing a book, or a research paper.
In the same way, Typst looks like a great candidate for those last examples, but is likely unsuitable for documenting a library written in Python.
> In the same way, Typst looks like a great candidate for those last examples, but is likely unsuitable for documenting a library written in Python.
why though?
Would you categorize Markdown as unsuitable as well? if so, why?
typst is great, but there are many many steps between “markdown isn’t sufficient” and reaching for typst.
1. typst only really has pdf output at the moment 2. so much less tooling available (linters, site builders, converters etc) 3. much less of a markup format, extremely tightly coupled to a specific tool (typst compiler)
again, love typst, but it has (atm) so much fewer applications
Typst has already experimental HTML output and it specifically has a markup mode (default mode).
Conceptually Typst is a superset of a Markdown with a slightly different syntax (e.g. = instead of # for headers)
I guess we need to wait until Typst is natively supported by Github.
I've used typst for generating PDFs before, how good is its HTML output?
it looks like typst's html output is under construction [1].
1: https://typst.app/docs/reference/html/
Markdown is meant for less technically skilled users and cases where you just want to type something with a bit of structure and not bother with full html. Making universal claims of it being bad ignores the proper user cases for it. Author can write HTML as much as he wants, but don't tell the world that MD is bad.
I'd rather use Markdown for writing and even user submitted content whenever possible instead of gag HTML or some other overcomplicated markup language. Sure, there's various different flavors of Markdown, but on average it's better than overcomplicated attribute ridden XML or even XSS prone HTML (where nobody even knows what section is and everything ends up being a div).
Just give me a good enough baseline, that's it. Markdown is close enough to that for now. I don't need that much semantic meaning in the text. Something like mdbook (https://github.com/rust-lang/mdBook) is more than enough for my needs, compared to shipping docs in once again, gag DOCX files and PDFs.
Good that there are solutions for more advanced use cases, though, but be careful with that complexity where you don't need it.
I love this post. While I don't mind markdown for quick notes which require basic formatting (headlines, bold, maybe a link), time and time again, I've found myself having to build parsing libraries and scripts for specific use cases just so the content can be interpreted correctly.
Take for example my blog, which I've had since 2016. It has been rebuilt into various systems over time and every time I had to migrate, there was a manual step of going over all posts and making sure they're displayed and interpreted correctly. In my last and current iteration, I've designed the system so that content is also stored with some hierarchical information (from html) like <section>, <article>, <address> etc, only applying styling to it when rendered.
I don't think we should stop using Markdown, but when something requires more than 200 lines of introductory text, more semantically enabled source feels necessary.
The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format. Markup formats in my opinion need to be defined in terms of a proper grammar, so that we can easily adapt that grammar in any programming language to build a parser and have support for that format in another language. The Org format in Emacs also suffered from this, but now there is an effort to make a grammar for it, I believe.
That said, I have used reStructuredText for writing a technical master thesis, and for that it worked wonderfully. If you buy into the ecosystem or use Pandoc to convert to LaTeX/TeX, and build a PDF or whatever you need, it will work well. But if you want to use it as a basis for HTML pages from other languages, which don't have a parser for reStructuredText, then you are in for trouble.
> The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format.
The same is true of Markdown (the canonical parser being John Gruber's at https://daringfireball.net/projects/markdown/) but that didn't stop third parties from extending it in their own implementations. For example, canonical Markdown doesn't support tables at all, but GitHub added custom markup for tables to their parser ("GitHub-flavored Markdown") and it became a de facto standard.
Oh, I am surprised the original didn't include tables. Guess it has been too long, since I looked at his page.
reStructuredText of course has support for tables[1].
I think writing a grammar for reStructuredText is a larger effort of course than writing one for Markdown, which is not to be underestimated.
Though extending reStructuredText is way less necessary, because it already includes a concept for custom "directives" (iirc that is what they are called). For example I have once made a custom directive to link to other documents, so that I have a local "wiki" like structure made out of files and folders. In Markdown no specific syntax exists for things to be implemented as extensions. Customization authors need to include special things in their parser instead, or come up with an extensibility concept themselves.
I think the point you are trying to make is, that there seems to be something else making the difference in adoption of the formats. Do I interpret your comment correctly?
[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/...
I don't agree with this article. I mean sure there's no standard but there is pandoc, and quarto, both of which fill the gaps this article claims. And I also don't write content for LLMs so I don't care whether they can understand it.
The tenor of the article is more like: Markdown is holding LLMs back. And it assumes the semantic enrichment comes for free. While I agree that other formats allow for that and it's nice to see the solid options: nope, nobody in our team has the time to do such a chore and we are fine with the information we leave for each other.
It's analogous to the whining of the semantic web folks. The semantic web hasn't happened as a whole. Same problem there: who would curate all the data?
The author seems to forget that markdown is just an extension of html. If markdown doesn't provide something that html does, you just write it in html and it will be rendered correctly.
I'd also argue that the limitations of markdown allow me to focus on actual content and less on the presentation. I have little use of all the features of a markup language if I can't remember how to use them.
It is not features but structure and undetstanding that is missing.
That said I am not sure what the solution is to that since your docs may need structure my docs dont need. Therefore you cant solve the "semantic" outside of a "namespace" of what you agree in your organization.
E.g. you may decide architecture diagrams are in Mermaid but that is by no means a stanfard and my org uses embeded svg.
So to go full circle... you are right just use HTML. After all it's semantic isn't it ;-)
> It is not features but structure and undetstanding that is missing.
I don't think this belief is valid. The whole purpose of markdown is to serve as a easy to read format that is publishable as plaintext and has minimalist standardized formatting and styling. It's something for humans to read and write without requiring specialized tooling.
For this purpose, "structure" is neither a requirement nor a valid concern.
> E.g. you may decide architecture diagrams are in Mermaid but that is by no means a stanfard and my org uses embeded svg.
That's a trait of your organization, not Markdown. Mermaid is ubiquitous, and used extensively in virtually everywhere in the internet. If you chose not use it that's a personal call you're making, and not related to Markdown at all.
Markdown can be used where HTML is not available, like in AI chatbots for omnichannel mediums (e.g. WhatsApp).
Wow! TIL!
It’s good to spread awareness (or just remind folks) that alternatives to Markdown exist. The right tool for the job depends on your circumstances. If I were scaling a docset for a team of contributors primarily consisting of technical writers, .adoc or .rst would be my preference. If I were scaling internal docs-as-code infra for software engineers, I’d use Markdown.
> Your content isn't just for human readers. Machines use it too. Your content gets indexed by search engines, and parsed by LLMs, and those things parse the well-formed HTML your systems publish.
Sounds like I need to start using Markdown!
I love RestructuredText. My blog used to be on RST, because I hate markdown. I moved to Hugo and Markdown because I wanted to put out content, not fight the weird system that was Sphinx (My RST blog was running on it), and ablog, the Sphinx blogging framework didn't work with Furo, my favourite theme. I just use Hugo, and I use Claude to fix the css.
It's interesting to see how Markdown keeps getting more and more use, and even native Windows Notepad support!
> Markdown Lacks the Structure You Need
The problem is, I always need more structure. Give me some YAML and time and I'll make hell (not a metaphor, I'll concoct hell itself on it).
Markdown keeps me honest.
Certainly not holding me back. I can go from crappy notes on a notepad to a polished and branded PDF release including TOC, tables, images and formulas, info/warning boxes, lists, code snippets with syntax highlighting, header/footer, etc in literally minutes. What else do you need?
Example: I want to explain the role of various files in the development directory. I start with a couple files; then I describe a command that creates a third file. And then I do this several more times, filling up the directory.
It wold be nice to show the starting list of files, a command, and the resulting list of files. It would also be nice to maybe color-code source and target files for each step, both in the command and in the listing. It may also help to typographically distinquish base files that are written by hand and generated ones. A few pictograms to tell apart files and directories would also be useful.
And it would be nice to somehow keep this a single process so that a command references a source state and produces the target state and the list of files is computed automatically.
(Doing this right now with XML and XSLT, targeting PDF via XSL-FO. Drew pictograms in SVG right in the XSLT. Haven't got to the automatic part yet, just got an idea that this is a natural way to go.)
What else?
I want figures. I want linked references. I want custom styling for images, and for blocks of text (eg warnings, notes, etc). I want a TOC and numbered chapters and sections. Sometimes I want a bibliography. Or a table generated from data within a JSON file.
You don't need this stuff for a readme file. But IMO markdown isn't powerful enough for blog posts, documentation or longer form content.
I use docusaurus as markdown renderer which adds most of what you need. Mermaid.js for figures. Never needed a data table from JSON but would be easy to add a custom component for this.
So yes for me markdown is definitely powerful enough for blogging and complex technical writing - has been for the last 6 years- with a few small extensions and I’ll eat my hat before I use anything xml based or reinvent html…
I hear you, but to be clear - you're not using markdown any more. A quick look at the docusaurus website suggests it uses MDX, which explicitly does not support commonmark. MDX documents cannot be rendered with other markdown renderers. And normal markdown text can also be incompatible with mdx.
If markdown were actually good enough, you wouldn't be reaching for bespoke extensions to markdown to make it more capable.
Have you looked at Quarto?
No. Should I? It looks like a markdown renderer with a huge pile of custom extensions.
It looks like they've added support for some of the things I need (eg references). But not other stuff. It has hardcoded block support for Note and Warning. But it looks like I can't program my own?
It supports front matter, but only in a few predefined styles? And it looks like I can't define my own rendering / styling for image blocks? Like, if I want to make images clickable and be shown full screen, I can't do it using quarto?
Like I said in another comment, if you're writing a markdown-like document that can only be rendered properly in one bespoke tool, you're not writing in actual markdown any more. Like if I had my own C compiler with a bunch of custom extensions, code written which uses all of those extensions isn't really C code. With actual markdown, you can send people the markdown content itself and they can render it locally using whatever tool they like.
Use a tool like quarto if you want. But the need for something like this proves the point that markdown on its own isn't sufficient. If you're reaching for a markdown-incompatible document format, why stick with markdown at all, and not React, or ascii doctor, or typst?
People keep reinventing LaTeX, but poorly. Most of the issues described have already been solved by it at least 20 years ago, especially the semantics part. The tooling is mature, well understood and supported on all operating systems.
As far as custom shortforms for fully tagged angle-bracket markup is concerned, people are reinventing SGML which can handle markdown and other custom syntaxes since 1986.
I've been meaning to see how close I can come to Markdown syntax using SGML's SHORTREF and perhaps architectural forms.
Markdown inline syntax is straightforward to capture using SGML SHORTREF. What's more difficult (impossible) are things such as reference links where a markdown processor is supposed to pull text (the title of a link) from wherever it's defined before or after its usage.
Haven't heard about archforms in a while ;) but it's not a technique for custom syntax, and since markdown is specified as a Wiki syntax with canonical mapping to HTML, there's no need for the kind of simplistic element and token renaming possible with archforms.
I've use archforms in my custom markup before: https://r6.ca/HtmlAsSgml.html
For example added an <nbsp> attribute to turn all spaces into non-breaking spaces, and used archforms to remove the attribute afterwards.
But yeah, maybe for Makrdown you don't need archforms. On the other hand, perhaps there is some super clever way to use archforms to get your reference links working.
Not at all. I use to maintain myriad of packages with restructured text, asciidoc, XML, perl pod and tex, but markdown all supercede it.
I could easily represent the long word spec for the DWG format in markdown with gh tables, rendering it to pdf, and it's even better than the original word. Just to represent our diffs.
I could easily produce C++ technical reports in markdown, rendering to pdf and HTML, which was perfect.
The rST docs are much easier to maintain in markdown than in rST.
> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices.
This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain in order to re-create 'the semantic web' - a flawed concept that has failed to catch on.
If the LLM needs context on content that humans don't need, the LLM needs fixing, not the content.
> With Markdown as your source, you can't easily go to another format.
File->Print->PDF.
Was that hard? (I admit it's still bizarre that Chrome puts 'Save As PDF' under Print).
(Apparently you can also go via LaTeX if you love a CLI)
> If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain
AsciiDoc is much better than Markdown for docs intended for humans that are more than short, README type of documents. Any advantage it has for documents intended for LLMs is a side effect of that.
Many consider AsciiDoc being too complex.
The history of tech is full of "X is better than Y. We should use X", only for X to die. It doesn't matter what is better; it matters what is used. For better or worse, Markdown is what is used.
This is the kind of dismissive sneer the HN guidelines advise against.
You can write dev docs for humans and still want machine readability (without caring about whether some LLM can make sense of the docs).
Machine readability is how you repurpose your own documentation in different contexts. If your documentation it isn't machine readable it might as well be in a .doc(x) file.
Markdown won. Simplicity always wins. Markdown is now the de facto documentation format, for better or for worse.
> Why semantic markup matters
> ...
> Web developers already went through all this with HTML. Prior to HTML5, you had <div> as a logical container. But HTML5 introduced <section>, <article>, <aside>, and many other elements that described the content.
Isn't the semantic web super dead? As in dead, buried, and decorated with countless generations of moss and lichen growing on its gravestone?
---
Edit: Huh, I guess it isn't as dead as I thought!
https://claude.ai/share/b4622d93-2724-4310-9cdd-95c99693a007
I find the semantic web stuff is really interesting but it seems to have more success where there are complex up-front data modeling and collaboration requirements, maybe between orgs. There is a Genome database out there for semantic web and I've heard of banks using it in complex fraud detection systems.
Asciidoc corresponds directly to DocBook XML. They're two formats with exactly the same semantics.
I believe that Markdown shines because it is literally human language. It’s the equivalent of tearing a paper sheet from a notebook and writing stuff down. If I wanted formatted, semantic writing, I’d use LaTeX
I'm surprised Pandoc markdown is not mentioned. You can make that semi structured quite easily, and write your own transformations using lua. It's powerful enough to write math papers and export into both pdf and html.
Pandoc is great for resumes too. My static website turns my pandoc resume into pdf and html and they look great
Being held back is the point.. WYSIWYM is a better ideal than more fonts, but it still tends towards trouble. It is hard enough to get engineers to write and maintain small amounts of correct comments without adding boilerplate metadata. I think everyone on this site is familiar with gripes against Jira but they are supposed to take a brain holiday when evaluating documentation mediums? Who is going to make sure previous and next topic are correct after the addition of a new topic? The great thing about absent fields is that they don't end up with bad content.
This is, personally, a controversial topic- I can take both sides of the debate in my head. I use markdown intensely and feel the deficiencies deeply, but wasn't able to see how there are real alternatives given the ecosystem (e.g. Obsidian).
I do think things are ripe for changes in this space.
This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?
What about markdown do you feel limits you in your writing process?
The beauty of markdown is that it’s standardized. If you find your self midway through the book and feel a need to change formats, it’s easy enough to parse and reformat.
> The beauty of markdown is that it’s standardized.
It isn't standardized. And that's the main problem.
Nothing! I was asking from the point of you that you don't know what you don't know.
I wouldn't use Markdown for that.
You're right to start with your requirements. Try to get detailed, like the list @WA wrote out, then match it up with appropriate tech.
I wrote a technical book and I also wanted multiple decent-looking outputs. In my case: HTML, EPUB/mobi, screen and print PDFs. I was struggling with Markdown+pandoc+custom scripts/styles, so I switched to Asciidoc. I wrote about that process here: https://adammonsen.com/post/2122/
Most of the formats came out satisfactory, but there were some gotchas. https://github.com/meonkeys/shb/#%EF%B8%8F-book-formats lists some, and https://github.com/meonkeys/shb/blob/main/issues.adoc has more. Translating from English to German went OK with asciidoc, but it might have been better with docbook and standard translation tools for working with .po files.
Here are two examples where the author used Markdown and the result was beautiful and successful (although layout for printed editions were done with extra/other tooling): http://gameprogrammingpatterns.com , http://www.craftinginterpreters.com . I'm curious if Bob would/will use Markdown for his next book. My process is different than Bob's... I didn't need literate code and I didn't want to do _any_ layout/pre/post-processing, even for print. Asciidoctor worked for this, although there were some compromises (see my links above). Print-ready layout is a lot of work, however you do it.
Is this your first book? Do you have a publisher? Will it be printed on paper? Do you have a developmental editor / proofreader / etc? Do you have a plan for what you'll do after you publish e.g. talks/promos/tour?
Contact me if you want to chat. I'm happy to share my war stories. And good luck!
You need:
- table of contents
- automatic chapter and section numbering
- cross references and automatic tracking of figures, tables etc.
- different styles besides blockquotes such as info sections, warnings, tips
Imho, cross-referencing chapters, pages, figures, tables and the lack thereof in Markdown is the first and most important thing to check how you would like this to be solved.
Pandoc and pandoc-crossref. Or simply use quarto.
Thanks!
You might look at DocBook. I haven't used it in ~25 years, and then only for short documents, and it is XML hence quite verbose.
But it's explicitly targeted at technical documentation. If nothing else, searching for DocBook alternatives might give you some ideas.
Thanks!
My stack is Markdown-Pandora-MiKTeX-PDF with Eisvogel for technical documentation and it works great for my use case. Eisvogel has a “book” typeset.
How about markdown -> PDF (with Typst) -> epub/mobi ?
Thanks! I'll look into that as an option.
Asciidoc
I prefer writing Markdown for notes, e.g. in Obsidian, I think it fits very there. Because now you can easily take your notes to most other note-taking programs, and letting AI interact with these files also works great.
If I needed more context / am writing a paper I'd choose something like Typst, but usually I don't need the additional overhead.
(Btw: The author has a great name!)
The whole point of markdown, really it's whole value preposition is that it has nice looking plain text. And don't get me wrong that is a hell of a value to many people, myself included. Yes it is a terrible markup language, And I would encourage anyone doing serious document work to use a language that provides better semantic structure. But I would also argue that all projects that try to add these structures to markdown are missing the point and destroying it by making the plain text ugly.
I recently moved my personal writing to John MacFarlane's djot. It's a markup language that grew out of his markdown improvements blogpost, where he explored the issues, and possible fixes, he discovered while creating the common mark standard.
I've no regrets since then
https://pdx.su/blog/2025-06-28-writing-in-djot/
Org is pretty good.
org-mode could have had a chance if they had provided tooling outside the emacs ecosystem. But now LLMs have chosen markdown, so it's destined to forever remain an obscurity.
The other options look like garbage tho
Reading all these debates about document structure and formatting and so on is so wearying. I predict as long as we have text written by people the debates will continue. Truly a case of the taste of the writers and producers being a key variable that no one system will uniformly satisfy.
We found Markdown with directives[1] worked well enough for our use case.
[1]: https://talk.commonmark.org/t/generic-directives-plugins-syn...
So I designed TapirMD [1], a new markup language which is still readable but more powerful, to help me (a tech writer) create web content.
[1]: https://tmd.tapirgames.com
I would like to point out that asciidork provides ability to get AST representation of asciidoc. It’s very nice package. Not the author but have used it.
https://github.com/jaredh159/asciidork
Markdown is the McDonalds of writing
Who is this for? I use markdown when I’m getting text from humans. *This* is just 10x easier than <i>this</i>, because I’m typing on my phone.
Markdown is easy to get started with, that's the main selling point.
It's often the choice between Markdown or no documentation at all.
Even worse: social media postings. There are no semantics at all. People use emojis and so to structure the plain text
It really is terrible. I've hated it ever since it was introduced, but it "won" before anyone ever adopted it, because there were webprogramming Apple/DaringFireball fanatics that pushed it everywhere they possibly could, and demanded that you acknowledge it as an ideal outcome.
The Apple/DaringFireball fanatics have gone, and the web programmers learned how to really program because they had node as an option, but we've been stuck with this ugly, limited non-standardized format.
I'm an AsciiDoc partisan. I think we should just standardize a subset of AsciiDoc that does everything that markdown does and let people just implement that subset if they want. AsciiDoc gets a bit hairy when you get into the weeds, but if there were some sort of graduated standard that layered on features, you could learn as slowly as you wanted, and only by necessity. AsciiDoc gives you what you need as a base to automate typesetting basically everthing, as far as semantics go.
edit: I have to admit that I do not like AsciiDoctor, but it's just because I hate introducing Ruby dependencies. The people behind AsciiDoctor seem really great.
The paper makes the point that people keep extending Markdown, badly and incompatibly.
I have been using Markdown for decade(s) at this point, and I have never felt held back. I love Markdown, I use it daily, and I like that it can be instantly understood in its raw format by anyone and rendered cleaning to rich text easily.
Uhh isn't the main strength of md that it's human-friendly to write? Same for yaml. In both cases, dramatically worse for processing, strictly weaker for semantics and rich formatting... And also doesn't make you want to kill yourself when you're editing it by hand.
You lost me at, "XML is not that bad if you are already doing <x>". Verbosity is insane, attribute vs element freedom induces crowd madness. But I do love the data-visiting parts, why can't they somehow get that into Markdown.
I've never struck any off these problems, and in order to use the tools he suggests I'd have to switch out the systems I use that just support markdown
I sometimes make documents that require more complex formatting, so I use html after 20 minutes fucking around in word and getting angry
Tried and trusted process
I'm working on a HTML replacement right now. If I am to believe the author, it would solve her issue (I don't think so). But I don't know if I want to "share". Can I patent it? Good luck with that.
Going off-topic now, sort of.
The Open Source I see just isn't serious. We lose the right to have an opinion about a technology, to steer it, as that right is mediated by money, and it just evaporates, unless you can set the norm by being a major user, like a tech titan.
Markdown is special because we as developers are the users! Though tech titans dictate what we shall use. As developers we are seemingly in a concentration camp where others set the rules, and there is no escape, unless we surrender our work in the name of love, in the presence of those who absolutely don't, government included, and whose basic mode of operation is to make the profit on our work. It's just legalized demoralization, if not outright stealing.
If you're from a developing country you know what I'm talking about. There is no way to be creative and get paid. You are a beggar, no matter your talents. The end result is that human creativity remains untapped. That is the price we as a community pay every day. Heil the rise of AI, so we don't need each other any longer, and the abuse can stop ;-
There's crimes everyday, and we normalize them, if they are done by the trusted and verified, that talk about merit while they hire f*cks to do their bidding. As a community we are a harem, and they come to rape us, err, give us pleasure, whenever they feel like it, and expect us to love it. Well, don't you love your new toys? That is who we are. And we therefore tend to repeat the cycle in our homes, as "men".
In the end the framing as a technical issue is what marks us. It's is the safe zone, where we can deny the real issue, and cope. If you're a member of Nation Procrasti-me, you know what I'm talking about. Nation Procrasti-Me, Where Life Is Denied. And rent-seeking is the truth.
F*ck, how did we get so cooked? We shackled ourselves, duh. We are infants, or else outright dumb, dumb enough to give away our life force, for new toys to play. Worse, we dictate others do so too. That's when we stand on the side of the abuse, confidently like a toddler that just spread his shit all over the place and radiates "how good was that!".
My biggest problem with Markdown is that I hate writing in it. I find messing around with the syntax interrupts my flow.
Are others writing raw markdown/mdx or is there a CMS/Vscode plugin I should be using? (I have a few plugins already but find the writing experience pretty rubbish still)
Eh, we had plenty of such structured document formats in the past. Markdown has won simply because it's much less hassle to write while still being readable without a specialized viewer. Markdown is exactly at the right sweetspot.
As long as your unstructured hassle-free writing just happens to be in the same format accepted by the viewer.
A generic ASCII capable text viewer is enough to read markdown, that's the point ;)
only if the markdown consists of 100% ASCII... unless you have a different definition of "view" than me
is this a poignant satire about programmers?
I went to look up and see if this guy was in his early to mid 20s when I got to this point
> That <Command> tag isn't Markdown at all; it's a React component.
Turns out he's in his 40s, so he lived through ms word, front page and the JavaScript wars; this is almost certainly satire
i think that specific turn off phrase is more of an indicator of llm usage then age imo