Metadata That Matters

xxx

Mar 6, 2026

3 min read

I shared a bloq post on LinkedIn and saw my homepage title instead of the article title. Embarrassing. So I learned how to tell platforms what my content actually is.

#nextjs

#seo

#reflections

The Problem

"A page without metadata is a stranger at its own party."

So I shared one of my bloq posts on Telegram. The preview card showed:

That's my homepage. Not the article. Every single bloq post had the same preview because I never told platforms what each article was actually about.

The content was unique. The code was thoughtful. But to Twitter, LinkedIn, Google, every post looked identical. I'd built the reading experience. The discovery experience? Completely ignored.

Classic me. Built the fun part, forgot the boring part that makes the fun part discoverable.

How Link Previews Actually Work

When you paste a URL into Twitter or LinkedIn, here's what happens:

The platform doesn't read your beautiful prose. It doesn't care about your carefully crafted opening paragraph. It looks for specific meta tags in the HTML <head>. If those tags exist, great, nice preview. If not, the platform guesses, and let me tell you, platforms are terrible guessers.

OpenGraph

Facebook created OpenGraph in 2010. The idea: webpages can describe themselves in a language platforms understand.

When someone shares your link, the platform reads these tags and builds the preview. Title, description, image, all from OpenGraph.

Twitter has its own format called Twitter Cards. Same idea, different tag names. Most platforms fall back to OpenGraph if Twitter tags are missing, so you can mostly just do OpenGraph and call it a day.

One decision I made: no fake images. If a post has no image, the preview has no image. Using my homepage screenshot as a fallback felt like lying to people. "Here's an article about React memory leaks" with a preview image of my homepage. Confusing. Better to have no image than a misleading one.

How Search Engines Understand Content

Social platforms use OpenGraph. Search engines want something different.

JSON vs JSON-LD

Regular JSON is just structure. You can format it however you want:

Valid JSON. But a search engine has no idea what this is. A blog post? A product listing? A support ticket? Who knows.

JSON-LD (JSON for Linking Data) adds context:

The @context says "I'm using the schema.org vocabulary." The @type says "this is a BlogPosting." Now search engines don't have to guess.

What is schema.org?

Schema.org is a shared vocabulary created by Google, Microsoft, Yahoo, and Yandex in 2011. (Remember when Yahoo was relevant? Me neither, but they were there.)

It defines types for things on the web. Person, Organization, BlogPosting, Product, Event, Recipe, HowTo, FAQ. Hundreds of them.

When you use schema.org types, search engines can show rich results. Recipe cards with cooking times and ingredients. Event listings with dates and locations. Product pages with prices and review stars. Those fancy search results don't come from magic. They come from structured data.

You include JSON-LD as a script tag:

Google finds this, reads it, and understands what your page is.

Canonical URLs

One more thing. When someone links to your post with tracking garbage like ?utm_source=twitter&utm_campaign=share, search engines see a different URL. When scrapers copy your content (they do this, apparently), they create more URLs with identical content. Which one is the original?

This tells search engines: no matter how you got here, this is the real URL. It consolidates ranking signals and helps avoid duplicate content penalties.

How the Data Flows

Here's the chain of how my bloq posts now get their metadata:

Write it once in frontmatter, it propagates everywhere. The title I put in the MDX file becomes the title Twitter shows, the title Google sees, the title in search results.

What I Built

Nothing fancy:

generateMetadata function in the bloq page. Reads frontmatter, returns metadata object with all the tags.
Conditional images. Has image? Include it. No image? Leave it empty. No fake defaults.
JSON-LD component. Renders a script tag with BlogPosting schema. Maybe 20 lines of code.
Static generation. All posts pre-rendered at build time. Search engines get HTML immediately, no JavaScript execution needed.

What I Learned

Metadata is translation work. You're teaching platforms how to describe your content in their language.

OpenGraph for social. JSON-LD for search. Canonical URLs for ownership. Different tools, different jobs, but they all need to be told what your content is.

The implementation wasn't hard once I understood what each thing was for. The hard part was noticing I had completely ignored all of it.

xxx

I Added an RSS Feed

I built an RSS feed for my site. Not because I expect millions of subscribers, but because there's something honest about a protocol that lets readers decide when and how to consume my writing. No algorithm. No engagement metrics. Just a file you can pull.

xxx

The YAGNI in Reverse

I spent three days building pagination for 48 items. Here's what I learned about architecture, search strategies, and why 30 passing tests didn't catch the thing that broke.

All Bloqs

xxx

Mar 6, 2026

3 min read

Metadata That Matters

I shared a bloq post on LinkedIn and saw my homepage title instead of the article title. Embarrassing. So I learned how to tell platforms what my content actually is.

#nextjs

#seo

#reflections

The Problem

"A page without metadata is a stranger at its own party."

So I shared one of my bloq posts on Telegram. The preview card showed:

That's my homepage. Not the article. Every single bloq post had the same preview because I never told platforms what each article was actually about.

The content was unique. The code was thoughtful. But to Twitter, LinkedIn, Google, every post looked identical. I'd built the reading experience. The discovery experience? Completely ignored.

Classic me. Built the fun part, forgot the boring part that makes the fun part discoverable.

How Link Previews Actually Work

When you paste a URL into Twitter or LinkedIn, here's what happens:

OpenGraph

Facebook created OpenGraph in 2010. The idea: webpages can describe themselves in a language platforms understand.

When someone shares your link, the platform reads these tags and builds the preview. Title, description, image, all from OpenGraph.

How Search Engines Understand Content

Social platforms use OpenGraph. Search engines want something different.

JSON vs JSON-LD

Regular JSON is just structure. You can format it however you want:

Valid JSON. But a search engine has no idea what this is. A blog post? A product listing? A support ticket? Who knows.

JSON-LD (JSON for Linking Data) adds context:

The @context says "I'm using the schema.org vocabulary." The @type says "this is a BlogPosting." Now search engines don't have to guess.

What is schema.org?

Schema.org is a shared vocabulary created by Google, Microsoft, Yahoo, and Yandex in 2011. (Remember when Yahoo was relevant? Me neither, but they were there.)

It defines types for things on the web. Person, Organization, BlogPosting, Product, Event, Recipe, HowTo, FAQ. Hundreds of them.

You include JSON-LD as a script tag:

Google finds this, reads it, and understands what your page is.

Canonical URLs

This tells search engines: no matter how you got here, this is the real URL. It consolidates ranking signals and helps avoid duplicate content penalties.

How the Data Flows

Here's the chain of how my bloq posts now get their metadata:

Write it once in frontmatter, it propagates everywhere. The title I put in the MDX file becomes the title Twitter shows, the title Google sees, the title in search results.

What I Built

Nothing fancy:

generateMetadata function in the bloq page. Reads frontmatter, returns metadata object with all the tags.
Conditional images. Has image? Include it. No image? Leave it empty. No fake defaults.
JSON-LD component. Renders a script tag with BlogPosting schema. Maybe 20 lines of code.
Static generation. All posts pre-rendered at build time. Search engines get HTML immediately, no JavaScript execution needed.

What I Learned

Metadata is translation work. You're teaching platforms how to describe your content in their language.

OpenGraph for social. JSON-LD for search. Canonical URLs for ownership. Different tools, different jobs, but they all need to be told what your content is.

The implementation wasn't hard once I understood what each thing was for. The hard part was noticing I had completely ignored all of it.

I spent three days building pagination for 48 items. Here's what I learned about architecture, search strategies, and why 30 passing tests didn't catch the thing that broke.