Cours Vibe coding avec Claude Code · Module 12: Clone de Medium

La carte pour les moteurs de recherche : métadonnées et plan du site

10 min de lecture
Dans cette leçon9

La chronique a déjà ses textes mais envoie à quelqu'un le lien d'un article et regarde l'onglet du navigateur : "Create Next App". Ce titre et la description "Generated by create next app" sont restés dans app/layout.tsx, créé par l'assistant de la leçon 11_1, et figurent sur chaque page. La messagerie qui affiche l'aperçu d'un lien et le moteur de recherche qui décide quoi écrire dans les résultats voient la même chose. En plus, personne ne leur dit quels textes existent. Un article sans métadonnées et sans plan du site, c'est un coffre enterré sans carte : le trésor est là, mais personne ne sait où.

Ce que tu vas apprendre

  • demander à Claude de lire la documentation actuelle des métadonnées de Next.js avant que le code n'existe ;
  • lire un generateMetadata qui prend le titre et la description dans l'article ;
  • construire un sitemap.xml avec les seuls textes publiés et une vraie date de modification ;
  • vérifier le résultat avec la commande curl sur l'application construite.

D'abord la documentation

Les métadonnées sont le titre, la description et d'autres balises dans le <head> de la page, que le lecteur ne voit pas dans le contenu, mais que lisent les navigateurs, les messageries et les moteurs de recherche. L'API des métadonnées de Next.js a changé d'une version à l'autre, donc tu commences par une reconnaissance, comme dans les leçons 5_4 et 9_4. Cette fois, pas besoin du réseau : tu sais depuis la leçon 1_2 que Next.js 16 embarque la documentation de sa version dans node_modules/next/dist/docs/, et AGENTS.md demande à Claude de la lire.

Demande pour Claude Code :

N'écris pas de code. Lis dans node_modules/next/dist/docs/ les pages
sur generateMetadata, sitemap, robots et JSON-LD. Écris : en quoi
generateMetadata diffère de l'objet metadata fixe, si sitemap.ts est
calculé au build ou à chaque requête, et comment insérer JSON-LD en
sécurité. Pour chaque constat, le chemin du fichier. Ensuite un plan
pour /articles/[id].

Compare le rapport avec les fichiers que tu ouvres toi-même dans Cursor. Chez nous, la documentation dit trois choses qui changent le code. L'objet fixe metadata est unique pour tout un segment de route, alors que generateMetadata reçoit params et peut lire des données, et l'on ne peut pas exporter les deux à la fois depuis le même segment. sitemap.ts est une route spéciale que Next.js met par défaut en cache au build, sauf si elle utilise une API dépendant de la requête. Et JSON.stringify ne nettoie pas le texte des caractères dangereux.

Demande pour Claude Code

Le plan a l'air bon, donc tu commandes les changements. La description de l'article vient de la fonction excerpt que tu as corrigée dans la leçon 11_4, et la date de modification d'un nouveau champ de données.

Ajoute les métadonnées à Captain's Chronicle selon le plan.
1. app/layout.tsx : à la place de "Create Next App", un titre avec le
   modèle "%s | Captain's Chronicle", la description de la chronique,
   lang="fr", metadataBase avec SITE_URL (lib/site.ts, en local
   http://localhost:3000).
2. /articles/[id] : generateMetadata avec le titre de l'article, la
   description tirée de @lib/excerpt.ts et Open Graph de type article
   avec les dates. Un texte non publié reçoit noindex. JSON-LD de type
   Article.
3. app/sitemap.ts : seulement les articles publiés, lastModified tiré
   des données : nouveau champ updatedAt dans Article (a3 a changé le
   15 novembre), et s'il n'y en a pas, publishedAt.
4. app/robots.ts : sans /api/ et /ecrire, avec l'adresse du plan.
C'est fini quand le lint, tsc, les tests et le build passent, et que
curl sur npm start montre le titre, la description, le plan et
robots.txt.

Ce que Claude a écrit : des métadonnées tirées de l'article

Ouvre app/layout.tsx. Le modèle de titre ajoute le nom de la chronique au titre de chaque sous-page :

// app/layout.tsx
export const metadata: Metadata = {
  metadataBase: new URL(SITE_URL),
  title: { default: "Captain's Chronicle", template: "%s | Captain's Chronicle" },
  description: "Récits de voyages écrits par l'équipage.",
};

Selon la documentation, template ne s'applique qu'aux segments situés sous le layout et exige un default, que reçoivent les pages sans titre propre. metadataBase te permet d'écrire plus bas des chemins au lieu d'adresses complètes. Voici maintenant 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 est le même type avec params comme promesse que celui qu'utilise la page. Chaque article reçoit son propre titre et sa propre description. Open Graph désigne les balises og: à partir desquelles les messageries construisent l'aperçu d'un lien. canonical indique l'adresse principale de la page. Un texte soumis mais non publié reçoit noindex : le rédacteur peut le voir, et le moteur de recherche reçoit la demande de ne pas l'indexer.

Ce que Claude a écrit : le plan du site

Un plan du site (sitemap) est un fichier XML avec une liste d'adresses. La documentation de Next.js écrit qu'il aide les robots des moteurs de recherche à indexer le site plus efficacement. À côté de chaque adresse peut figurer la date de dernière modification, et le protocole des plans de site (sitemaps.org) précise que ce doit être la date de modification de la page elle-même, pas le moment où le plan a été créé. C'est pourquoi Claude a commencé par les données dans lib/articles.ts :

// lib/articles.ts
  publishedAt: string; // ISO
  updatedAt?: string; // ISO, dernière modification après publication

Le point d'interrogation fait d'updatedAt un champ facultatif : un texte que personne n'a corrigé après publication ne l'a pas, et c'est alors publishedAt qui compte. Le texte de Mary de la leçon 11_4 a reçu updatedAt, car il a changé après publication. Ouvre maintenant app/sitemap.ts :

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

filter(isPublished) écarte les brouillons : seul ce que le lecteur peut réellement lire entre dans le plan. lastModified vient des données, donc le plan dit la vérité sur la date de modification de chaque texte. connection() de next/server demande de calculer le plan à chaque requête. Sans cette ligne, le build a marqué chez nous /sitemap.xml comme statique (○). Après la publication du texte a4 par le curl de la leçon 11_3, le plan avait toujours trois adresses. Avec connection(), la route a reçu ƒ, et a4 est apparu tout de suite.

app/robots.ts dit aux robots ce qu'ils ne doivent pas visiter et donne l'adresse du plan :

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

Cette route est restée statique, donc elle lit SITE_URL au build. Chez nous, une variable définie seulement au moment de npm start a changé les adresses du plan, mais robots.txt affichait toujours http://localhost:3000/sitemap.xml. En production, tu définis SITE_URL avant que le build ne démarre.

Ce que Claude a écrit : JSON-LD

JSON-LD, ce sont des données structurées : une description de la page dans un format que les moteurs de recherche lisent comme un formulaire (type, titre, dates). La documentation de Next.js recommande une simple balise <script> dans la page :

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

jsonLd est un objet avec @type: "Article", le titre, la description et les deux dates. Le titre est écrit par l'auteur, et un titre contenant </script> fermerait la balise et traiterait le reste comme du HTML. C'est pourquoi replace remplace chaque < par \u003c, comme le conseille la documentation.

Vérification : curl sur l'application construite

Les métadonnées s'évaluent dans le HTML que reçoit le robot, pas dans le code. Lance npm run build && npm start et, dans un deuxième onglet du terminal :

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 n'affiche que les morceaux qui correspondent, et -E permet d'écrire plusieurs motifs séparés par |. Chez nous, la première commande a affiché :

<title>Le cuisinier de bord conseille : du biscuit pour six semaines | Captain&#x27;s Chronicle</title>
<meta name="description" content="Le biscuit doit être dur comme le pont, sinon il ne survivra pas au voyage."/>
<meta property="og:title" content="Le cuisinier de bord conseille : du biscuit pour six semaines"/>
<meta property="og:type" content="article"/>

&#x27; est l'apostrophe écrite en HTML. La deuxième commande a donné <meta name="robots" content="noindex"/> pour a4, soumis mais pas publié. Le plan avait trois adresses, a1, a2 et a3, avec les dates tirées des données, pour a3 2026-11-15T07:30:00Z du champ updatedAt. Dans robots.txt figuraient Disallow: /api/, Disallow: /ecrire et l'adresse du plan. Vérifie aussi une adresse qui n'existe pas : /articles/zzz a répondu chez nous par le code 404, avec le noindex que Next.js ajoute tout seul et avec le titre par défaut du layout. Ici generateMetadata renvoie un objet vide, et la page est arrêtée par notFound().

La revue du capitaine

  1. Un titre différent par article. L'erreur typique de l'agent est un export const metadata fixe dans la page de l'article : le même titre pour chaque texte. La deuxième est un exemple de la documentation recopié avec acme.com, ou un "Create Next App" laissé en place. Cherche ces deux chaînes dans le projet.
  2. Brouillons hors du plan. Dans sitemap.xml, il n'y a pas a4 tant que le rédacteur ne l'a pas publié, et sa page a noindex.
  3. Une date tirée des données. L'exemple de la documentation a lastModified: new Date(), et Claude le copie volontiers. Chez nous, deux requêtes à deux secondes d'écart ont donné deux dates différentes : le plan prétendait que chaque texte change à chaque instant.
  4. Une vraie adresse. En production, il n'y a pas de localhost dans le plan ni dans robots.txt.
  5. JSON-LD sûr. À côté de JSON.stringify dans un <script>, il y a le replace du caractère <.

Les métadonnées et le plan ne promettent pas de place dans les résultats de recherche. Ils disent aux robots ce qu'il y a sur le site et où chercher le reste, et l'ordre des résultats, c'est le moteur de recherche qui le décide.

Étape suivante

Demande un commit "Métadonnées, plan du site et robots.txt". Les quatre commandes curl, tu les répéteras à chaque nouvelle route, donc transforme-les en skill de la leçon 6_1 : "Enregistre le contrôle SEO de cette conversation comme skill /seo-check dans .claude/skills/ : build, start, curl du titre, de la description, des og:, du plan et de robots.txt, résultat dans un tableau. Je suis le seul à le lancer." Dans l'éditeur ci-dessous t'attend un aperçu de la chronique : choisis un article, regarde ses balises et le plan, puis active l'erreur de l'agent "un seul titre pour tous" et l'erreur avec new Date().

Retiens ceci : une carte sans trésor n'est qu'un bout de papier, mais un trésor sans carte reste sous le sable.

Code de cette leçon : App.jsx
// Aperçu des métadonnées et du plan du site à partir d'articles d'exemple de la chronique
import { useState } from 'react';

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

const ARTICLES = [
  { id: 'a1', title: "Comment survivre à une tempête en Atlantique", text: "La tempête est arrivée de nuit, et l'équipage dormait après un long quart.", status: 'published', publishedAt: '2026-11-10T08:00:00Z' },
  { id: 'a2', title: "La carte au trésor introuvable", text: "La carte avait trois croix et aucun trésor.", status: 'published', publishedAt: '2026-11-12T08:00:00Z' },
  { id: 'a3', title: "Le cuisinier de bord conseille : du biscuit pour six semaines", text: "Le biscuit doit être dur comme le pont, sinon il ne survivra pas au voyage.", status: 'published', publishedAt: '2026-11-14T08:00:00Z', updatedAt: '2026-11-15T07:30:00Z' },
  { id: 'a4', title: "Le quart de nuit sans café", text: "À trois heures du matin, les étoiles sont la seule horloge.", 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;
}

// Comme generateMetadata : titre et description tirés de l'article. Version de l'agent : un seul objet metadata fixe.
function metadataFor(article, published, staticTitle) {
  if (staticTitle) {
    return { title: 'Article | ' + SITE_NAME, description: "Récits de voyages écrits par l'équipage.", 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) ? '' : '(soumis)'}
              </option>
            ))}
          </select>
        </label>

        <div className="rounded-lg border border-gray-200 p-3">
          <p className="text-xs uppercase text-gray-500">Aperçu du lien dans la messagerie</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="Balises dans le 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="Plan du site" 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">
            Récupérer le plan à nouveau
          </button>
          <button type="button" disabled={publishedA4} onClick={() => setPublishedA4(true)} className="rounded bg-gray-700 px-3 py-1 text-white disabled:opacity-50">
            Le rédacteur publie 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)} />
          Erreur de l&apos;agent : un seul titre pour tous (metadata fixe)
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={newDate} onChange={(e) => setNewDate(e.target.checked)} />
          Erreur de l&apos;agent : lastModified: new Date()
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={drafts} onChange={(e) => setDrafts(e.target.checked)} />
          Erreur de l&apos;agent : des brouillons dans le plan
        </label>
      </div>
    </div>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. L'agent a "réparé" l'erreur de l'extrait : il a enveloppé le code dans un try/catch dont le catch renvoie une chaîne vide. Que se passe-t-il ?

  2. 2. Tu ajoutes le serveur MCP de Sentry avec l'option --scope project. Où va la configuration et qui la reçoit ?

Voici 2 des 6 questions de cette leçon. Réponds aux autres dans le jeu.

Tâches pratiques dans le jeu

  • Tri vertical

    Ordonne le travail avec Claude Code sur une erreur signalée par Sentry :

  • Tri horizontal

    Compose la commande telle qu'elle est écrite dans la documentation de Claude Code : d'abord l'option de transport, puis le nom du serveur et l'adresse :

  • Clique dans l'ordre

    Clique sur les éléments pour construire la ligne du plan du site avec la date de modification tirée des données de l'article :

  1. Remets dans l'ordreL'erreur de Sentry pas à pas
  2. QuestionUn catch vide dans la correction
  3. Remets dans l'ordreAjouter un serveur MCP en HTTP
  4. QuestionLa portée project
  5. QuestionCLI ou MCP
  6. QuestionÀ quoi sert /mcp
  7. Clique dans l'ordreDate de modification tirée des données
  8. QuestiongenerateMetadata ou metadata
  9. QuestionTexte soumis et plan du site
  10. Projet à envoyerEnvoie Chronique du Capitaine au mentor
  11. VidéoRésumé du module

Articles utiles