HTML > Markdown? The Case for Enriched Structured Content

Anthropic has a recent post on "the unreasonable effectiveness of HTML" as an output format for Claude Code. It's also selling Claude Code, which is worth saying out loud. But underneath the pitch, the underlying point about richer structured content is worth thinking about, and the version of that argument that lands for us in healthcare-informatics work is a little more specific than the marketing post suggests.

The short version: Markdown isn't dead. But plain Markdown is going to start feeling pressure as agents produce richer planning artifacts, review artifacts, explainers, and task-specific editing interfaces. The middle ground we've been exploring is what we call enriched Markdown — keep the simplicity of .md, but add structured YAML front matter and lightweight conventions so the document can be both human-readable and machine-actionable. That feels like the practical tension to live in for a while.

This post is the long version. The healthcare-informatics version, specifically. The one where we use this every day in our rh-skills project, and the conventions we land on there shape how every artifact in the workflow looks.

The obvious point

The case for HTML as an output format is easiest to make for visible artifacts. Things the user is going to look at, click through, or share:

• UI prototypes and mockups. HTML is the most direct path from "describe a screen" to "have a screen." Markdown can't do that without an additional render step.
• Diagrams. SVG embedded inline is genuinely useful, and Markdown's image-link syntax is the opposite.
• Interactive reports and dashboards. When the answer is "the user should be able to filter, sort, and explore," Markdown is the wrong layer.
• Small purpose-built tools. A few dozen lines of HTML and a small script becomes a tool. The same idea in Markdown is a paragraph that says "this would be a tool if it existed."

None of this is new. It's also not the interesting part. The interesting part is what happens when you push past visible artifacts into machine-actionable ones.

The less obvious point

The case for HTML gets sharper when you stop thinking about pixels and start thinking about semantics. HTML is more than presentation. It's a vocabulary for what things are and how they relate:

• Layout and hierarchy — header, nav, main, section, article, aside, footer. Markdown's # and ## are flat by comparison.
• Tables — Markdown's pipe syntax is the most fragile thing in the format. A column with a pipe in it breaks the table. HTML tables don't care.
• Links — Markdown's [text](url) is fine for most cases. HTML's <a> carries rel, target, aria-label, download, hreflang, and a real DOM event model.
• Forms and inputs — Markdown has no form syntax. HTML has the real thing.
• Embedded SVG — Inline SVG gives you shape, color, animation, and accessibility attributes in one container. Markdown's image link gives you a rendered bitmap and nothing else.
• Interactive controls — A button that does something, a select that drives a render, a slider that updates a value. All HTML, none Markdown.
• Semantic attributes — data-* attributes carry structured information that scripts and agents can read. aria-* attributes carry accessibility information that screen readers use. Markdown has nothing analogous.

The reason this matters for agentic workflows is that HTML is closer to a structured document than Markdown is, even when the HTML is mostly the same words as the Markdown would have been. A <table> with <thead>, <tbody>, and <th scope="col"> is something an agent can parse and reason about. A Markdown table is something an agent can guess at.

That's the case the Anthropic post is making, and it's a real case.

Why "Markdown is dead" is still wrong

None of that means Markdown is dead, or even that it's the wrong default. Markdown is wonderful for the things Markdown is wonderful for, and that list is long:

• It is simple. There are essentially no syntax errors in Markdown that don't produce a parseable result. The cost of getting started is roughly zero.
• It is portable. A .md file renders the same way in 50 different tools, and the source is also the readable artifact. That's a property HTML doesn't have.
• It is reviewable in git. Diffs in Markdown are meaningful and human-readable. Diffs in HTML are noise.
• It is easy to edit without special tooling. Anyone with a text editor can write Markdown. HTML requires more discipline.
• It is close to plain text. A Markdown file is also a perfectly fine text file. The same can't be said of HTML.

For many knowledge workflows, Markdown is still the right default. It keeps the artifact close to plain text, reviewable in version control, and easy to edit without special tooling. None of those properties have changed, and none of them are going to.

The thing that's changing is what agents are producing. The output of an LLM in 2026 is much more often a planning artifact, a review report, an explainer, an interactive spec, a task-specific editor — and those have always strained Markdown. They strain it more now because there's more of it, and because the workflow is asking the artifacts to do more.

The middle ground we've landed on

The middle ground we keep returning to is what we call enriched Markdown. The shape of it is:

• A .md file as the artifact. So you still get plain-text portability, git diffability, and zero-tooling edits.
• Structured YAML front matter at the top. This is where the document declares what it is, what it's about, what status it's in, what links to it, and what an agent should be able to find in it without re-parsing the prose. This is the part that makes it machine-actionable without making it machine-only.
• Lightweight conventions in the body for things Markdown doesn't natively support. A consistent way to declare a "this is a decision," a "this is open question," a "this is a finding," a "this is a deferred follow-up." None of these are required by Markdown, all of them are things an agent can extract, and none of them break readability for humans.

Concretely, the front matter might look something like:

1---
2title: 'T2DM denominator review'
3type: structured-review
4status: in-review
5topic: t2dm-quality-measure
6linked_artifacts:
7  - lib/CqlLibrary-T2DM-1.0.0.json
8  - vset/ValueSet-T2DM-ICD10-1.0.0.json
9reviewers:
10  - clinical-lead@health.org
11  - informaticist@reason.health
12findings: 3
13open_questions: 2
14deferred: 1
15generated_by: rh-skills extract --topic t2dm-quality-measure
16---

That block is doing real work. An agent reading the file knows the type, the status, what it links to, who owns it, and what to look for. None of that required an HTML renderer. None of it required a custom file format. The body of the document is still plain Markdown, and the prose is still the prose.

A full file in this convention looks something like this — a structured review of a type-2 diabetes quality measure, with a few findings, an open question, and a deferred follow-up:

1---
2title: 'T2DM denominator review'
3type: structured-review
4status: in-review
5topic: t2dm-quality-measure
6linked_artifacts:
7  - lib/CqlLibrary-T2DM-1.0.0.json
8  - vset/ValueSet-T2DM-ICD10-1.0.0.json
9reviewers:
10  - clinical-lead@health.org
11  - informaticist@reason.health
12findings: 3
13open_questions: 1
14deferred: 1
15generated_by: rh-skills extract --topic t2dm-quality-measure
16generated_at: 2026-05-18
17---
18
19# T2DM denominator review
20
21A structured review of the proposed CQL library and value set for the
22T2DM quality measure denominator. The intent is to confirm that the
23denominator captures the right population before this library moves to
24the formalize step.
25
26## Scope
27
28This review covers `CqlLibrary-T2DM-1.0.0` and its referenced
29`ValueSet-T2DM-ICD10-1.0.0`. The numerator and exclusion criteria are
30out of scope here and will be reviewed separately.
31
32## Source
33
34Denominator criteria are derived from the measure specification
35(NQF-0059) and the 2024 ADA Standards of Care, §6.
36
37## Findings
38
39### Finding 1: E11.9 ("Type 2 diabetes mellitus without complications") is over-inclusive
40
41The current value set includes `E11.9` in the denominator. Per the
42measure intent, patients with T2DM without complications should be
43excluded — they are not the population the measure is targeting. This
44will pull in a large number of patients who don't meet the measure's
45clinical criteria.
46
47**Suggested change:** Remove `E11.9` from `ValueSet-T2DM-ICD10-1.0.0`
48and require at least one of the complication codes for inclusion.
49
50**Severity:** blocking
51
52**Confidence:** high
53
54### Finding 2: Secondary diabetes codes (E08, E09) are not represented
55
56The value set covers `E11.*` only. The measure intent is "diabetes
57mellitus," not "type 2 diabetes mellitus" specifically, and the
58clinical lead has confirmed that secondary diabetes should be in
59scope.
60
61**Suggested change:** Add `ValueSet-T2DM-SecDiab` covering `E08.*` and
62`E09.*` and include it in the denominator.
63
64**Severity:** blocking
65
66**Confidence:** medium — needs clinical sign-off on the secondary
67diabetes inclusion criterion.
68
69### Finding 3: The CQL expression uses `Condition.code` but doesn't constrain by clinical status
70
71The CQL retrieves "all T2DM diagnoses" but doesn't filter by
72`Condition.clinicalStatus` (active vs. resolved). This will include
73historical diagnoses that aren't currently active.
74
75**Suggested change:** Add a `Condition.clinicalStatus = 'active'`
76filter to the denominator query.
77
78**Severity:** should-fix (not blocking)
79
80**Confidence:** high
81
82## Open questions
83
84### Question 1: Gestational diabetes boundary
85
86Should gestational diabetes (`O24.*`) be included in the denominator?
87The source measure is silent on this. The current value set excludes
88it by virtue of not including any `O` codes, but the rationale is
89unstated.
90
91**Owner:** clinical-lead@health.org
92**Blocks:** sign-off
93
94## Deferred
95
96### Follow-up 1: HbA1c timing constraint
97
98The measure spec calls for "most recent HbA1c in the measurement
99period." The CQL currently doesn't enforce a temporal constraint on
100the HbA1c lookup. This is technically a numerator/exclusion concern,
101not a denominator concern, so we're parking it for the numerator
102review.
103
104**Tracker:** t2dm-quality-measure/numerator-review
105**Target:** next review cycle
106
107## Sign-off
108
109When all blocking findings are resolved and the open question is
110answered, this document moves to `status: approved` and the linked
111artifacts can be promoted to the formalize step.

A few things to notice in that example:

• The front matter is the index. An agent that only reads the front matter knows the doc is a structured review, in review, on T2DM, links to two artifacts, has two reviewers, and contains 3 findings, 1 open question, 1 deferred item. None of that required parsing prose.
• The body uses simple, consistent headings. # for the document, ## for sections, ### for individual findings, questions, and deferred items. A regex or a small parser can extract them deterministically. The headings are also still readable as a document.
• Each finding carries the same shape: a one-paragraph problem, a suggested change, a severity, and a confidence. That shape is what makes the convention machine-actionable. The agent doesn't have to guess where the action item is — it's always under "Suggested change."
• The body has no custom syntax. It's all standard Markdown. If the front matter is stripped, the body is still a valid plain Markdown document. If a future reader doesn't know the convention, the prose still makes sense.

By contrast, the same document in HTML would be a <article> with a <header> and a <dl> of metadata and a <section> for findings. That's not wrong, but it's not a better artifact. It's a different artifact, with a different set of tradeoffs, and a different blast radius when it gets opened in five years by a tool nobody maintains.

Where we use this in practice

We use enriched Markdown as the primary artifact format in our open-source rh-skills project — an agentic workflow toolset for clinical informaticists. The toolset turns narrative clinical source material (guidelines, measures, assessments, prior authorization policies) into deterministic, computable rules. The intermediate artifacts — what we call the structured layer, between raw source and final FHIR — are enriched Markdown files.

The reasons we picked enriched Markdown specifically are pretty much the list above:

• They're reviewable. A clinician or informaticist can open a structured review, read it like a document, and leave comments inline in the same tool they review prose in. The git diff between two review versions is meaningful to a non-engineer.
• They're parseable. A skill that needs to know "is this review still in progress, and who are the reviewers" can read the front matter without parsing the prose. A skill that needs to extract findings can match a convention rather than a free-text pattern.
• They survive a tool change. If we replace the toolset next year, the structured reviews are still readable. They're still diffable. They're still actionable by a future agent with no knowledge of our current implementation.
• They don't lock us in. If a downstream tool needs a real HTML version for a specific use case, we can render the Markdown to HTML without losing any structured information. The front matter becomes a JSON-LD sidecar or a <script type="application/ld+json"> block in the HTML.

This is going to get its own post — there's a lot to say about how the structured layer of rh-skills is shaped and what we're learning from shipping it — but the format choice underneath it is the enriched Markdown pattern, and it's holding up well.

When to use which

A rough guide, since this is the part people actually ask about:

Use plain Markdown when the artifact is:

• A long-form doc where the prose is the artifact (a spec, a policy, a README, this post)
• Something that will be read more than it's processed
• Something that needs to survive a tool change with no migration
• Anything you want a non-engineer to be able to edit without thinking

Use HTML when the artifact is:

• A user-facing interface (mockup, dashboard, interactive report)
• Anything where layout, semantic structure, or interactive controls are the point
• A document that will be parsed by tools that expect HTML (browsers, screen readers, web crawlers)
• A one-off that doesn't need a long-term artifact strategy

Use enriched Markdown when the artifact is:

• A review, a planning doc, an explainer, a structured report
• Something that needs to be readable by humans and parseable by agents
• A document that will be the input to a deterministic tool later
• Anything that will be reviewed in version control and acted on by both humans and tooling

Use MDX (or a similar Markdown-with-components extension) when:

• The components you need are stable and reused
• The render target is a specific runtime (Next.js, Gatsby, etc.)
• The audience is the same runtime's consumers

Use a fully custom format (YAML, JSON, JSON-LD, FHIR resources) when:

• The artifact is data, not a document
• The downstream is a deterministic pipeline, not a human or a generic agent
• A schema can be specified up front

The interesting slice is the enriched Markdown row. That's the one that didn't really exist before agents — because before agents, the only consumer of a "structured doc" was a human, and humans are pretty good at inferring structure from prose. The agent side of the loop is what's pushing us to make the structure explicit.

The part under the part

The Anthropic post is right that HTML is unreasonably effective as an output format, and it's right that the reason isn't just visual. The semantic layer of HTML is real and useful and agents will keep finding it useful.

But the post is also pitching a specific tool, and the framing of "HTML everywhere" misses the part where plain Markdown is doing a lot of uncelebrated work. Most of what gets written, reviewed, and shipped in a software project is documentation, not interface. For that work, Markdown's simplicity, portability, and review-friendliness aren't bugs to be worked around. They're the feature.

The right move is the middle: keep Markdown as the substrate, add structure where structure helps, and reach for HTML when the artifact is genuinely a UI. Enriched Markdown is the convention we've landed on, and it's the one we're building on top of in the work that's most likely to matter for healthcare informatics in the next few years.

If you're working on agent-produced artifacts, structured reviews, or docs-that-need-to-be-machine-actionable, give the middle ground a try. It's not a framework. It's a few lines of YAML and a handful of conventions. The hard part is deciding to be explicit. The rest is just typing.

And if you want to see this convention used at scale in a real project, rh-skills is the example. We'll talk more about it soon. Until then, write the front matter. It costs you a minute. It saves whoever comes next — human or agent — an hour.