Glaze Glaze
  • Docs
  • Why Not Markdown?

Why not Markdown? #

Glaze uses Djot instead of Markdown. This page explains why and what that means in practice.

Djot support is provided by php-collective/djot-php.

The core reason: Markdown is ambiguous #

Markdown’s grammar has real parsing ambiguities. Different renderers make different choices, which is why there are so many flavors: CommonMark, GitHub Flavored Markdown, Pandoc, Kramdown, and dozens more. A page that renders correctly in one flavor may render differently in another.

Djot was designed by John MacFarlane (the author of pandoc and CommonMark) specifically to fix these ambiguities. The parsing rules are fully specified and unambiguous.

Practical differences #

Emphasis #

Markdown uses * and _ for emphasis with complex precedence rules. Djot uses _ for emphasis and * for strong, always:

Markdown: *italic* **bold** _also italic_
Djot:     _italic_ *bold*

Raw inline HTML vs. attributes #

In Markdown, you drop to raw HTML to add attributes. Djot has a clean attribute syntax built in:

[link text](url){.class #id target=_blank}
![image](photo.jpg){width=800}

No raw HTML needed.

Code spans and fences #

Djot code handling is more predictable – no special-case rules for backtick counts or indented code blocks.

Pipe tables #

Djot has pipe table support as a standard extension, consistent across implementations.

What stays the same #

  • You still write plain text files
  • Headings use #
  • Bullet lists use - or *
  • Links are [text](url)
  • Images are ![alt](url)
  • Bold/italic use _ and * (just with swapped meaning)

The learning curve for Djot is minimal if you already know Markdown.

Is Markdown bad? #

No. Markdown is simple, widely supported, and perfectly suitable for many use cases. If your content is minimal and your rendering environment is fixed, Markdown is fine.

Glaze chooses Djot because it scales better for structured content pipelines where consistency and reliable attribute handling matter.

Resources #