You’ve spent hours debugging a markdown file that looks perfect in your editor but breaks on GitHub. You’re not alone — and it’s not your fault. The problem isn’t you. It’s markdown itself.
Markdown was supposed to be the simplest way to write formatted text. No complex tags, no WYSIWYG bloat. Just plaintext with a few readable symbols. But somewhere along the way, that simplicity became a trap. Every parser, every platform, every tool interprets markdown slightly differently. What works in Obsidian breaks in Notion. What renders fine in GitHub issues chokes in Jekyll. And every developer has wasted hours chasing these phantom bugs.
Markdown’s greatest strength — its informal flexibility — is also its greatest curse. The very thing that made it beloved is now the source of an invisible tax on productivity. We accepted inconsistency as the price of convenience. But what if we didn’t have to?
Enter Creed. It’s not another parser, not another flavor, not another attempt to patch the problem. Creed is a canonical specification — a single, unambiguous, authoritative definition of what markdown is. Think of it as the constitution for plaintext markup. No more guessing. No more ‘works on my machine.’
I saw this firsthand when I tried to migrate a documentation repo from one static site generator to another. The same markdown file rendered differently in three different places. Lists got mangled. Code blocks lost their syntax highlighting. Links broke. And the worst part? No one could tell me what the ‘correct’ behavior was supposed to be. Because there is no correct behavior — only what each tool decides.
We didn’t need yet another parser. We needed a law. Creed is that law. It defines, down to the character, how markdown should be parsed. It eliminates the ambiguity that has cost developers millions of hours in debugging and tooling workarounds. It’s not a competitor to existing markdown implementations; it’s the foundation they should all be built on.
But here’s the twist. The very thing that made markdown explode — its informal, human-readable nature — is what makes standardization so controversial. Critics will say that a rigid spec kills the spirit of markdown. That it turns a friendly tool into a bureaucratic nightmare. That the beauty of markdown was that you could just write, and it would ‘just work.’
That’s a comforting lie. It never ‘just worked.’ It worked by accident, until it didn’t. The informal nature didn’t make markdown more accessible; it made it unreliable. Every time you assumed one thing and your tool assumed another, you paid the price. The only reason we tolerated it is because we had no standard to compare it to.
Creed doesn’t kill the spirit of markdown. It preserves it. By giving us a single correct answer, it frees us to focus on what matters: writing. No more side quests into rendering bugs. No more ‘let me check how GitHub handles this.’ Just plaintext that works everywhere, every time.
This is not a minor improvement. It’s a paradigm shift. The future of plaintext depends on whether we can agree on what ‘bold’ actually means. And for the first time, someone has the courage to say: ‘This is what it means. Now let’s build on that.’
So the next time you spend an hour fixing a markdown table that refuses to render, remember: the problem isn’t you. It’s the lack of a standard. And Creed is the antidote.
FAQ
Q: Isn't markdown already standardized? Why do we need another one?
A: No, markdown has no official standard. John Gruber's original description is intentionally vague, and every parser implements its own interpretation. Creed seeks to create a single authoritative spec that all parsers can adopt.
Q: What does this mean for me as a developer?
A: If you write documentation, comments, or any plain-text content that moves between tools, a canonical standard means you'll never have to debug rendering inconsistencies again. Your markdown will work identically everywhere, saving you time and frustration.
Q: Won't a rigid spec kill the simplicity that made markdown popular?
A: No, it does the opposite. By removing ambiguity, it makes markdown actually simpler because you don't have to remember edge cases across different tools. The informal flexibility was an illusion of simplicity that caused real complexity. A clear spec reduces cognitive load.