It’s so funny to me that people spend all this effort trying to explain to you that markdown is bad.

Listen pal, I know it’s bad–I have to use it all the time! I’m not using it because it’s good. That’s not what’s going on here at all.

I feel like this is coming full circle to XML again. The PortableText format seems like an awkward way to write XML in JavaScript. And now we get to rediscover the world of namespaces and schemas and validation.

Markdown certainly has its limitations, and I’m open to trying other lightweight markup languages. AsciiDoc looks particularly interesting. But this article also seems to be criticizing the dominance of lightweight markup languages in general, and that’s what I want to push back against.

I think what I like most about writing in a lightweight markup language is the complete transparency of plain text. As long as I’ve got the syntax correct, I know there will be no surprises when it comes to document structure or presentation. And if I make a mistake, fixing that is always a simple matter of adding, removing, or replacing characters. It’s just so simple and predictable, compared to working with a WYSIWYG editor, whether it’s Microsoft Word, the Thunderbird HTML email composer, or something else. Maybe my visual impairment has something to do with my discomfort with WYSIWYG editors. Then again, I do have enough sight to see how the document looks. Still, I’m slow at using the mouse, and I never learned all the keyboard shortcuts for Word, never mind other editors.

It’s true that most non-developers aren’t comfortable with markup languages. But maybe that just means we need to teach the next generation while they’re still young enough to pick up new things easily.

Perhaps the problem is picking markdown for something it’s not optimized to do.

I love markdown. I love the fact that I can write my novel in a text editor and get the little bit of formatting I need via easy to type characters. I love that my files are plain text, not some franken markup, nor some franken binary.

I love my markdown for write ups that are overwhelmingly text and don’t need font or color changes.

If I had to embed a ton of images and forms and videos I would be using some ephemeral WYSYWIG platform that’ll last just a bit longer than the usefulness of my content, what with all the associated media and all. That’s when I wouldn’t be using plain text.

Even CommonMark implementations don’t behave quite the same. Even different implementations both maintained by John McFarlane don’t behave exactly the same! (I’m tempted to add more than one exclamation mark here, but I won’t ;)

$ pandoc –no-highlight -f commonmark -t html

print("hello world")

^D

<pre class="python"><code>print(&quot;hello world&quot;)</code></pre>

$ cmark
```python
print("hello world")

^D

<pre><code class="language-python">print(&quot;hello world&quot;)
</code></pre>

If you are using an external syntax highlighter, it will break if you switch from cmark to pandoc and vice versa, unless you make pandoc behave the same as cmark (at least that’s possible with Lua hooks).

Using Markdown as if it were a protocol language or exchange format is what sucks. Just use it as a tool for yourself to quickly generate data for a more robust format. gemini://idiomdrottning.org/markdown-good

This article seems to be aimed more toward the CMS crowd, but I have one piece of advice for them:

Text is timeless. I can dig out text files from my 1990 DOS computer’s archive, and they’re just as readable as they were then. In my first few years on the mac, I tried out a few “modern” technologies like RTF and now all those files are just binary garbage. (I’m sure I can read them in the future with some decoder app, but for now, they’re just garbage.) I went back to plain text and “commonmark” because I could write a blog post in 2008 and feel confident that I’d still be able to read and edit it 15 years later. (Prediction was correct!)

I suspect that a lot of people who prize commonmark don’t particularly love it, but have had bad experiences with the various fad structured formats over the years, and started thinking long-term. If/when the commonmark fad ends, these files will still be readable and editable by people who have never heard of it, and that matters more to me than having native support for video links to a commercial website.

Conversations in this domain can be frustrating because there are a lot of different/overlapping interests and historical currents.

I think the one that’s probably the most fundamental and maybe intractable is that on one hand there are many impressive towers-of-babel that we can build with a few CPUs and some semantics to rub together, and on the other–people do not semantic well.

(To be very clear, I’m speaking generally and not in a “Semantic Web” sense.)

There’s a whole nest of reasons we don’t semantic well, but some big ones are:

• semantics are hard
• semantics get harder as you add more brains
• we have a ~legacy of writing practices/formats/tools (for the page, word processors, WYSIWYG tools, LWMLs, etc.) that have poor semantic fidelity and are often laden with distracting presentational features; this ensures vanishingly few people have been forced to semantic well

That said, I think there are some seams to pick at. One thing that could change the weather is more emphasis on building tools that deliver enough visible value to the people doing the authoring to get them to buy in.

I’ve been working on a weird little semantic-first documentation single-sourcing platypus, myself. To the point where I’ve recently started dogfooding it in the real project I started building it to document.

Impressive to get through an entire article on the limitations of and alternatives to markdown without once mentioning restructuredText! I’m writing the new version of learntla in Sphinx/rST and oh my god it is so much better. Unambiguous formatting! Uniform extensive mechanisms! Semantic markup! Intermediate representations! I’ve started even writing my own custom directives and roles and it’s solving problems I didn’t even know I had.

none of his points convincing at all. I think that commonmark is the best.

KeenWrite is my text editor that takes a slightly different approach than MDX. Rather than include variable definitions within documents, variables are defined in an external file. I find that when variables are embedded into documents, those variables often include controls for presentation logic. To me, any presentation logic meant to affect a plain text document’s appearance does not belong in the document itself. Part 8 of my Typesetting Markdown series shows the power of separating content from presentation by leveraging pandoc’s annotation syntax.

Annotated Markdown is sufficiently powerful to produce a wide variety of different styles. Here are a few such Markdown documents typeset using ConTeXt:

• Fire and Ice
• Jekyll and Hyde
• Impacts
• KeenWrite Screenshots

What’s bothersome is how some companies are setting de facto Markdown standards without considering the greater ecosystem. GitHub has done this by introducing the “``` mermaid” syntax, which creates some problems.