mdrise

Background — is Markdown really dying?

In early 2026, Anthropic engineer Thariq published an essay titled "Using Claude Code: The Unreasonable Effectiveness of HTML" that went viral — 929 comments, 3.4K retweets, 14K likes, 10M views:

[ ./thariq-tweet.png — image not found alongside this HTML ]

The core claim:

Whether I'm planning, drafting specs, exploring solutions, reviewing code, or organizing reports — I now do all of it in HTML.

The essay lists five reasons HTML beats Markdown: density, readability, zero-friction sharing, interaction, and joy. Every one of them is true.

But — Markdown isn't dead. It just retreated to "source format."

Read what Thariq actually said: "I rarely hand-edit these files anymore — I use them as specs, reference docs, brainstorming output. If I need to change something, I usually just throw it at Claude."

In other words: AI still writes Markdown. Humans still read HTML.

Markdown retains five functions that HTML can't replace:

So Markdown's position is shifting. The likely future architecture of AI systems looks like this:

AI
 ↓
MD / JSON / AST          ← source format (Git layer)
 ↓
HTML Component Tree      ← render layer (human reading)
 ↓
Human reader

Markdown will gradually become:

• An export format — one source, many downstream artifacts
• A compatibility layer — shaking hands with older toolchains
• A plain-text fallback — graceful degradation when HTML can't render
• A Git layer — version control, diff, review

Not the primary interaction layer. That's HTML — and eventually, per Karpathy, perhaps some directly-generated interactive video.

HTML's weakness is exactly where MD fills the gap

Commenters on Thariq's essay asked the obvious question: HTML is great, but what about version control? HTML diffs are notoriously noisy — change a few lines of content, and the tag, style, and attribute churn drowns out the actual difference. PR review becomes nearly impossible. Thariq himself acknowledged: this is HTML's biggest weakness, with no perfect solution.

But there is a solution — it just isn't on the HTML side.

Keep MD in Git. Render HTML on demand, only when humans need to read it.

.md  →  Git repo (version control / diff / review / source of truth)
 ↓ mdrise (on demand)
.html  →  share / read / email / print (human visual artifact)

This is the most important point in mdrise's design. You don't have to pick a side in "Markdown vs HTML." You let each do what it does best:

• MD does what MD does well: Git diff, portability, no token pollution, source of truth, version control
• HTML does what HTML does well: information density, readability, zero-cost sharing, interaction, reading pleasure

mdrise is the automatic bridge between them: AI writes the .md and commits it to Git; when a human needs to read it, one "make it a webpage" produces the .html. The .html is a disposable visual artifact — regenerate any time, zero cost.

This is what makes the AI era genuinely disruptive — not that Markdown died, but that its role shifted from "primary interaction layer for humans" back to "source format for machines." It's still indispensable; the position just changed.

What this is

A Claude skill. Install it, then ask Claude to convert any .md into a single-file HTML that:

• Preserves every word verbatim — no paraphrasing, no "fixing," no omission. What's in the source is in the HTML.
• Auto-selects visual style — Claude first identifies the content's medium (docs / book page / landing / notebook…) then picks fonts, palette, layout. Not a uniform template.
• Floats a side table-of-contents — auto-generated from H2 / H3, a persistent toggle stays visible as you scroll, scroll-spy highlights the current section.
• Supports 17+ writing scripts — Latin, CJK, Arabic & Hebrew (RTL), Cyrillic, Devanagari, Tamil, Bengali, Thai, Khmer, Burmese, Georgian, Armenian, Ethiopic… each with a font recommendation table, with the Noto family as universal fallback.
• Three anti-slop rules — no Inter / Roboto / Arial, no purple-gradient-on-white hero, no book-page aesthetics on non-literary content.
• Single-file output — all CSS inlined, only external resource is Google Fonts. One .html file you can send as an email attachment.

Not just slapping marked.js + a default Bootstrap theme on it — that turns ugly markdown into ugly markdown rendered. The goal is for Claude to recognize what kind of document this is and pick a visual language that matches: a technical README gets Vercel / Stripe docs vibes, a personal essay gets a printed book page, a product launch gets a Linear-style landing page, an Arabic literary piece gets a right-to-left book page — all auto-decided.

No redundant work — only rerender when the source changed

mdrise treats .md ↔ .html as a maintained mirror pair, not a blind trigger. Each generated HTML embeds a SHA-256 fingerprint of the source in the head:

<meta name="mdrise-source-hash" content="sha256:9c01140d59119d59e0...">
<meta name="mdrise-generated-at" content="2026-05-12T09:08:27Z">

Next time you (or Claude) wants to "make it a webpage", the skill reads the hash from the existing HTML, computes a fresh hash of the current MD, and decides from this table:

This makes mdrise safely idempotent — invoke it as often as you want; it won't churn out a new HTML every conversation that happens to mention the README. That's what "automatic maintenance of a markdown→HTML mirror" actually means.

Why hash instead of file mtime: git clone resets every file's mtime to the clone moment, so mtime is unreliable. Hashes anchor to source content — consistent across clones and devices.

Real-world examples (5 test cases)

Each was rendered both with-skill and as a no-skill baseline. Click any link to see the actual rendered output:

Install

Claude Code CLI

/plugin marketplace add YukiOvOb/mdrise
/reload-plugins

Or install locally:

claude --plugin-dir ./mdrise.skill

Claude desktop / web

Upload mdrise.skill via the skills uploader on claude.ai.

Use

Just talk to Claude:

> turn README.md into a webpage
> render this article as html
> make my notes look nice
> create a project homepage
> 做成网页
> 美化这篇文章

The most natural workflow: after Claude finishes writing a plan.md / report.md, just say "make it a webpage."

When README.md exists in the working directory, any "make it a webpage / homepage / look nice" request auto-routes to this skill — that's a hard rule baked into the skill description.

Design philosophy

Two invariants:

1. Text fidelity — every visual enhancement is additive. Never replace or paraphrase source text.
2. Visual elevation — target is "shareable" quality, not default browser rendering.

Core method: identify the medium first, then pick aesthetics.

• Literary → book page (warm paper + serif body + classical dividers + narrow column)
• Technical → docs site (Stripe / Vercel / Anthropic docs vibe — clean, screen-native)
• Product → landing page (Linear / Resend vibe — modern, designed)
• This boundary is central. Book-page aesthetics belong to literary content only. Using them on technical / product docs is a category error.

Multi-language strategy: identify script first (CJK / Arabic / Cyrillic / Devanagari…), pick fonts that cover it (Noto family as safe default), then handle direction (LTR / RTL) and layout. RTL uses logical CSS (padding-inline-start, etc.), not left / right.

Full design principles: see SKILL.md.

Contributing

Issues and PRs welcome. If mdrise fails on a content type you care about:

1. Open an issue with the source .md and the visual direction you want
2. I'll iterate on the skill using the same 4-step loop (draft → subagent runs → review → revise)

Sponsor / Donate

mdrise is fully open source (MIT). If it saved you time on layout, or you want to support continued polish, buy me a coffee:

• Buy Me a Coffee (international): https://buymeacoffee.com/midasovorh
• WeChat / Alipay:

./donation.png — save your WeChat / Alipay QR image here

Any support welcome: share mdrise with someone who writes README files with Claude, star the repo, or render something beautiful with it and send me the result — that's the biggest encouragement.

License

MIT. See LICENSE.