HTML, markdown, and your page's other machine reader

Two kinds of machine read your page, and they take opposite halves of it. A link-preview crawler reads the <head>, extracts about a dozen meta tags, and never touches the body. An agent fetching your page to answer a question does roughly the reverse: it takes the document, flattens it to text or markdown, and drops the head — including every Open Graph tag you wrote.

So the work that produces a good card does nothing for the second reader, and the parts of your page that reader depends on are ones nobody checks before publishing.

Two extraction shapes

The card shape is head-only and has a fixed output schema: title, description, image, URL, type. It is a lookup, not a reading. Nothing in your body can influence it except as a fallback when the tags are missing.

The text shape is whole-document. The HTML gets converted to something plainer — headings, lists, links and paragraphs preserved, markup discarded — and that text is what gets summarised or quoted. This conversion is a commodity operation rather than anything exotic: Serply’s page-fetch endpoint that returns raw HTML or markdown does both from a single GET, which is about the level of engineering involved.

The important consequence is that the second shape has no slot for your metadata. There is nowhere in a markdown document for og:description to live.

What survives the conversion

Roughly, and with variation between converters:

Visible headings survive, and carry structure. Your h1 usually becomes the document’s title.
The first visible paragraph survives, and does the job og:description does on a card — it is what a summariser reads first.
Link text survives; the URL usually does too.
Image alt text survives, often as the only trace the image was there at all.
<head> metadata does not. Not og: tags, not twitter: tags, frequently not <title> either.
JSON-LD usually does not — it lives in a <script> tag, and scripts are the first thing dropped.
Anything rendered by JavaScript does not, for the same reason it never reaches a preview crawler.
Navigation and footer chrome often does, unhelpfully, unless your markup gives the converter a <main> or <article> to prefer.

What to do with that

Say the summary in visible copy, not only in a meta tag. If the only place your page states what it is about is og:description, then one reader has that sentence and the other has whatever your opening paragraph happens to be. Write the opening paragraph as though it were the description, because for half your machine audience it is. It should also agree with the card’s wording — two machines describing your page differently is a self-inflicted problem.

Keep h1 and og:title in agreement. They can differ in length and phrasing; they should not differ in claim. A card promising one thing and a converted document containing another reads as a mismatch to anything comparing them.

Write alt text as description, not as a label. On a card, og:image has no accessible text unless you add og:image:alt. In a converted document, alt text is the entire image. “Chart” tells both readers nothing; a sentence naming what the chart shows serves both.

Prefer semantic containers. <main>, <article>, <nav> cost nothing and give a converter a way to drop your navigation instead of pasting it in front of your content.

Anything behind an interaction is invisible to both. Content in a collapsed accordion, a tab panel populated on click, or a modal is not in the document either machine received.

Should you publish markdown yourself?

Some sites now serve a .md copy of each page alongside the HTML. It is a reasonable experiment, and it is not a substitute for the above: there is no settled convention for how a fetcher would discover the markdown version, it is a second artifact to keep synchronised with the first, and the conversion it saves is already cheap and already being done by the consumer.

The higher-yield version of the same instinct is HTML that converts well: real headings in order, no layout tables, text as text rather than baked into images, and the main content inside one container.

What hasn’t changed

The head still matters exactly as much as it did. Cards are still built from meta tags, still cached, still the thing a human sees before deciding whether to click. Nothing here argues for spending less time on Open Graph.

What is new is that the head is no longer the only machine-readable surface your page has, and the other one is made of the words you can already see. That is a pleasant sort of requirement: writing a clear first paragraph and honest alt text is work that pays off in both directions at once.