I've used many content formats over the years, and while I love Markdown, I run into its limitations daily when I work on larger documentation projects.
In this issue, you'll look at Markdown and explore why it might not be the best fit for technical content, and what else might work instead.
Markdown Lacks the Structure You Need
Markdown is everywhere. It's human-readable, approachable, and has just enough syntax to make docs look good in GitHub or a static site. That ease of use is why it's become the default choice for developer documentation. I'm using Markdown right now to write this newsletter issue. I love it.
But Markdown's biggest advantage is its biggest drawback: it doesn't describe the content like other formats can.
Think about how your content gets consumed. Your content isn't just for human readers. Machines use it too. Your content gets indexed by search engines, and parsed by LLMs, and those things parse the well-formed HTML your systems publish. Markdown's basic syntax only emits a small subset of the available semantic tags HTML allows.
IDE integrations can use your docs, too. And AI agents rely on structure to answer developer questions. If you're only feeding them plain-text Markdown documents to reduce the number of tokens you send, you're not providing as much context as you could.
Worse, when you want to reuse your content or syndicate content into another system, you quickly find out that Markdown is more of the lowest common denominator than a source of truth, as not all Markdown flavors are the same.
There are other options you can use that give you more control. But first, let's look deeper into why you should move away from Markdown for serious work.
Markdown is "implicit typing" for content
... continue reading