ContentLayer : cet Outil Fait Révolutionne Markdown dans NextJS !

Pourquoi j'utilise Markdown

Tout d'abord, pourquoi j'utilise Markdown pour créer du contenu pour NextJS ? J'ai utilisé Markdown chaque fois que j'ai pu, à la fois pour mes sites personnels et pour mon travail.

Et il y a de nombreuses raisons pour lesquelles je préfère Markdown. Pourquoi ? Parce que Markdown vous donne une liberté que d'autres solutions n'ont pas.

Il est gratuit. Vous n'avez besoin d'aucun outil supplémentaire. C'est un fichier texte simple. Cela signifie que vous pouvez le modifier dans n'importe quel éditeur de texte, même sur GitHub. Vous n'avez besoin de vous connecter nulle part. Cela signifie qu'il n'y a pas de verrou de fournisseur (de “vendor lockin” comme on dit en Anglais). Le fait qu'il s'agisse d'un fichier texte signifie que vous pouvez tracker votre contenu dans Git.

Et comme Markdown est un format reconnu, il est facile à importer et à exporter.

Si nécessaire, vous pouvez commencer avec Markdown et passer à autre chose plus tard si vous ne vous sentez plus à l'aise avec ce format.

Et vous pouvez ajouter des données supplémentaires en utilisant le "front matter", qui est une donnée formatée YAML en haut du fichier, entre deux lignes de trois tirets.

L'utilisation du front matter me permet de définir des données spécifiques pour mes articles de blog, mes éléments de portefeuille, mes pages et bien d'autres choses encore. En fait, pour n'importe quel contenu.

Par exemple, pour les éléments de mon portfolio, mon frontmatter se présente comme suit.

---
title: Forest Morning
slug: forest-morning
image: /images/portfolio/forest-morning.jpg
prompt: a dslr photography of a sunrise in a lush autumn forest, ethereal,cinematic tones, dramatic lighting, field of view --style 1f4tF7LChmCv2MWh --ar 16:9
width: 1456
height: 816
date: 2023-11-12
type: Portfolio
---

Vous pouvez voir que j'ai défini des chaînes de caractères comme le titre, le chemin d'accès à l'image, l'invite, etc. J'ai également défini quelques nombres (à savoir, ici, largeur et hauteur) et une date

Pour les articles de blog, mon frontmatter se présente comme suit.

---
title: "Angular vs React: which should you choose?"
slug: angular-vs-react
featuredImage: /images/blog/react_vs_angular.jpg
date: 2021-05-01T00:00:00.000Z
subtitle: Philosophical differences expressed visually
category: Frameworks
tags:
  - angular
  - react
lang: en
alts:
  - fr: angular-vs-react
type: Post
---

Comme vous pouvez le constater, certains champs tels que le titre, la balise et la date sont partagés. D'autres, comme l'invite, la largeur ou la catégorie, sont spécifiques au type de contenu concerné. Comme vous pouvez aussi le lire, YAML nous permet de créer des types de données plus complexes. Ici, tags est une liste de chaînes, et les liens alternatifs (la clé alt) est une liste d'objets clé-valeur.

Quel est le problème avec Markdown ?

Cependant, qui dit grande flexibilité dit aussi une grande responsabilité. Pour le dire autrement, cette flexibilité est aussi le plus gros défaut de Markdown.

Par exemple, je me suis rendu compte qu'à certains endroits, j'avais écrit "tag" au lieu de "tags". À d'autres endroits, j'avais utilisé image au lieu de featuredImage. Et ce contenu est introduit dans mon code, qui s'attend donc à ce que les champs soient nommés d'une certaine manière. Avec Markdown, je n'ai aucun moyen d'imposer la forme des données stockées dans la matière première. C'est dommage, car je suis un fan de Markdown.

De plus, la récupération du contenu est une corvée. Une fois que je l'ai configuré pour la première fois, j'ai copié-collé ce que j'avais fait d'un projet à l'autre. Pour utiliser markdown, vous avez besoin de la bibliothèque du système de fichiers, fs. Vous l'utilisez pour lister tous les fichiers, les charger et les analyser. Cependant, s'il y a deux choses que j'ai apprises en tant que développeur, c'est que :

• la lecture et l'écriture de fichiers au moment de l'exécution doivent être évitées autant que possible, et
• le copier-coller de code n'est pas une bonne chose.

Sur tous ces points, la façon dont j'utilisais Markdown me laissait un goût amer dans la bouche.

La solution que j'utilise

Tout d'abord, j'ai essayé de pré-parser tous les fichiers au moment de la construction. Ensuite, j'ai créé un JSON avec tout le contenu. Cela m'a permis de charger le catalogue de contenu en tant qu'importation. Cependant, j'avais toujours des types incohérents et la configuration contenait beaucoup de code personnalisé. J'ai donc commencé à me poser des questions sur les contrôles de codage pour la forme des données dans mon contenu de base.

Cependant, à peu près au même moment, je me suis penché sur le travail de ShadCN. ShadCN a créé la bibliothèque UI du même nom, que je regarde de plus près. Il travaille également sur un dépôt GitHub appelé Taxonomy. Taxonomy contient beaucoup de code intéressant si vous êtes intéressé par NextJS. Des choses comme l'intégration de bases de données et l'intégration de Stripe.

Et dans le dépôt Taxonomy, il a mentionné qu'il utilisait une bibliothèque appelée ContentLayer, alors j’ai regardé de quoi il s'agissait. Et j'ai beaucoup aimé ce que j'ai vu. A tel point que ce week-end, j'ai remplacé tout mon code de gestion du markdown par ContentLayer.

Pourquoi ? (je veux dire, à part le fait que je suis un mordu de la punition).

Eh bien, ContentLayer fait tout ce que j'essayais de coder moi-même.

Vous commencez par définir un schéma pour votre contenu. Par exemple, mon schéma pour les éléments du portfolio se ressemble à ceci.

export const Portfolio = defineDocumentType(() => ({
  name: 'Portfolio',
  filePathPattern: `portfolio/**/*.md`,

  fields: {
    title: { type: 'string', required: true },
    slug: { type: 'string', required: true },
    date: { type: 'date', required: true },
    image: { type: 'string', required: true },
    width: { type: 'number', required: true },
    height: { type: 'number', required: true },
    prompt: { type: 'string', required: false },
  }
}))

Comme vous pouvez le voir, le nom correspond au type de mon contenu, et je définis le chemin d'accès à l'endroit où mon contenu est stocké. Je définis également les différents champs, leur type et s'ils sont obligatoires. Par exemple, title, slug et image sont des chaînes obligatoires, width et height sont des nombres obligatoires, et prompt est une chaîne facultative.

J'indique à ContentLayer quel type de contenu j'ai et où il se trouve en appelant la fonction makeSource :

export default makeSource({
  contentDirPath: 'src/content',
  documentTypes: [Post, Product, Person, Portfolio]
});

En utilisant toutes les informations que je lui ai fournies, ContentLayer lit alors les fichiers qui correspondent aux chemins que j'ai indiqués. Il vérifie que

• le document de couverture correspond au schéma que j'ai défini,
• qu'il n'y a pas de champs supplémentaires,
• que tous les champs obligatoires sont présents
• et que tous les champs contiennent les bonnes données.

En utilisant le schéma, ContentLayer définit ensuite un type TypeScript que je peux utiliser dans mon code et un accesseur qui me fournit tout le contenu de ce type.

Cela signifie que toutes mes manipulations compliquées du système de fichiers à l'aide de fs et mon analyse de la matière première sont maintenant remplacées par un simple : import { allPortfolios, Portfolio } from 'contentlayer/generated' ;

J'ai passé le week-end à l'implémenter, mais savez-vous ce qui a pris tant de temps ? À vrai dire, le nettoyage de mon code a été rapide et facile. Ce qui a pris du temps, c'est de passer en revue tous les problèmes que ContentLayer n'arrêtait pas de trouver dans mon contenu. Aujourd'hui, non seulement mon code est beaucoup plus propre, mais mon contenu l'est également.

Mais maintenant que j'ai nettoyé mon contenu, comment puis-je le suivre et l'organiser ? J'utilise Notion et je me connecte à son API.