Aller au contenu principal

Données structurées : du Root.js manuel au plugin JSON-LD

· 7 minutes de lecture
Florence Venisse
Florence Venisse
Rédactrice Technique Expert

Comment mon travail sur les données structurées a fini en plugin Docusaurus

Dans mon article précédent, "J'ai pris le contrôle de mes métadonnées", j'expliquais comment j'avais exploré deux méthodes pour injecter des données structurées dans Docusaurus.

Ce travail m'a amenée à une conclusion simple : pour un site bilingue, riche en contenu, et pensé pour le SEO moderne (SEO, GEO et moteurs génératifs compris), aucune des méthodes existantes n'était satisfaisante sur la durée.

À ce stade, j'avais le choix : accepter la complexité croissante... ou changer complètement d'approche.
C'est ainsi qu'est née la troisième méthode, puis un plugin !

Le travail décrit ci-après n'a pas été sous-traité à l'IA, et le plugin n'a pas non plus été développé par IA.

Comment un plugin JSON-LD a émergé de mon travail sur les données structurées

Rappel sur les méthodes​

Dans mon article précédent, j'ai présenté deux méthodes pour gérer les données structurées dans Docusaurus et les injecter dans le <head> des pages HTML, tout en évoquant le fait que j'avais abouti à une troisième méthode 😁.

Méthode 1 via docusaurus.config.js​

Cette méthode consiste à définir un schéma global, valable pour tout le site, et à le placer dans l'endroit de prédilection des personnalisations de Docusaurus : le fichier de configuration.

➕ Pratique pour les informations communes (organisation, site web, personne).
➖ Insuffisante pour décrire chaque page individuellement.

Méthode 2 via un fichier Root.js​

Cette méthode consiste à créer un composant React global* qui injecte un JSON-LD spécifique à chaque page.

Il faut pour cela renseigner un fichier Root.js avec toutes les propriétés souhaitées pour les entités de base, mais aussi pour chaque page Markdown du site.

➕ Puissante, centralisée, détaillée et exhaustive.
➖ Manuelle : il faut écrire un schéma détaillé pour chaque page du site.
➖ Difficile à maintenir et à faire évoluer dans le temps.

* Composant React global injecté au niveau du thème Docusaurus.

Les limites concrètes du Root.js​

En pratique, la méthode a bien fonctionné : le JSON-LD était correctement interprété par Docusaurus et les propriétés étaient bien définies.

Mais très vite, le travail est devenu fastidieux, et le fichier menaçait de devenir ingérable.

Un fichier face à ses limites​

Une fois le travail abouti, la méthode s'est heurtée à des limites structurelles : un fichier de près de 2 800 lignes, centralisant la description d'une cinquantaine de pages… par langue. Et mon site en compte deux.

Cette approche fonctionne tant que le contenu du site reste stable.
En revanche, chaque nouvelle page impose une mise à jour manuelle, avec un risque d'erreur proportionnel à la taille du fichier.

C'est un piège classique : ce qui est acceptable à petite échelle devient vite un fardeau dès que le site commence à vivre.

Le problème du multilingue​

Mon site est bilingue (français et anglais) et j'ai activé l'i18n de Docusaurus. Je m'attends donc à pouvoir injecter des données structurées spécifiques à chaque langue, sans invisibiliser mon site côté SEO français, même s'il est English first.

Or, le fichier Root.js est placé dans src/theme et il est, par nature, unilingue :

  • Docusaurus ne duplique pas ce composant par locale (pas de duplication dans i18n/fr),
  • les traductions ne sont pas possibles, contrairement au contenu de src/components par exemple.

Maintenir deux fichiers Root.js n'est donc pas prévu — et heureusement.
Dupliquer ce type de logique reviendrait à démultiplier les problèmes de maintenance et à créer une véritable usine à gaz 😁.

La redondance au cœur du problème​

La méthode 2 imposait de nombreuses redondances :

  1. Répéter les entités de base (organisation, site web, personne).
  2. Déclarer manuellement les URLs canoniques pour chaque page.
  3. Copier-coller des titres, descriptions et dates déjà présents dans les front matter.

Cette duplication était non seulement lourde, mais dangereuse pour la cohérence du site.

La bonne pratique @graph​

Pour limiter ces répétitions, j'ai utilisé un @graph.

Cette approche permet de regrouper dans un seul bloc JSON-LD toutes les entités liées à une page (organisation, auteur, page, article…), ce qui améliore la lisibilité du schéma et simplifie partiellement la maintenance. Les moteurs de recherche interprètent plus facilement un graphe bien structuré qu'une succession de scripts indépendants.

🎬 Voir une vidéo

Vous pouvez à ce sujet visionner sur YouTube : "JSON-LD : Comment structurer votre site pour Google et l'IA", à partir de 4'34 pour la méthode @graph.

La méthode @graph est une excellente base pour structurer proprement un schéma JSON-LD.
Mais dans un site réel, multilingue et en évolution constante, elle ne suffit pas à elle seule.

Le problème de fond restait entier : les URLs et les doublons avec les front matter continuaient de poser un vrai problème de cohérence.

C'est précisément ce constat qui m'a menée à concevoir un plugin dédié — qui sera le sujet de la partie 2️⃣ 😉.

Voir un exemple réel de @graph utilisé sur CoffeeCup.tech
"@graph": [
  {
    "@type": "Organization",
    "@id": "https://coffeecup.tech/#organization",
    "name": "CoffeeCup.tech",
    "legalName": "Florence Venisse EI",
    "legalRepresentative": {
      "@id": "https://coffeecup.tech/#person"
    },
    "location": "France",
    (...)
  },
  {
    "@type": "Person",
    "@id": "https://coffeecup.tech/#person",
    (...)
  },
  {
    "@type": "WebSite",
    "@id": "https://coffeecup.tech/#website",
    "url": "https://coffeecup.tech/",
    "name": "CoffeeCup.tech",
    (...)
  }
]

Les front matter au cœur de la solution​

💡 C'est là que le déclic s'est produit : le front matter est une source de vérité déjà existante.

Présents sur toutes les pages Markdown (et MDX), ils sont structurés, fiables et déjà utilisés par Docusaurus pour générer les métadonnées HTML.

Il suffisait donc d'exploiter pleinement ceux qui correspondent aux propriétés de schema.org, plutôt que de les dupliquer ailleurs.

Les front matter décrivent chaque page comme une véritable carte d'identité.

---
id: contact
title: Contacter CoffeeCup.tech
language: FR
author: Florence Venisse
description: "Contactez CoffeeCup.tech xxxx."
date: 2026-01-19
---
SSG Hugo

Avant Docusaurus, j'utilisais Hugo, un SSG reposant fortement sur les front matter pour typer les pages, gérer les contenus et structurer les métadonnées.

Concevoir la méthode 3​

La méthode 3 transforme un front matter en schéma JSON-LD. Elle combine :

  • la méthode 1 pour les données globales,
  • les front matter pour les données spécifiques,
  • et la méthode 2, puisqu'elle génère dynamiquement un Root.js.

À ce stade, l'objectif était clair : changer d'échelle et sortir définitivement des redondances du JSON-LD écrit à la main.

Certaines correspondances sont évidentes :

  • title ⬌ headline
  • author ⬌ author
  • date ⬌ datePublished

Mais un schéma exploitable par les moteurs modernes nécessite aussi :

  • un type de page explicite (WebPage, Article, BlogPosting…),
  • des mots-clés pertinents,
  • une URL canonique fiable,
  • des images optimisées pour les snippets.

💡 En enrichissant progressivement les front matter, une grande partie du schéma JSON-LD pouvait être sourcée là où l'information existait déjà.

Répartir les informations​

Pour bannir les redondances et obtenir une architecture claire et maintenable, il fallait séparer strictement le spécifique du global.

  • Le spécifique — titre, description, dates, type, image, mots-clés — sera défini dans les front matter.
  • Le commun — organisation, auteur récurrent, éditeur, graphe global — sera centralisé dans docusaurus.config.js.

Un travail préparatoire systématique​

J'ai donc enrichi l'ensemble de mes pages Markdown :

  • définitions uniques et conformes aux critères Google,
  • mots-clés non redondants,
  • images adaptées aux snippets,
  • types de page explicitement définis.

Ce travail a posé les fondations du plugin.

Ce que je retiens de cette expérience​

J'ai adoré ce travail en coulisses. Il a mêlé réflexion stratégique, apprentissage technique et véritable conception produit.

  • Une réflexion sur mon positionnement et sur ce que je souhaite dire de CoffeeCup.tech, de mon travail, et de moi en tant que rédactrice technique experte.
  • Un approfondissement du SEO, des données structurées et de l'écosystème Docusaurus.
  • Une démarche de conception produit : identifier un besoin réel, puis concevoir une solution durable et réutilisable.

Si vous travaillez sur un site Docusaurus riche, multilingue ou pensé pour durer, cette réflexion vous évitera des choix techniques coûteux à long terme.

Ce plugin n'est pas qu'un outil. C'est une façon de penser la documentation comme un graphe de données cohérent, lisible par les humains comme par les machines — et prêt pour les moteurs génératifs.

Dans la partie 2️⃣, j'entrerai dans le concret :

  • l'architecture du plugin,
  • la lecture et la validation des front matter,
  • la gestion du multilingue,
  • et la génération automatique de schémas JSON-LD cohérents, maintenables et AI-ready.

La suite arrive bientôt.