Edit article

Update content, metadata, and publishing status for this post.

Markdown Content

When someone shares your link on LinkedIn, the preview card comes from **meta tags** in your HTML. Google works the same way. If title and description only appear after JavaScript runs in the browser, many crawlers miss them entirely.

**SSR** puts metadata in the first HTML response — before React loads.

## Vocabulary

| Term | Meaning |
| ---- | ------- |
| **Meta tags** | `<title>`, `<meta name="description">` — shown in search results |
| **Open Graph** | `og:*` tags — control social preview cards |
| **Canonical URL** | Tells search engines the official page address |
| **JSON-LD** | Structured data block — enables rich search results |
| **Sitemap** | XML list of URLs you want indexed |

## Mental model

1. Route loader fetches page data
2. `head()` builds meta, Open Graph, and JSON-LD
3. Server sends a complete `<head>` in the first HTML response
4. Crawlers and social bots read metadata immediately
5. Sitemap lists public URLs for discovery

## Steps

## Step 1 — Build a reusable head helper

One function sets title, description, canonical, Open Graph, and Twitter cards:

```typescript
export const createPortfolioPageHead = (input, baseUrl) => {
  const canonicalUrl = resolveCanonicalUrl(baseUrl, input.path);
  return {
    meta: [
      { title: input.title },
      { name: 'description', content: input.description },
      { property: 'og:title', content: input.title },
      { property: 'og:url', content: canonicalUrl },
      { property: 'og:image', content: ogImageUrl },
      { name: 'twitter:card', content: 'summary_large_image' }
    ],
    links: [{ rel: 'canonical', href: canonicalUrl }]
  };
};
```

## Step 2 — Extend for blog posts

Add article type, publish date, and BlogPosting JSON-LD:

```typescript
export const createBlogPostHead = (post, baseUrl) => {
  const head = createPortfolioPageHead({
    title: post.title,
    description: post.excerpt,
    path: `/blog/${post.slug}`,
    ogType: 'article'
  }, baseUrl);

return {
    ...head,
    meta: [...head.meta, { property: 'article:published_time', content: post.dateTime }],
    scripts: [{ type: 'application/ld+json', children: JSON.stringify(articleJsonLd) }]
  };
};
```

## Step 3 — Wire head into each route

```typescript
head: ({ loaderData }) => {
  const post = loaderData?.post;
  if (!post) return createPortfolioPageHead({ /* fallback */ }, publicConfig.BASE_URL);
  return createBlogPostHead(post, publicConfig.BASE_URL);
},
```

## Step 4 — Generate a dynamic sitemap

Query published content and emit XML:

```typescript
export const buildSitemapXml = async () => {
  const posts = await getBlogPostsImpl();
  const urls = [
    buildSitemapUrlEntry(`${baseUrl}/`, { priority: '1.0' }),
    buildSitemapUrlEntry(`${baseUrl}/blog`, { priority: '0.8' }),
    ...posts.map((post) =>
      buildSitemapUrlEntry(`${baseUrl}/blog/${post.slug}`, {
        lastmod: post.dateTime,
        priority: '0.6'
      })
    )
  ];
  return `<?xml version="1.0"?><urlset>...</urlset>`;
};
```

## Step 5 — Add robots.txt

```typescript
export const buildRobotsTxt = () => {
  return ['User-agent: *', 'Disallow:', '', `Sitemap: ${baseUrl}/sitemap.xml`, ''].join('\n');
};
```

Expose as a server route returning `text/plain`.

## Step 6 — Set BASE_URL in production

```bash
BASE_URL=https://yoursite.com
```

Every canonical link, sitemap entry, and OG URL derives from this — never hard-code `localhost`.

## Common pitfalls

- Setting meta tags in `useEffect` — crawlers never see them.
- Forgetting `og:image` — social shares show blank cards.
- Static sitemap that never updates — new blog posts stay invisible to Google.

## Verify it works

- **View page source** (not DevTools Elements) — meta tags must appear in raw HTML.
- Visit `/sitemap.xml` — all published URLs listed with `lastmod`.
- Test social cards at an Open Graph debugger.
- Validate JSON-LD with Google's Rich Results Test.

## Takeaway

SEO is server-rendered metadata plus a sitemap that stays current. One head helper per page type, one env var for your domain, automatic sitemap from your database.