> 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)
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.
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.
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 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.
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.
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.
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?
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!
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.
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 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.
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.
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 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.
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.
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.
84 comments
[ 5.0 ms ] story [ 91.9 ms ] threadThis 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)
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.
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.
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.
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.
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
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.
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'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.
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!
https://github.com/jaredh159/asciidork
No, seriously, who is this for?
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)
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)!
I do think things are ripe for changes in this space.
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.