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.
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.
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.
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.
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.
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 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.
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?
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 ;-)
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)
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.
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
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.
> 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.
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.
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.
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.
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
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.
mdx does tho. you could just not define any components, then you can nest markdown inside html no problem
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.
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.
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.
> 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.
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?
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 ;-)
Wow! TIL!
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)
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 article doesnt consider Typst, which IMO ought to be the first port of call if Markdown isnt sufficient for your needs.
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'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/
[delayed]
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.
> 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.
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
It's interesting to see how Markdown keeps getting more and more use, and even native Windows Notepad support!
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.
Nothing! I was asking from the point of you that you don't know what you don't know.
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.
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.
The paper makes the point that people keep extending Markdown, badly and incompatibly.
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
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