Why I still prefer Markdown over HTML for AI-generated files

Recently, I have seen a trend where people ask AI tools to generate HTML pages instead of Markdown files.

I understand why.

HTML output can look beautiful. You can have nice layouts, colours, diagrams, navigation, collapsible sections, and even small interactive widgets. If you are trying to understand a complicated topic quickly, a well-designed HTML page can be much easier to grasp than a plain Markdown file.

Also, with newer models and larger context windows, the token cost of generating HTML does not feel as scary as it used to.

There are already a few good links on why HTML is gaining traction:

• Using Claude Code: The unreasonable effectiveness of HTML
• Simon Willison's link post on the same idea
• Thariq Shihipar's X post on HTML output

The core point is valid: HTML gives the model a richer canvas.

But I still prefer Markdown for most work-related AI outputs.

HTML is great until you have to share it

The problem starts after the HTML file is generated.

If I am working alone, HTML is probably the best option. I can generate a fancy page, open it in the browser, and enjoy the custom formatting. Diagrams look good. Sections are easier to scan. The whole thing feels polished.

But work is rarely solo.

The moment I want to share it with a teammate, HTML becomes slightly awkward.

What do I send?

• The .html file?
• A zip file with assets?
• A downloaded file that they have to open manually?
• A screenshot?

This is where the experience starts to break.

Asking a co-worker to download an HTML file and open it locally does not feel natural. Sending a link that opens directly is much better. Markdown files fit that workflow nicely because GitHub, GitLab, and many internal tools already know how to render them.

Markdown fits collaboration better

Markdown is boring, but it works beautifully for collaboration.

You can commit a .md file to Git.

You can review it in a pull request.

You can send a GitHub link to a teammate.

You can copy it into Confluence or Google Docs with much less pain.

You can version it, diff it, comment on it, and improve it over time.

That is a big advantage.

With HTML, the first version may look great. But once you need to edit, review, migrate, or publish it somewhere else, it becomes extra work.

Portability is the real issue

This is the biggest pain point for me.

AI-generated HTML does not always port cleanly back to Markdown, Confluence, or Google Docs.

The layout may depend on CSS.

The diagrams may be inline SVG.

The content may be mixed with styling.

The output may look nice in the browser, but extracting clean text from it later is not always fun.

Markdown keeps the content separate from the presentation. That sounds boring, but it is exactly what makes it useful.

A simple way to think about it

Use HTML when:

• You are working alone.
• You want a rich explanation.
• You need diagrams, interactions, or a custom visual layout.
• The output is mainly for reading once.

Use Markdown when:

• You need to share it with a team.
• You want to commit it to Git.
• You want comments and review.
• You may need to move it to Confluence, Google Docs, or a blog.
• The document may evolve over time.

My current preference

For me, the default is still Markdown.

If I need a quick visual explanation for myself, HTML is excellent.

But if the output needs to live longer than one reading session, Markdown is safer.

It is easier to share, easier to edit, easier to review, and easier to migrate.

HTML gives better presentation.

Markdown gives better collaboration.

And in most workplace situations, collaboration matters more.

Final thoughts

Organisations can still make HTML sharing work.

For example, they can enable GitHub Pages for internal projects. In that case, an AI-generated HTML file can be committed to the repository and shared as a normal link. That solves a big part of the problem.

But Confluence is still a hard truth.

It does not support HTML rendering in a simple, native way. Confluence also does not seem to be doing a great job with AI, other than Rovo. If Confluence could safely render HTML pages or HTML-style artifacts, it would be a game changer for teams.

Until that happens, Markdown remains the safer default for collaborative documents.