> 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.
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?
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.
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?
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?
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.
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.
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.
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
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.
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.
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 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.
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.
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)
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
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.
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 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.
> 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)
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.
> 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.
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.
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!".
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 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.
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.
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.
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.
- 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.
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.
> 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.
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'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
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.
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?
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?
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?
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.
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
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.
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
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.
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.
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.
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
> 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.
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.
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 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.
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.
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)
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.
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/
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.
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 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 interesting to see how Markdown keeps getting more and more use, and even native Windows Notepad support!
Asciidoc corresponds directly to DocBook XML. They're two formats with exactly the same semantics.
We found Markdown with directives[1] worked well enough for our use case.
[1]: https://talk.commonmark.org/t/generic-directives-plugins-syn...
> 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)
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.
> 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.
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.
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!".
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 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.
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.
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
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.
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.
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!
How about markdown -> PDF (with Typst) -> epub/mobi ?
Thanks! I'll look into that as an option.
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!
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.
> 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!
Markdown is the McDonalds of writing
The other options look like garbage tho
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.
The paper makes the point that people keep extending Markdown, badly and incompatibly.
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
> 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.
Markdown won. Simplicity always wins. Markdown is now the de facto documentation format, for better or for worse.
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