Sébastien Lorber

Nous sommes heureux d'annoncer Docusaurus 3.3.

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

We are happy to announce Docusaurus 3.2.

La mise à jour devrait être facile : comme expliqué dans notre documentation du processus de publication, les versions mineures respectent le versionnage sémantique.

Nous sommes heureux d'annoncer Docusaurus 3.1.

La mise à jour devrait être facile : comme expliqué dans notre documentation du processus de publication, les versions mineures respectent le versionnage sémantique.

Aujourd'hui, nous sommes heureux d'annoncer Docusaurus 3.0 ! 🥳

Chez Meta Open Source, nous pensons que Docusaurus vous aidera à construire les meilleurs sites web de documentation avec un minimum d'effort, vous permettant de vous concentrer sur ce qui compte vraiment : l'écriture du contenu.

Il s'agit d'une nouvelle version majeure de Docusaurus, avec de nouvelles fonctionnalités intéressantes et des dépendances mises à jour.

Conformément aux principes du Semantic Versioning, cette version inclut des changements de rupture que nous avons documentés en détail dans le guide de mise à jour de la version 3. Les changements de rupture peuvent être gênants, mais ils sont nécessaires pour préparer le terrain à une nouvelle vague de fonctionnalités Docusaurus que nous prévoyons d'implémenter.

Nous avions initialement prévu de publier des versions majeures plus fréquemment, mais Docusaurus v3 a pris plus de temps que prévu. Parmi les changements de rupture que nous avons comptabilisés, la montée de version vers MDX v3 est probablement le principal défi à l'adoption de cette nouvelle version. Nous avons fait un effort supplémentaire pour rendre cette montée de version aussi facile que possible, notamment en ajoutant des options de compatibilité pour MDX v1.

Les sites les plus simples n'auront besoin de mettre à jour que quelques dépendances npm. Pour les sites plus complexes, nous avons élaboré quelques stratégies qui peuvent vous aider à effectuer une mise à niveau en toute confiance :

• Préparez votre site à l'avance, progressivement, tout en restant sur Docusaurus v2
• Mettez en place des tests de régression visuelle pour détecter les changements visuels inattendus survenant au cours de la mise à jour

Changements de rupture​

Cette section ne donne qu'un bref aperçu. Toutes les changements de rupture sont documentés en détail dans le guide de mise à jour de la version 3.

Docusaurus v3 a mis à jour quelques dépendances vers de nouvelles versions majeures, chacune venant avec ses propres changements de rupture :

• Node.js v16 ➡️ v18
• React v17 ➡️ v18
• MDX v1 ➡️ v3
• TypeScript v4 ➡️ v5
• prism-react-renderer v1 ➡️ v2
• react-live v2 ➡️ v4
• Mermaid v9 ➡️ v10
• import-fresh v3 ➡️ jiti v1
• remark-emoji v2 ➡️ v4

Une mise à jour typique des dépendances de package.json ressemble à ceci :

 {
   "dependencies": {
     // upgrade to Docusaurus v3
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
+    "@docusaurus/core": "3.0.0",
+    "@docusaurus/preset-classic": "3.0.0",
     // upgrade to MDX v3
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^3.0.0",
     // upgrade to prism-react-renderer v2.0+
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
     // upgrade to React v18.0+
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
     // upgrade Docusaurus dev dependencies to v3
-    "@docusaurus/module-type-aliases": "2.4.3",
-    "@docusaurus/types": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0",
+    "@docusaurus/types": "3.0.0"
   }
   "engines": {
     // require Node.js 18.0+
-    "node": ">=16.14"
+    "node": ">=18.0"
   }
 }

A l'exception de MDX v3, la plupart des changements de rupture provenant de ces dépendances, qui ont été mises à jour, ont été gérés en interne pour vous : la plupart du temps, vous ne devriez pas avoir à faire quoi que ce soit. En dehors des dépendances, les seuls changements de rupture fonctionnels provenant explicitement de la base de code de Docusaurus sont les suivantes :

• #9189 : nouveau flux RSS de blog par défaut limité à 20 entrées
• #9308 : corrige et réintroduit l'admonition :::warning, supprime :::caution
• #9310 : supprime l'ancien préfixe d'identification de la barre latérale, utilisé pour les sites dont la version est antérieure à v2.0.0-beta.10 (décembre 2021)
• #7966 : refactorise les composants du thème des docs, ce qui vous oblige éventuellement à les re-swizzler

Points importants​

Voici une liste non exhaustive des nouvelles fonctionnalités utiles de cette nouvelle version. Toutes les fonctionnalités sont listées dans les notes de version de Docusaurus v3.0.0.

Markdown​

Docusaurus v3 met à jour MDX v1 en MDX v3 :

• dans #8288, nous avons mis à jour vers MDX v2 (guide de migration)
• dans #9451, nous avons mis à jour vers MDX v3 (guide de migration)

Cette nouvelle version de MDX est bien meilleure pour les rédacteurs de contenu et les auteurs de plugins, et prépare le terrain pour l'implémentation de nouvelles fonctionnalités Markdown passionnantes.

Cela nous permet notamment d'ajouter un mode CommonMark qui devrait faciliter l'adoption de Docusaurus pour les documentations existantes. Elle est actuellement facultative, expérimentale et limitée (certaines fonctionnalités de Docusaurus ne fonctionneront pas). Dans Docusaurus v3, tous les fichiers sont encore interprétés en MDX, mais nous prévoyons d'interpréter les fichiers .md en CommonMark dans une prochaine version majeure, et nous recommandons d'utiliser l'extension .mdx pour tout fichier utilisant les modules JSX ou ES.

Nous avons également introduit une nouvelle façon de configurer le Markdown globalement pour votre site, et nous prévoyons d'ajouter des options plus flexibles ultérieurement.

export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

Docusaurus utilise désormais le plugin remark-directive pour prendre en charge les admonitions. Cela vous offre également la possibilité de créer vos propres plugins Remark pour étendre Markdown avec vos propres directives personnalisées telles que :textDirective, ::leafDirective ou :::containerDirective.

Configs ESM et TypeScript​

Dans #9317, nous avons ajouté la prise en charge des modules ES et des fichiers de config TypeScript, y compris la config du site, les barres latérales des docs, les plugins et les presets.

Voici 2 exemples TypeScript, vous donnant une expérience moderne avec l'autocomplétion de l'IDE :

import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'Mon Site',
  favicon: 'img/favicon.ico',
  // Votre config de site ...
  presets: [
    [
      'classic',
      {
        // Votre config de preset ...
      } satisfies Preset.Options,
    ],
  ],
  themeConfig: {
    // Votre config de thème ...
  } satisfies Preset.ThemeConfig,
};

export default config;

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  docs: ['introduction'],
};

export default sidebars;

Contenu non listé​

Docusaurus prenait déjà en charge l'option draft : true dans nos 3 plugins de contenu (docs, blog, pages), ce qui vous permet de supprimer certaines pages de vos versions de production.

Dans #8004, nous avons introduit une nouvelle option unlisted : true, qui gardera vos pages disponibles dans les constructions de production, tout en les « cachant » et en les rendant impossibles à découvrir à moins que vous n'ayez l'url. Cela permet de mettre en place des flux de travail utiles où vous pouvez facilement demander un avis sur un élément de contenu avant la publication finale.

Le contenu non listé sera :

• exclu de sitemap.xml
• exclu des résultats de référencement grâce à <meta name="robots" content="noindex, nofollow" />
• exclu des flux RSS du blog
• exclu des résultats d'Algolia DocSearch
• filtré à partir des éléments de la barre de navigation du site, des barres latérales des docs, de la barre latérale du blog, des archives du blog, des tags des pages...

Les contenus non listés affichent également une bannière afin que vous n'oubliiez pas de la désactiver une fois que votre contenu est prêt pour le grand jour. Voici un exemple d'article du blog non listé :

React 18​

Dans #8961, nous avons fait la mise à jour vers React 18. C'est important, notamment pour l'adoption progressive des fonctionnalités Concurrent de React, ainsi que pour les fonctionnalités prometteuses à venir telles que les composants de serveur React à l'exécution de la construction.

Cette nouvelle version de React devrait pouvoir remplacer la plupart des sites Docusaurus. Elle s'accompagne de changements de rupture que nous avons gérés en interne dans la base de code de Docusaurus. Si votre site utilise beaucoup de code React personnalisé, nous vous recommandons de consulter l'article officiel sur Comment passer à React 18, notamment le nouveau comportement de batching automatique.

Exécution automatique du JSX​

Docusaurus v3 utilise désormais le runtime JSX « automatique ».

Il n'est plus nécessaire d'importer React dans les fichiers JSX qui n'utilisent aucune API React.

- import React from 'react';

  export default function MyComponent() {
    return <div>Hello</div>;
  }

Débogage des constructions​

Il est maintenant possible de construire votre site statique en mode dev.

docusaurus build --dev

TypeScript​

Docusaurus v3 nécessite maintenant une version minimale de TypeScript 5.0.

Nous avons réinternalisé la config TypeScript de base recommandée dans un nouveau package officiel :

 {
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
   }
 }

Nous avons également des exportations plus propres et normalisées pour le type du noyau de Docusaurus, les plugins et les options de preset, que vous pouvez utiliser dans les tous nouveaux fichiers de configuration TypeScript :

import type {Config} from '@docusaurus/types';
import type {Options, ThemeConfig} from '@docusaurus/preset-classic';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

Blocs de code​

Dans #9316, nous avons amélioré la coloration syntaxique grâce à la mise à jour de prism-react-renderer v2. Par exemple, le paramètre bash --save est maintenant colorisé :

npm install --save some-package

L'éditeur de code interactif passe également à react-live v4, avec un nouveau compilateur sucrase. Il est plus rapide, plus léger et prend en charge des fonctionnalités modernes, notamment les annotations de type TypeScript.

function Hello() {
  const name: string = 'World';
  return <div>Hello {name}</div>;
}

Dans #8982 et #8870, nous avons également ajouté la prise en charge des commentaires magiques pour les syntaxes de commentaires de type TeX, Haskell et WebAssembly.

stringLength :: String -> Int
stringLength [] = 0
stringLength (x:xs) = 1 + stringLength xs

function result = times2(n)
  result = n * 2;
end
x = 10;
y = times2(x);

Diagrammes Mermaid​

Dans #9305, nous avons mis à jour Mermaid v10.4 et ajouté la prise en charge du rendu asynchrone des diagrammes. Docusaurus est maintenant en mesure de rendre de nouveaux types de diagrammes.

Attributs de données de la chaîne de requête​

Dans #9028, nous avons rendu possible la définition d'attributs de données HTML personnalisés à travers les paramètres de la chaîne de requête docusaurus-data-x. Cela facilite l'intégration d'un iframe Docusaurus sur un autre site et vous permet de personnaliser l'apparence de la version intégrée à l'aide de CSS.

html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

Autres fonctionnalités​

Autres nouvelles fonctionnalités à mentionner :

• #9189 : nouvelle option du blog feedOptions.limit
• #9071 : ajout d'un support de référencement normalisé pour le plugin de pages
• #9171 : le plugin client-redirects prend désormais en charge les urls qualifiés et query-string/hash dans l'url de destination
• #9171 : nouvelle règle ESLint no-html-links
• #8384 : nouvelle règle ESLint prefer-docusaurus-heading

Consultez les notes de version de Docusaurus v3.0.0 pour une liste exhaustive des changements.

Conclusion​

Cette version est fournie avec quelques fonctionnalités, mais plus important encore, met à jour de nombreuses pièces de l'infrastructure Docusaurus.

La mise à jour MDX a consommé beaucoup de notre temps cette année, et nous avons travaillé dur pour rendre cette importante mise à jour moins difficile pour vous tous.

Maintenant que nous avons rattrapé notre retard en matière d'infrastructure, nous serons de retour pour délivrer des fonctionnalités de documentation utiles très bientôt, dans les prochaines versions mineures.

Nous vous remercions d'utiliser Docusaurus au fil des ans. Le marché des frameworks de documentation devient de plus en plus concurrentiel ces derniers temps, et nous ferons de notre mieux pour que Docusaurus reste une solution compétitive qui se distingue par sa grande flexibilité.

Docusaurus v3 est maintenant en beta et la sortie officielle est imminente. C'est le moment idéal pour commencer à préparer votre site pour cette nouvelle version majeure.

Docusaurus v3 comporte quelques changements de rupture, dont beaucoup peuvent être traités aujourd'hui avec Docusaurus v2. La préparation de votre site en amont peut se faire de manière progressive et facilitera la mise à niveau vers la v3.

Le principal changement de rupture est la mise à jour de MDX v1 vers MDX v3. Lisez les notes de version pour MDX v2 et MDX v3 pour plus de détails. MDX compile maintenant votre contenu Markdown plus strictement et avec des différences subtiles.

Cet article se concentrera principalement sur la façon de préparer votre contenu pour cette nouvelle version de MDX, et énumérera également quelques autres changements de rupture que vous pouvez traiter dès aujourd'hui.