You can do footnotes in markdown [^0]

[^0]: it doesn't matter where this is placed, just that this one has a colon.

The table of contents thing is annoying but it's not hard to write a little bash script. Sed and regex are all you need.

  > Markdown doesn't have enough features

Markdown has too many features

The issue is you're using the wrong tool. Markdown is not intended for making fancy documents or blogs, it's meant to be a deadass simple format that can be read in anything. Hell, its goal is to be readable in a text editor so its more about styling. If you really want to use it and have occasional fanciness, you can use html.

But don't turn a tool that is explicitly meant to be simple into something complicated just because it doesn't have enough features. The lack of features is the point.

> The issue is you're using the wrong tool.

Yes, I think we're in violent agreement that markdown is the wrong tool for the job. That's why I find it baffling how so many blogging & documentation tools lock you in to using markdown, with its anaemic feature set (eg mdbook).

Even markdown + inline HTML is wildly inadequate. For example, you can't make automatically numbered sections. Or figures with links in the text. Or a ToC. And so on. Try and attach a caption to an image and you're basically hand authoring your document in crappy HTML.

So I agree with you. I don't think the answer is "markdown++" with comments, templating and scripting support. I think the answer is something else. Something which has considered the needs of authoring documents from the start. Something like typst.

  > That's why I find it baffling how so many blogging & documentation tools lock you in to using

I feel this about so many things and it boggles my mind why people often choose to do things the hardest way possible.

Honestly, I think a good portion of it of the unwillingness to toss something aside and write something new. If it's just a hack on a hack on a hack on a hack then no wonder it's shit. It's funny that often it's quicker to rewrite than force your way through.

I'm worried that with LLMs and vibe coding on the rise we're just going to get more. Because people will be asking "how do I make X do Y" when in reality you shouldn't ever make X do Y, you need to find a different tool.

> I'm worried that with LLMs and vibe coding on the rise we're just going to get more.

I'm hoping the opposite, at least eventually. I think before long it'll be easy to get chatgpt to build your own version of whatever you want, from scratch.

Eg, "Hey, I want something kinda like markdown but with these other features. Write me the spec. Implement a renderer for documents in Go - and write a vs code extension + language server for it."

But if that happens, we'll get way more fragmentation of the computing ecosystem. Maybe to the point that you really need the memory of a LLM to even know what's out there - let alone understand how to glue everything together.

You missed my concern. Even if LLMs get much but it doesn't mean the users will ask the right questions. Even now many don't ask the right questions, why would it be any better when we just scale the issue?

MDX as a middle ground with most of the text standard markdown and the escape hatch of custom React JSX when needed has worked well for me.

MDX advertises itself as "markdown + components", but its not commonmark compatible. I tried using it a few years ago. In the process, I migrated over some regular markdown documents and they render incorrectly using MDX.

I filed a bug (this was a few years ago) and I was told commonmark compatibility was an explicit non goal for the project. Meh.

I didn't know that, that is unfortunate to hear.