Vibe coding with Claude Code course Β· Module 12: Medium clone

A Map for Search Engines: Metadata and the Sitemap

9 min read
In this lesson9

The chronicle has texts now but send someone a link to an article and look at the browser tab: "Create Next App". That title and the description "Generated by create next app" stayed in app/layout.tsx from the generator in lesson 11_1 and stand on every page. A messenger that shows a link preview and a search engine that decides what to put in the results see the same thing. On top of that, nobody tells them which texts exist at all. An article without metadata and without a sitemap is like a chest buried without a map: the treasure is there, but nobody knows where.

What you will learn

  • tell Claude to read the current Next.js metadata documentation before any code exists;
  • read generateMetadata, which takes the title and description from the article;
  • build sitemap.xml only from published texts, with a real change date;
  • check the result with the curl command on the built app.

Documentation first

Metadata is the title, description and other tags in the <head> of a page, which the reader does not see in the content and which browsers, messengers and search engines read. The metadata API in Next.js changed between versions, so you start with a scouting trip, as in lessons 5_4 and 9_4. This time no network is needed: from lesson 1_2 you know that Next.js 16 ships the documentation of its version in node_modules/next/dist/docs/, and AGENTS.md tells Claude to read it.

Request for Claude Code:

Do not write code. Read in node_modules/next/dist/docs/ the pages
about generateMetadata, sitemap, robots and JSON-LD. Write: how
generateMetadata differs from a fixed metadata, whether sitemap.ts
is computed at build time or on every request and how to insert
JSON-LD safely. Give a file path for every finding. Then a plan for
/articles/[id].

Compare the report with the files that you open yourself in Cursor. For us the documentation says three things that change the code. A fixed metadata object is one for the whole route segment, and generateMetadata gets params and can read data, but you may not export both from one segment. sitemap.ts is a special route that Next.js caches at build time by default, unless it uses an API that depends on the request. And JSON.stringify does not clean the text of dangerous characters.

Request for Claude Code

The plan looks good, so you order the changes. The article description comes from the excerpt function that you fixed in lesson 11_4, and the change date from a new data field.

Add metadata to Captain's Chronicle according to the plan.
1. app/layout.tsx: instead of "Create Next App" a title with the
   template "%s | Captain's Chronicle", a description of the
   chronicle, lang="en", metadataBase from SITE_URL (lib/site.ts,
   locally http://localhost:3000).
2. /articles/[id]: generateMetadata with the article title, the
   description from @lib/excerpt.ts and Open Graph of type article
   with dates. An unpublished text gets noindex. JSON-LD of type
   Article.
3. app/sitemap.ts: only published articles, lastModified from the
   data: a new field updatedAt in Article (a3 changed on
   15 November), and when it is missing, publishedAt.
4. app/robots.ts: without /api/ and /write, with the sitemap
   address.
Done when lint, tsc, tests and build pass, and curl on npm start
shows the title, description, sitemap and robots.txt.

What Claude wrote: metadata from the article

Open app/layout.tsx. The title template attaches the name of the chronicle to the title of every subpage:

// app/layout.tsx
export const metadata: Metadata = {
  metadataBase: new URL(SITE_URL),
  title: { default: "Captain's Chronicle", template: "%s | Captain's Chronicle" },
  description: "Tales from voyages written down by the crew.",
};

According to the docs template works only in segments below the layout and requires default, which pages without their own title get. metadataBase lets you write paths further down instead of full addresses. Now app/articles/[id]/page.tsx:

// app/articles/[id]/page.tsx
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { id } = await params;
  const article = getArticle(id);
  if (!article) return {};
  const description = excerpt(article);
  return {
    title: article.title,
    description,
    alternates: { canonical: `/articles/${article.id}` },
    openGraph: {
      type: "article",
      title: article.title,
      description,
      url: `/articles/${article.id}`,
      publishedTime: article.publishedAt,
      modifiedTime: article.updatedAt ?? article.publishedAt,
    },
    robots: isPublished(article) ? undefined : { index: false },
  };
}

Props is the same type with params as a promise that the page uses. Every article gets its own title and description. Open Graph is the og: tags from which messengers build a link preview. canonical points at the main address of the page. A text that was submitted but not published gets noindex: the editor can look at it, and the search engine gets a request not to index it.

What Claude wrote: the sitemap

A sitemap is an XML file with a list of addresses. The Next.js docs say it helps search engine robots index the site more efficiently. Each address may have the date of the last change, and the sitemap protocol (sitemaps.org) reserves that for the date the page itself changed, not the moment the sitemap was created. That is why Claude started with the data in lib/articles.ts:

// lib/articles.ts
  publishedAt: string; // ISO
  updatedAt?: string; // ISO, the last change after publication

The question mark makes updatedAt an optional field: a text that nobody corrected after publication does not have it, and then publishedAt counts. Mary's text from lesson 11_4 got updatedAt, because it changed after publication. Now open app/sitemap.ts:

// app/sitemap.ts
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  await connection(); // publications change after the build
  return ARTICLES.filter(isPublished).map((article) => ({
    url: `${SITE_URL}/articles/${article.id}`,
    lastModified: article.updatedAt ?? article.publishedAt,
  }));
}

filter(isPublished) throws drafts out: only what the reader can really read goes into the sitemap. lastModified comes from the data, so the sitemap tells the truth about the change date of every text. connection() from next/server makes the sitemap computed on every request. Without this line the build marked /sitemap.xml as static (β—‹) for us. After publishing text a4 through the curl from lesson 11_3 the sitemap still had three addresses. With connection() the route got Ζ’, and a4 appeared at once.

app/robots.ts tells robots what not to visit and gives the address of the sitemap:

// app/robots.ts
export default function robots(): MetadataRoute.Robots {
  return {
    rules: { userAgent: "*", allow: "/", disallow: ["/api/", "/write"] },
    sitemap: `${SITE_URL}/sitemap.xml`,
  };
}

This route stayed static, so it reads SITE_URL at build time. For us a variable set only at npm start changed the addresses in the sitemap, and robots.txt still showed http://localhost:3000/sitemap.xml. In production you set SITE_URL before the build starts.

What Claude wrote: JSON-LD

JSON-LD is structured data: a description of the page in a format that search engines read like a form (type, title, dates). The Next.js docs recommend a plain <script> tag in the page:

// app/articles/[id]/page.tsx
<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, "\\u003c") }}
/>

jsonLd is an object with @type: "Article", the title, the description and both dates. The title is written by the author, and a title with </script> inside would close the tag and treat the rest as HTML. That is why replace changes every < into \u003c, as the docs advise.

The check: curl on the built app

Metadata is judged in the HTML that a robot gets, not in the code. Run npm run build && npm start and in a second terminal tab:

curl -s localhost:3000/articles/a3 | grep -oE '<title>[^<]*</title>|<meta name="description"[^>]*>|<meta property="og:(title|type)"[^>]*>'
curl -s localhost:3000/articles/a4 | grep -o '<meta name="robots"[^>]*>'
curl -s localhost:3000/sitemap.xml
curl -s localhost:3000/robots.txt

grep -o prints only the matching pieces, and -E lets you write several patterns separated by |. For us the first command printed:

<title>The Ship&#x27;s Cook Advises: Hardtack for Six Weeks | Captain&#x27;s Chronicle</title>
<meta name="description" content="Hardtack must be hard as the deck, or it will not survive the voyage."/>
<meta property="og:title" content="The Ship&#x27;s Cook Advises: Hardtack for Six Weeks"/>
<meta property="og:type" content="article"/>

&#x27; is an apostrophe written in HTML. The second command gave <meta name="robots" content="noindex"/> for the submitted a4. The sitemap had three addresses, a1, a2 and a3, with dates from the data, and at a3 2026-11-15T07:30:00Z from the updatedAt field. In robots.txt stood Disallow: /api/, Disallow: /write and the address of the sitemap. Check an address that does not exist too: /articles/zzz answered with code 404 for us, with the noindex that Next.js adds by itself and with the default title from the layout. Here generateMetadata returns an empty object, and notFound() stops the page.

Captain's review

  1. A different title for every article. A typical agent mistake is a fixed export const metadata in the article page: the same title for every text. The second is a copied example from the docs with acme.com or a leftover "Create Next App". Search the project for both strings.
  2. Drafts outside the sitemap. a4 is not in sitemap.xml until the editor publishes it, and its page has noindex.
  3. A date from the data. The example in the docs has lastModified: new Date() and Claude likes to copy it. For us two requests two seconds apart gave two different dates: the sitemap claimed that every text changes all the time.
  4. A real address. In production there is no localhost in the sitemap or in robots.txt.
  5. Safe JSON-LD. Next to JSON.stringify in the <script> stands a replace of the < character.

Metadata and a sitemap do not promise a place in the search results. They tell robots what is on the page and where to look for the rest, and the search engine decides the order of the results.

Next step

Ask for a commit "Metadata, sitemap and robots.txt". You will repeat the four curl commands for every new route, so turn them into a skill from lesson 6_1: "Save the SEO check from this conversation as a skill /seo-check in .claude/skills/: build, start, curl of the title, description, og:, sitemap and robots.txt, the result in a table. Only I run it." In the editor below waits a preview of the chronicle: pick an article, see its tags and the sitemap, and then switch on the agent's bug "one title for everyone" and the bug with new Date().

Remember: a map without treasure is only a sheet of paper, but treasure without a map stays under the sand.

Code for this lesson: App.jsx
// A preview of metadata and the sitemap built from the chronicle's sample articles
import { useState } from 'react';

const SITE_URL = 'https://chronicle.example';
const SITE_NAME = "Captain's Chronicle";

const ARTICLES = [
  { id: 'a1', title: 'How to Survive a Storm on the Atlantic', text: 'The storm came at night while the crew slept after a long watch.', status: 'published', publishedAt: '2026-11-10T08:00:00Z' },
  { id: 'a2', title: 'The Treasure Map That Never Was', text: 'The map had three crosses and no treasure.', status: 'published', publishedAt: '2026-11-12T08:00:00Z' },
  { id: 'a3', title: "The Ship's Cook Advises: Hardtack for Six Weeks", text: 'Hardtack must be hard as the deck, or it will not survive the voyage.', status: 'published', publishedAt: '2026-11-14T08:00:00Z', updatedAt: '2026-11-15T07:30:00Z' },
  { id: 'a4', title: 'Night Watch Without Coffee', text: 'At three in the morning the stars are the only clock.', status: 'submitted', publishedAt: '2026-11-15T08:00:00Z' },
];

function excerpt(article, max = 160) {
  const text = article.text.trim();
  return text.length > max ? text.slice(0, max - 1).trimEnd() + '…' : text;
}

// Like generateMetadata: title and description from the article. The agent's version: one fixed metadata object.
function metadataFor(article, published, staticTitle) {
  if (staticTitle) {
    return { title: 'Article | ' + SITE_NAME, description: 'Tales from voyages written down by the crew.', ogType: 'website', robots: null };
  }
  return {
    title: article.title + ' | ' + SITE_NAME,
    description: excerpt(article),
    ogType: 'article',
    robots: published ? null : 'noindex',
  };
}

function sitemapXml(articles, isPublished, options) {
  const rows = articles
    .filter((a) => options.drafts || isPublished(a))
    .map((a) => {
      const lastmod = options.newDate ? options.generatedAt : a.updatedAt ?? a.publishedAt;
      return '  <url>\n    <loc>' + SITE_URL + '/articles/' + a.id + '</loc>\n    <lastmod>' + lastmod + '</lastmod>\n  </url>';
    });
  return '<urlset>\n' + rows.join('\n') + '\n</urlset>';
}

export default function App() {
  const [selectedId, setSelectedId] = useState('a3');
  const [publishedA4, setPublishedA4] = useState(false);
  const [staticTitle, setStaticTitle] = useState(false);
  const [newDate, setNewDate] = useState(false);
  const [drafts, setDrafts] = useState(false);
  const [generatedAt, setGeneratedAt] = useState('2026-11-15T09:00:00.000Z');

  const isPublished = (a) => a.status === 'published' || (a.id === 'a4' && publishedA4);
  const article = ARTICLES.find((a) => a.id === selectedId);
  const meta = metadataFor(article, isPublished(article), staticTitle);
  const xml = sitemapXml(ARTICLES, isPublished, { drafts, newDate, generatedAt });

  return (
    <div className="min-h-screen bg-gray-50 p-4 text-gray-900">
      <div className="mx-auto max-w-xl space-y-4 rounded-xl bg-white p-4 shadow-sm">
        <label className="block text-sm">
          Article:{' '}
          <select value={selectedId} onChange={(e) => setSelectedId(e.target.value)} className="rounded border border-gray-300">
            {ARTICLES.map((a) => (
              <option key={a.id} value={a.id}>
                {a.id}: {a.title} {isPublished(a) ? '' : '(submitted)'}
              </option>
            ))}
          </select>
        </label>

        <div className="rounded-lg border border-gray-200 p-3">
          <p className="text-xs uppercase text-gray-500">Link preview in a messenger</p>
          <p className="font-semibold text-blue-800">{meta.title}</p>
          <p className="text-sm text-gray-700">{meta.description}</p>
          <p className="text-xs text-gray-500">{SITE_URL}/articles/{article.id}</p>
        </div>

        <pre aria-label="Tags in head" className="overflow-x-auto rounded bg-gray-900 p-3 text-xs text-green-200">
          {'<title>' + meta.title + '</title>\n'}
          {'<meta name="description" content="' + meta.description + '"/>\n'}
          {'<meta property="og:type" content="' + meta.ogType + '"/>'}
          {meta.robots ? '\n<meta name="robots" content="' + meta.robots + '"/>' : ''}
        </pre>
      </div>

      <div className="mx-auto mt-3 max-w-xl space-y-2 rounded-xl bg-white p-4 text-sm shadow-sm">
        <p className="font-semibold">sitemap.xml</p>
        <pre aria-label="Sitemap" className="overflow-x-auto rounded bg-gray-100 p-3 text-xs">{xml}</pre>
        <div className="flex flex-wrap gap-2">
          <button type="button" onClick={() => setGeneratedAt(new Date().toISOString())} className="rounded bg-gray-900 px-3 py-1 text-white">
            Fetch the sitemap again
          </button>
          <button type="button" disabled={publishedA4} onClick={() => setPublishedA4(true)} className="rounded bg-gray-700 px-3 py-1 text-white disabled:opacity-50">
            Editor publishes a4
          </button>
        </div>
      </div>

      <div className="mx-auto mt-3 max-w-xl space-y-2 rounded-xl bg-gray-900 p-4 text-sm text-white">
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={staticTitle} onChange={(e) => setStaticTitle(e.target.checked)} />
          Agent mistake: one title for everything (fixed metadata)
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={newDate} onChange={(e) => setNewDate(e.target.checked)} />
          Agent mistake: lastModified: new Date()
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={drafts} onChange={(e) => setDrafts(e.target.checked)} />
          Agent mistake: drafts in the sitemap
        </label>
      </div>
    </div>
  );
}

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. The agent "fixed" the excerpt bug: it wrapped the code in try/catch, and the catch returns an empty string. What happens?

  2. 2. You add the Sentry MCP server with the --scope project option. Where does the configuration go and who gets it?

These are 2 of 6 questions for this lesson. Solve the rest in the game.

Hands-on tasks in the game

  • Vertical ordering

    Arrange your work with Claude Code on a bug reported by Sentry:

  • Horizontal ordering

    Arrange the command as written in the Claude Code docs: first the transport option, then the server name and the address:

  • Click in order

    Click the elements to build a sitemap line with the change date taken from the article's data:

  1. Put in orderA Sentry bug step by step
  2. QuestionThe empty catch in the fix
  3. Put in orderAdding an MCP server over HTTP
  4. QuestionThe project scope
  5. QuestionCLI or MCP
  6. QuestionWhat /mcp is for
  7. Click in orderThe change date from the data
  8. QuestiongenerateMetadata or metadata
  9. QuestionA submitted text and the sitemap
  10. Project to submitSend Captain's Chronicle to mentor
  11. VideoModule summary

Useful articles