Aller au contenu principal
Version: Canary 🚧

Montée de version vers Docusaurus v3

Cette documentation vous aidera à mettre à jour votre site de Docusaurus v2 à Docusaurus v3.

Docusaurus v3 est une nouvelle version majeure, comprenant des changements de rupture vous obligeant à adapter votre site en conséquence. Nous vous guiderons tout au long de ce processus, et mentionnerons également quelques recommandations facultatives.

Il ne s'agit pas d'une réécriture complète, et les changements de rupture sont relativement faciles à gérer. Les sites les plus simples se mettront finalement à jour en mettant simplement à jour leurs dépendances npm.

The main breaking change is the upgrade from MDX v1 to MDX v3. Read the MDX v2 and MDX v3 release notes for details. MDX will now compile your Markdown content more strictly and with subtle differences.

Avant la montée de version

Avant de mettre à jour, nous vous recommandons la Préparation de votre site pour Docusaurus v3. Il y a des changements que vous pouvez déjà gérer incrémentalement, sous Docusaurus v2. Cela permettra de réduire le travail nécessaire pour passer à Docusaurus v3.

Pour les sites complexes, nous recommandons également de mettre en place des tests de régression visuelle, un bon moyen de s'assurer que votre site reste visuellement identique. Docusaurus v3 met principalement à jour les dépendances, et ne devrait pas produire de changements visuels.

remarque

Consultez les notes de version pour Docusaurus v3.0.0, et parcourez les pull-requests pour des informations utiles supplémentaires et la motivation derrière chaque changement mentionné ici.

Mise à jour des dépendances​

La mise à jour vers Docusaurus v3 nécessite la mise à jour des dépendances de Docusaurus (@docusaurus/name), mais aussi d'autres paquets connexes.

Docusaurus v3 utilise maintenant les dépendances suivantes :

  • Node.js v18.0+
  • React v18.0+
  • MDX v3.0+
  • TypeScript v5.0+
  • prism-react-renderer v2.0+
  • react-live v4.0+
  • remark-emoji v4.0+
  • mermaid v10.4+
Mise à jour des plugins communautaires

Si votre site utilise des plugins et des thèmes tiers de la communauté, vous devrez peut-être les mettre à jour.

Assurez-vous que ces plugins sont compatibles avec Docusaurus v3 avant de tenter une mise à niveau.

Un exemple typique de mise à jour de dépendance du package.json :

package.json
 {
   "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 v2
-    "@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"
   }
 }

Pour les utilisateurs de TypeScript :

package.json
 {
   "devDependencies": {
     // remplace le paquet externe de configuration TypeScript par le nouveau paquet officiel
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "3.0.0",
     // met à jour les types React en v18.0+
-    "@types/react": "^17.0.69",
+    "@types/react": "^18.2.29",
     // montée de version de TypeScript vers v5.0+
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

Mise à jour de MDX​

MDX est une dépendance majeure de Docusaurus responsable de la compilation de vos fichiers .md et .mdx en composants React.

The transition from MDX v1 to MDX v3 is the main challenge to the adoption of Docusaurus v3. Most breaking changes come from MDX v2, and MDX v3 is a relatively small release.

Certains documents qui ont été compilés avec succès sous Docusaurus v2 peuvent maintenant ne pas se compiler sous Docusaurus v3.

Repérer à l'avance les contenus problématiques

Lancez npx docusaurus-mdx-checker sur votre site pour obtenir une liste des fichiers qui ne pourront plus être compilés sous Docusaurus v3.

Cette commande est également un bon moyen d'estimer la quantité de travail à faire pour rendre votre contenu compatible. N'oubliez pas que la plupart de ces travaux peuvent être exécutés avant la mise à jour en préparant votre contenu pour Docusaurus v3.

D'autres documents peuvent également se présenter différemment.

Utiliser les tests de régression visuelle

Pour les grands sites où une revue manuelle de toutes les pages est compliquée, nous vous recommandons de configurer des tests de régression visuels.

Upgrading MDX comes with all the breaking changes documented on the MDX v2 and MDX v3 release blog posts. Most breaking changes come from MDX v2. Le guide de migration MDX v2 contient une section sur la façon de mettre à jour les fichiers MDX qui sera particulièrement pertinente pour nous. Assurez-vous également de lire la page Troubleshooting MDX qui peut vous aider à interpréter les messages d'erreur MDX les plus courants.

Veillez également à lire notre page de documentation actualisée de MDX et React.

Utilisation du terrain de jeu MDX​

Le terrain de jeu du MDX est votre nouveau meilleur ami. Il permet de comprendre comment votre contenu est compilé en composants React, et de résoudre les problèmes de compilation ou de rendu de manière isolée.

Configuring the MDX playground options for Docusaurus

To obtain a compilation behavior similar to what Docusaurus v2 uses, please turn on these options on the MDX playground:

  • Use MDX
  • Use remark-gfm
  • Use remark-directive

Screenshot of the MDX playground's options panel, with only the "Use `MDX`", "Use `remark-gfm`", and "Use `remark-directive`" options checked

En utilisant les deux terrains de jeu MDX côte à côte, vous remarquerez rapidement que certains contenus sont compilés différemment ou ne se compilent pas dans la v2.

Faire en sorte que votre contenu soit prêt pour l'avenir

L'objectif est de remanier votre contenu problématique afin qu'il fonctionne correctement avec les deux versions du MDX. Ainsi, lorsque vous passerez à Docusaurus v3, ce contenu sera déjà prêt à l'emploi.

Utilisation du CLI de vérification du MDX​

Nous fournissons un CLI docusaurus-mdx-checker qui permet de repérer facilement les contenus problématiques. Run this command on your site to obtain a list of files that will fail to compile under MDX v3.

npx docusaurus-mdx-checker

Pour chaque problème de compilation, le CLI enregistre le chemin d'accès au fichier et un numéro de ligne à consulter.

Screenshot of the terminal showing an example MDX checker CLI output, with a few error messages

astuce

Use this CLI to estimate of how much work will be required to make your content compatible with MDX v3.

attention

This CLI is a best effort, and will only report compilation errors.

Il ne signale pas les modifications subtiles de la compilation qui ne produisent pas d'erreurs mais qui peuvent affecter l'affichage de votre contenu. Pour détecter ces problèmes, nous recommandons d'utiliser des tests de régression visuels.

Problèmes fréquents du MDX​

Docusaurus cannot document exhaustively all the changes coming with MDX. That's the responsibility of the MDX v2 and MDX v3 migration guides.

However, by upgrading a few Docusaurus sites, we noticed that most of the issues come down to only a few cases that we have documented for you.

Mauvaise utilisation de {​

Le caractère { est utilisé pour ouvrir des expressions JavaScript. MDX will now fail if what you put inside {expression} is not a valid expression.

example.md
La forme de l'objet ressemble à {username: string, age: number}
Message d'erreur

Could not parse expression with acorn: Unexpected content after expression

How to upgrade

Options disponibles pour corriger cette erreur :

  • Utilisez le code en ligne : {username: string, age: number}
  • Utilisez le code HTML : {
  • Échappez-le  : \{

Mauvaise utilisation de <​

Le caractère < est utilisé pour ouvrir des balises JSX. MDX will now fail if it thinks your JSX is invalid.

example.md
Utiliser la version Android <5

Vous pouvez utiliser un type générique comme Array<T>

Suivez le modèle "Road to <YOUR_MINOR_VERSION>"
Messages d'erreur

Unexpected character 5 (U+0035) before name, expected a character that can start a name, such as a letter, $, or _

Expected a closing tag for <T> (1:6-1:9) before the end of paragraph end-tag-mismatch mdast-util-mdx-jsx

Expected a closing tag for <YOUR_MINOR_VERSION> (134:19-134:39) before the end of paragraph

How to upgrade

Options disponibles pour corriger cette erreur :

  • Utilisez le code en ligne : Array<T>
  • Utilisez le code HTML : &lt; ou &#60;
  • Escape it: \<

Docusaurus supports GitHub Flavored Markdown (GFM), but autolink using the <link> syntax is not supported anymore by MDX.

example.md
<sebastien@thisweekinreact.com>

<http://localhost:3000>
Messages d'erreur

Unexpected character @ (U+0040) in name, expected a name character such as letters, digits, $, or _; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use [text](url))

Unexpected character / (U+002F) before local name, expected a character that can start a name, such as a letter, $, or _ (note: to create a link in MDX, use [text](url))

How to upgrade

Utilisez des liens Markdown classiques, ou supprimez les < et >. MDX et GFM sont déjà en mesure d'établir des liens automatiques avec les littéraux.

example.md
sebastien@thisweekinreact.com
[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)

http://localhost:3000
[http://localhost:3000](http://localhost:3000)

Correspondance de MDXComponent en minuscules​

For users providing a custom MDXComponentmapping, components are now "sandboxed":

  • une correspondance de MDXComponent pour h1 n'est utilisée que pour # hi mais pas pour <h1>hi</h1>
  • un nom d'élément personnalisé en minuscules ne sera plus remplacé par son composant MDXComponent respectif
différence visuelle

Your MDXComponent component mapping might not be applied as before, and your custom components might no longer be used.

How to upgrade

Pour les éléments Markdown natifs, vous pouvez continuer à utiliser les minuscules : p, h1, img, a...

Pour tout autre élément, utiliser des noms en majuscules.

src/theme/MDXComponents.js
 import MDXComponents from '@theme-original/MDXComponents';

 export default {
   ...MDXComponents,
   p: (props) => <p {...props} className="my-paragraph"/>
-  myElement: (props) => <div {...props} className="my-class" />,
+  MyElement: (props) => <div {...props} className="my-class" />,
 };

Paragraphes supplémentaires involontaires​

In MDX v3, it is now possible to interleave JSX and Markdown more easily without requiring extra line breaks. L'écriture d'un contenu sur plusieurs lignes peut également produire de nouvelles balises <p> attendues.

différence visuelle

See how this content is rendered differently by MDX v1 and v3.

example.md
<div>Un peu de contenu **Markdown**</div>
<div>
  Un peu de contenu **Markdown**
</div>
MDX v1 output
<div>Un peu de contenu **Markdown**</div>
<div>Un peu de contenu **Markdown**</div>
MDX v3 output
<div>Un peu de contenu <strong>Markdown</strong></div>
<div><p>Un peu de contenu <strong>Markdown</strong></p></div></div>
How to upgrade

Si vous ne voulez pas de balise <p> supplémentaire, remaniez le contenu au cas par cas pour utiliser une balise JSX sur une seule ligne.

 <figure>
   <img src="/img/myImage.png" alt="My alt" />
-  <figcaption>
-    Légende de mon image
-  </figcaption>
+  <figcaption>Légende de mon image</figcaption>
 </figure>

Utilisation involontaire de directives​

Docusaurus v3 utilise désormais des directives Markdown (mises en œuvre avec remark-directive) comme moyen générique de fournir un support pour les admonitions, et d'autres fonctionnalités à venir de Docusaurus.

example.md
Ceci est un :texteDeDirective

::directiveFeuille

:::conteneurDeDirective

Contenu du conteneur de la directive

:::
Changement visuel

Les directives sont analysées dans le but d'être traitées par d'autres plugins Remark. Les directives non traitées seront ignorées et ne seront pas restituées dans leur forme originale.

example.md
La conférence AWS re:Invent est formidable

En raison de l'analyse de :Invent en tant que directive de texte, ceci sera maintenant rendu ainsi :

La conférence AWS re
est formidable
How to upgrade
  • Utilisez le code HTML : &#58;
  • Ajoutez un espace après : (si cela a du sens) : : texte
  • Escape it: \:

Blocs de code indentés non pris en charge​

MDX does not transform indented text as code blocks anymore.

example.md
    console.log("hello");
Changement visuel

The upgrade does not generally produce new MDX compilation errors, but can lead to content being rendered in an unexpected way because there isn't a code block anymore.

How to upgrade

Utilisez la syntaxe du bloc de code normal au lieu de l'indentation :

example.md
```js
console.log('hello');
```

Plugins MDX​

Tous les paquets officiels (Unified, Remark, Rehype...) dans l'écosystème MDX sont désormais des Modules ES uniquement et ne supportent plus [CommonJS] (https://nodejs.org/api/modules.html#modules-commonjs-modules).

En pratique, cela signifie que vous ne pouvez plus faire de require("remark-plugin").

How to upgrade

Docusaurus v3 prend désormais en charge les fichiers de configuration ES Modules. Nous vous recommandons de migrer votre fichier de config vers le ES module, qui vous permet d'importer facilement les plugins Remark :

docusaurus.config.js
import remarkPlugin from 'remark-plugin';

export default {
  title: 'Docusaurus',
  /* config du site à l'aide des plugins remark ici */
};

Si vous souhaitez continuer à utiliser les modules CommonJS, vous pouvez utiliser les importations dynamiques comme solution de contournement qui vous permet d'importer des modules ES à l'intérieur d'un module CommonJS. Heureusement, la config de Docusaurus prend en charge l'utilisation d'une fonction asynchrone qui vous permet de le faire.

docusaurus.config.js
module.exports = async function () {
  const myPlugin = (await import('remark-plugin')).default;
  return {
    // config du site...
  };
};
Pour les auteurs de plugins

Si vous avez créé des plugins Remark ou Rehype personnalisés, vous devrez peut-être les refactoriser, voire les réécrire complètement, étant donné la façon dont le nouveau système AST est structuré. Nous avons créé une discussion d'assistance dédiée pour aider les auteurs de plugins à mettre à jour leur code.

Other Breaking Changes​

Apart the MDX v3 upgrade, here is an exhaustive list of breaking changes coming with Docusaurus v3.

Node.js v18.0​

Node.js 16 a atteint sa fin de vie, et Docusaurus v3 nécessite désormais Node.js >= 18.0.

How to upgrade

Install Node.js 18.0+ on your computer.

Eventually, configure your continuous integration, CDN or host to use this new Node.js version.

You can also update your site package.json to prevent usage of an older unsupported version:

package.json
 {
   "engines": {
-     "node": ">=16.14"
+     "node": ">=18.0"
   }
 }

Veuillez mettre à jour votre site Docusaurus v2 vers Node.js 18 avant de passer à Docusaurus v3.

React v18.0+​

Docusaurus v3 nécessite désormais React >= 18.0.

React 18 s'accompagne de ses propres changements de rupture qui devraient être relativement faciles à gérer, selon la quantité de code React personnalisé que vous avez créé pour votre site. The official themes and plugins are compatible with React 18.

How to upgrade

Read the official React v18.0 and How to Upgrade to React 18, and look at your own React code to figure out which components might be affected this upgrade.

Nous recommandons de vérifier tout particulièrement les points suivants :

  • Le traitement automatique des composants avec état
  • Les nouvelles erreurs d'hydratation de React signalées dans la console
Experimental support for React 18 features

React 18 comes with new features:

  • <Suspense>
  • React.lazy()
  • startTransition

Their Docusaurus support is considered as experimental. We might have to adjust the integration in the future, leading to a different runtime behavior.

Prism-React-Renderer v2.0+​

Docusaurus v3 upgrades prism-react-renderer to v2.0+. This library is used for code block syntax highlighting.

How to upgrade

This is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. The prism-react-renderer v2 release notes are not super exhaustive, but there are 3 major changes to be aware of for Docusaurus users.

The dependency should be upgraded:

package.json
 {
   "dependencies": {
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
 }

The API to import themes in your Docusaurus config file has been updated:

docusaurus.config.js
- const lightTheme = require('prism-react-renderer/themes/github');
- const darkTheme = require('prism-react-renderer/themes/dracula');
+ const {themes} = require('prism-react-renderer');
+ const lightTheme = themes.github;
+ const darkTheme = themes.dracula;

Previously, react-prism-render v1 included more languages by default. From v2.0+, less languages are included by default. You may need to add extra languages to your Docusaurus config:

docusaurus.config.js
const siteConfig = {
  themeConfig: {
    prism: {
      additionalLanguages: ['bash', 'diff', 'json'],
    },
  },
};

React-Live v4.0+​

For users of the @docusaurus/theme-live-codeblock package, Docusaurus v3 upgrades react-live to v4.0+.

How to upgrade

In theory, you have nothing to do, and your existing interactive code blocks should keep working as before.

However, this is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. Read the v3 and v4 changelogs in case of problems.

remark-emoji v4.0+​

Docusaurus v3 upgrades prism-react-renderer to v4.0+. This library is to support :emoji: shortcuts in Markdown.

How to upgrade

Most Docusaurus users have nothing to do. Users of emoji shortcodes should read the changelog and double-check their emojis keep rendering as expected.

Breaking Change Update node-emoji from v1 to v2. This change introduces support for many new emojis and removes old emoji short codes which are no longer valid on GitHub.

Mermaid v10.4+​

For users of the @docusaurus/theme-mermaid package, Docusaurus v3 upgrades mermaid to v10.4+.

How to upgrade

In theory, you have nothing to do, and your existing diagrams should keep working as before.

However, this is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. Read the v10 changelog in case of problem.

TypeScript v5.0+​

Docusaurus v3 nécessite désormais TypeScript >= 5.0.

How to upgrade

Upgrade your dependencies to use TypeScript 5+

package.json
 {
   "devDependencies": {
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

Configuration de base de TypeScript​

La configuration officielle de TypeScript de Docusaurus a été réinternalisée depuis le paquet externe @tsconfig/docusaurus vers notre nouveau paquet monorepo @docusaurus/tsconfig.

Ce nouveau paquet est versionné en même temps que tous les autres paquets de base de Docusaurus, et il sera utilisé pour assurer la rétro-compatibilité de TypeScript et les changements de rupture lors des mises à jour de versions majeures.

How to upgrade

Swap the external TypeScript config package for the new official one

package.json
 {
   "devDependencies": {
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "3.0.0",
   }
 }

Use it in your tsconfig.json file:

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

New Config Loader​

Docusaurus v3 changes its internal config loading library from import-fresh to jiti. It is responsible for loading files such as docusaurus.config.js or sidebars.js, and Docusaurus plugins.

How to upgrade

In theory, you have nothing to do, and your existing config files should keep working as before.

However, this is a major dependency swap and subtle behavior changes could occur.

Admonition Warning​

Pour des raisons historiques, nous prenons en charge un admonition non documenté :::warning qui s'affiche avec une couleur rouge.

Attention

Ceci est une admonition de Docusaurus v2 :::warning.

However, the color and icon have always been wrong. Docusaurus v3 réintroduit officiellement l'admonition :::warning, la documente, et corrige la couleur et l'icône.

attention

Ceci est une admonition de Docusaurus v3 :::warning.

How to upgrade

Si vous utilisiez auparavant l'admonition non documentées :::warning, vérifiez pour chaque utilisation si le jaune est maintenant une couleur appropriée. Si vous voulez conserver la couleur rouge, utilisez :::danger à la place.

Docusaurus v3 a aussi déprécié l'admonition :::caution. Veuillez refactoriser :::caution (jaune) soit en :::warning (jaune) soit en :::danger (rouge).

Versioned Sidebars​

Ce changement de rupture n'affectera que les utilisateurs de Docusaurus v2 qui ont versionné leurs documents avant la v2.0.0-beta.10 (décembre 2021).

Lors de la création de la version v1.0.0, le fichier sidebar contenait un préfixe version-v1.0.0/ que Docusaurus v3 ne prend plus en charge.

versioned_sidebars/version-v1.0.0-sidebars.json
{
  "version-v1.0.0/docs": [
    "version-v1.0.0/introduction",
    "version-v1.0.0/prerequisites"
  ]
}
How to upgrade

Remove the useless versioned prefix from your versioned sidebars.

versioned_sidebars/version-v1.0.0-sidebars.json
{
  "docs": ["introduction", "prerequisites"]
}

Blog Feed Limit​

The @docusaurus/plugin-content-blog now limits the RSS feed to the last 20 entries by default. For large Docusaurus blogs, this is a more sensible default value to avoid an increasingly large RSS file.

How to upgrade

In case you don't like this new default behavior, you can revert to the former "unlimited feed" behavior with the new limit: false feed option:

docusaurus.config.js
const blogOptions = {
  feedOptions: {
    limit: false,
  },
};

Docs Theme Refactoring​

For users that swizzled docs-related theme components (like @theme/DocPage), these components have been significantly refactor to make it easier to customize.

Technically, this is not a breaking change because these components are flagged as unsafe to swizzle, however many Docusaurus sites ejected docs-related components, and will be interested to know their customizations might break Docusaurus.

How to upgrade

Delete all your swizzled components, re-swizzle them, and re-apply your customizations on top of the newly updated components.

Alternatively, you can look at the pull-request notes to understand the new theme component tree structure, and eventually try to patch your swizzled components manually.

Optional Changes​

Some changes are not mandatory, but remain useful to be aware of to plainly leverage Docusaurus v3.

Automatic JSX runtime​

Docusaurus v3 now uses the React 18 "automatic" JSX runtime.

It is not needed anymore to import React in JSX files that do not use any React API.

src/components/MyComponent.js
- import React from 'react';

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

ESM and TypeScript Configs​

Docusaurus v3 supports ESM and TypeScript config files, and it might be a good idea to adopt those new options.

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};
docusaurus.config.ts
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'My Site',
  favicon: 'img/favicon.ico',
  presets: [
    [
      'classic',
      {
        /* Your preset config here */
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    /* Your theme config here */
  } satisfies Preset.ThemeConfig,
};

export default config;

Using the .mdx extension​

We recommend using the .mdx extension whenever you use JSX, import, or export (i.e. les fonctionnalités MDX) dans un fichier Markdown. Elle est plus correcte sémantiquement et améliore la compatibilité avec les outils externes (IDE, formateurs, linters, etc.).

Dans les versions futures de Docusaurus, les fichiers .md seront analysés comme du CommonMark standard, qui ne prend pas en charge ces fonctionnalités. Dans Docusaurus v3, les fichiers .md continuent d'être compilés comme des fichiers MDX, mais il sera possible d'opter pour CommonMark.

Upgrading math packages​

If you use Docusaurus to render Math Equations, you should upgrade the MDX plugins.

Make sure to use remark-math 6 and rehype-katex 7 for Docusaurus v3 (using MDX v3). We can't guarantee other versions will work.

{
-  "remark-math": "^3.0.0",
+  "remark-math": "^6.0.0",
-  "rehype-katex": "^5.0.0"
+  "rehype-katex": "^7.0.0"
}

Turn off MDX v1 compat​

Docusaurus v3 comes with MDX v1 compatibility options, that are turned on by default.

docusaurus.config.js
export default {
  markdown: {
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

comments option​

This option allows the usage of HTML comments inside MDX, while HTML comments are officially not supported anymore.

For MDX files, we recommend to progressively use MDX {/* comments */} instead of HTML <!-- comments -->, and then turn this compatibility option off.

Blog truncate marker

The default blog truncate marker now supports both <!-- truncate --> and {/* truncate */}.

admonitions option​

This option allows the usage of the Docusaurus v2 admonition title syntax:

:::note[Your Title]

content

:::

Docusaurus now implements admonitions with Markdown Directives (implemented with remark-directive), and the syntax to provide a directive label requires square brackets:

:::note[Your Title]

content

:::

We recommend to progressively use the new Markdown directive label syntax, and then turn this compatibility option off.

headingIds option​

This option allows the usage of the Docusaurus v2 explicit heading id syntax:

### Hello World {#my-explicit-id}

This syntax is now invalid MDX, and would require to escape the { character: \{#my-explicit-id}.

We recommend to keep this compatibility option on for now, until we provide a new syntax compatible with newer versions of MDX.

Ask For Help​

In case of any upgrade problem, the first things to try are:

  • make sure all your docs compile in the MDX playground, or using npx docusaurus-mdx-checker
  • delete node_modules and run npm install again
  • run docusaurus clear to clear the caches
  • remove third-party plugins that might not support Docusaurus v3
  • delete all your swizzled components

Once you have tried that, you can ask for support through the following support channels:

Please consider our time is precious. To ensure that your support request is not ignored, we kindly ask you to:

  • provide a minimal reproduction that we can easily run, ideally created with docusaurus.new
  • provide a live deployment url showing the problem in action (if your site can build)
  • explain clearly the problem, much more than an ambiguous "it doesn't work"
  • include as much relevant material as possible: code snippets, repo url, git branch urls, full stack traces, screenshots and videos
  • present your request clearly, concisely, showing us that you have made an effort to help us help you

Vous pouvez également faire appel à un fournisseur de service Docusaurus payant pour effectuer cette montée de version à votre place. Si votre site est open source, vous pouvez également demander à notre communauté une aide gratuite et bienveillante.