MDX, collections de contenu et le contenu en tant qu'architecture

Le mode d’échec le plus courant lors de l’adoption de MDX ou de Markdown dans un framework JavaScript est de le traiter comme un traitement de texte glorifié.

Les équipes configurent un parseur, déposent cinquante fichiers .mdx dans un dossier /content et supposent qu’elles ont un système de publication. Six mois plus tard, elles ont un tas d’articles non typés. Le frontmatter est incohérent. Les pages de guide utilisent une mise en page différente de celle des articles de blog, mais uniquement parce qu’un auteur s’est souvenu d’importer le bon composant. La réorganisation de la documentation nécessite une recherche regex sur l’ensemble du dépôt.

Lorsque votre produit est du matériel de lecture, votre modèle de contenu est votre architecture.

La thèse du contenu en tant qu’architecture

Dans une publication basée sur des fichiers comme Interface Atlas, vous devez cesser de considérer le dossier src/content/ comme un seau de stockage. C’est une base de données.

S’il s’agit d’une base de données, elle a besoin d’un schéma. Elle a besoin de relations. Elle a besoin de contraintes. Dans Astro, nous imposons cette architecture à l’aide de Collections de contenu.

Le dépôt en tant que système de publication

graph TD
    subgraph La couche base de données
        C1[Collection Guides] -->|Valide via Zod| S1(Schéma Guide)
        C2[Collection Glossaire] -->|Valide via Zod| S2(Schéma Glossaire)
    end
    
    subgraph La couche graphe
        S1 -->|topicKeys| T[Hubs de Sujets]
        S1 -->|glossaryKeys| C2
    end
    
    subgraph La couche présentation
        T --> R1[Route Astro Sujet]
        C1 --> R2[Route Astro Guide]
        C2 --> R3[Route Astro Glossaire]
    end

Passer de Markdown aux collections de contenu

Le tas non typé (Le mode d’échec)

Avant les collections de contenu, les frameworks chargeaient les fichiers markdown via des importations glob. Vous obteniez n’importe quel frontmatter tapé par l’auteur. Si un auteur tapait diffculty: hard au lieu de difficulty: Advanced, la compilation (build) réussissait, mais la page laissait tomber silencieusement le badge de difficulté. La logique de contenu devenait cachée dans des composants d’interface fragiles essayant d’analyser des données corrompues.

La collection typée (La solution)

Les collections de contenu d’Astro corrigent cela en introduisant une frontière stricte entre le contenu et le rendu.

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

export const guides = defineCollection({
  loader: glob({ pattern: "**/*.mdx", base: "./src/content/guides" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    topicKeys: z.array(z.string()), // Impose la relation de graphe
    difficulty: z.enum(["Foundation", "Intermediate", "Advanced"]), // Empêche les fautes de frappe
  }),
});

Ce code enseigne une conséquence architecturale : Les erreurs de contenu sont désormais des erreurs de compilation. Si un auteur oublie le tableau topicKeys, la compilation d’Astro échoue. Le site ne peut pas être déployé dans un état cassé.

Frontmatter est le schéma relationnel

Une fois que vous avez des collections typées, le Frontmatter cesse d’être juste un endroit pour mettre le titre. Il devient le schéma relationnel qui construit votre graphe de contenu.

Dans Interface Atlas, nous ne codons pas en dur les « Guides connexes » au bas des fichiers MDX. Nous utilisons des clés frontmatter :

---
title: "Architecture de l'information"
topicKeys: ["architecture", "seo"]
glossaryKeys: ["taxonomy"]
relatedGuideKeys: ["what-frontend-architecture-really-is"]
---

Parce que cela est fortement typé, la couche de routage peut générer automatiquement les liens connexes, les puces de hub de sujet et les info-bulles de glossaire.

Le workflow éditorial basé sur Git

Lorsque le dépôt est le CMS, le workflow Git est le workflow éditorial.

Brouillon : Un auteur crée une branche et écrit un fichier MDX.
Révision : La Pull Request devient la révision éditoriale. Les réviseurs peuvent commenter la prose de la même manière qu’ils commentent le code.
Validation : La CI/CD exécute la compilation Astro. Le schéma valide le frontmatter et MDX valide la syntaxe du composant.
Publication : La fusion vers main déclenche un déploiement statique vers la périphérie (edge).

Ce flux de travail échoue lorsque les équipes tentent de forcer des éditeurs non techniques à utiliser GitHub directement sans un outil comme Decap CMS, ou lorsque les fichiers MDX deviennent tellement pollués par du JSX complexe que les auteurs ne peuvent plus lire le texte.

Quand MDX ne suffit pas

MDX est un support hybride. Il vous permet d’intégrer des composants interactifs complexes directement dans un texte long. Mais vous devez savoir quand vous arrêter.

Si un fichier MDX contient 40 lignes de prose et 300 lignes de gestion d’état React complexe, vous avez franchi une limite. Le contenu est désormais soumis à la logique de l’application.

La Règle : Gardez les fichiers MDX concentrés sur la lecture. Si un widget interactif nécessite un état local complexe, abstrayez-le dans un composant Island et passez-lui des props simples à partir du fichier MDX.

Guides et termes associés

Explorez les systèmes de support :

Architecture de l’information et architecture de contenu — Comment la structure du contenu favorise la découvrabilité.
L’anatomie d’un excellent guide technique — Comment écrire du contenu pour ce système.
Choisir la bonne pile — Pourquoi Astro est un bon choix pour ce modèle.

Sommaire