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.
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.