The problem I have with Markdown is its lack of standardization. I know there is CommonMark but CommonMark is a classic case of https://xkcd.com/927/
Every Markdown spec differs from others in one way or the other and there is no way to tell that if the Markdown documents I am writing today will convert to PDF, HTML, etc. in exactly the same way 10 years later as they are converting today.
Two Markdown specs may end up converting the Markdown into different types of HTML and PDF -- sometimes even with semantic changes like nested lists in one spec is broken list in another one. Nothing is more displeasing than seeing a carefully written nested lists appear as ugly code blocks within lists because a different Markdown spec does not support nested lists the same way as the first Markdown spec I was using. This is just one of many examples where Markdown for one spec can break in another spec.
If you are strictly going to stick with Hugo forever, then that's fine. But how many of us can guarantee that we want to keep using the same tool to render our Markdown for ever? I certainly can't! I really wish there was a simple documentation format that with a single spec with a large number of implementations -- something like the C89 of text formats. Is there one?
I know this doesn't solve your problem directly, but I recommend people to try out Djot[0], a markup language from the author of CommonMark.
Djot has a single well-defined spec, and most of the basic formatting has the same syntax as (a) Markdown, so switching is pretty painless. It has as a main goal to be legible and visually aesthetic as-is, just like Markdown.
What Djot adds is its _predictability_. Nested formatting, precedence order, line breaks behavior, nested blocks, mixed inline and block formatting, custom attributes are all laid out precisely in the spec in a thought-out manner. Till this day I still can't remember how to put line break within a list item in Markdown (and I'm sure there're more than one way).
I have been keeping markdown notes for 10 years and have never had issues. I suspect the last 10 years is a decent predictor for the next 10 years, given the existence of github as a fairly strong touchstone.
I have lately been rendering everything as HTML using hugo + mathjax.
> If you are strictly going to stick with Hugo forever, then that's fine. But how many of us can guarantee that we want to keep using the same tool to render our Markdown for ever? I certainly can't!
The problem I have is that I don't want to lock myself into one single Markdown renderer like Hugo or whatever it uses internally. I'd like the flexibility to change tools later without worrying that the new tool may break the rendered output.
Like I said, not even something as basic as nested lists are rendered the same way by all tools. What is rendered as nested list by one tool is rendered as a broken list with unexpected code blocks interspersed between them.
A single spec consistently implemented by all tools could fix these issues. Sadly such a spec does not exist in the Markdown world. That's really why I was looking for something like C89 of the Markdown world.
That makes sense. I did ninja edit, probably as you were commenting, about how I've been using 10 years and only lately like hugo, but have no issues regardless.
Github has been fairly stable as a markdown center of gravity. That works fine for me too.
For me, I don't find the need for 100 year compatibility to be a stopping point. 10-20 years is far away enough for me, otherwise the perfect becomes the enemy of good.
Every Markdown spec differs from others in one way or the other and there is no way to tell that if the Markdown documents I am writing today will convert to PDF, HTML, etc. in exactly the same way 10 years later as they are converting today.
Two Markdown specs may end up converting the Markdown into different types of HTML and PDF -- sometimes even with semantic changes like nested lists in one spec is broken list in another one. Nothing is more displeasing than seeing a carefully written nested lists appear as ugly code blocks within lists because a different Markdown spec does not support nested lists the same way as the first Markdown spec I was using. This is just one of many examples where Markdown for one spec can break in another spec.
If you are strictly going to stick with Hugo forever, then that's fine. But how many of us can guarantee that we want to keep using the same tool to render our Markdown for ever? I certainly can't! I really wish there was a simple documentation format that with a single spec with a large number of implementations -- something like the C89 of text formats. Is there one?