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 :
Selon notre processus de version, Docusaurus v2 est maintenant entré en mode maintenance. Elle bénéficiera d'une assistance pour les problèmes de sécurité majeurs pendant trois mois seulement, jusqu'au 31 janvier 2024. Il est recommandé de passer à la version 3 dans ce laps de temps.
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 :
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 :
:::warning, supprime :::cautionv2.0.0-beta.10 (décembre 2021)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.
Docusaurus v3 met à jour MDX v1 en MDX v3 :
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.
La transition de MDX v1 à MDX v3 est le principal défi pour le passage à Docusaurus v3.
Certains documents qui ont été compilés avec succès sous Docusaurus v2 peuvent maintenant ne pas être compilés sous Docusaurus v3, tandis que d'autres peuvent s'afficher différemment.
La plupart des changements de rupture proviennent de [MDX v2(https://mdxjs.com/blog/v2/), et [MDX v3(https://mdxjs.com/blog/v3/) qui est une version relativement petite. 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.
Ne soyez pas intimidé. La plupart des problèmes sont faciles à résoudre et souvent liés aux caractères { et < que vous devez maintenant échapper. Cependant, en fonction de la taille de votre site, vous pourriez avoir besoin de modifier de nombreux fichiers et vous sentir submergé. Pour cette raison, nous fournissons une commande npx docusaurus-mdx-checker pour vous aider à obtenir une estimation du travail à effectuer, et nous recommandons de préparer votre site à l'avance.
Si vous avez créé des plugins MDX (Remark/Rehype), l'AST est légèrement différent et vous devrez peut-être les refactoriser.
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.
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;
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 :
sitemap.xml<meta name="robots" content="noindex, nofollow" />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é :
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.
React 18 est livré avec de nouvelles fonctionnalités :
<Suspense>React.lazy()startTransition()Leur prise en charge par Docusaurus est considérée comme expérimentale. Nous pourrions être amenés à ajuster l'intégration à l'avenir, ce qui entraînerait un comportement différent au niveau de l'exécution.
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>;
}
Il est maintenant possible de construire votre site statique en mode dev.
docusaurus build --dev
Docusaurus enregistrera plus d'erreurs dans la console, notamment les erreurs d'hydratation de React 18 grâce au nouveau callback onRecoverableError.
Ce nouveau mode de compilation est particulièrement utile pour résoudre les problèmes de React. Docusaurus utilisera la version de développement de React, produisant ainsi des messages d'erreur détaillés et lisibles au lieu de messages minifiés renvoyant à la page du décodeur d'erreurs React.
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';
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);
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.
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 nouvelles fonctionnalités à mentionner :
feedOptions.limitno-html-linksprefer-docusaurus-headingConsultez les notes de version de Docusaurus v3.0.0 pour une liste exhaustive des changements.
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é.
Les développeurs frontend ont souvent besoin de mettre à jour les dépendances npm, mais ces mises à jour peuvent être angoissantes et entraîner des effets secondaires subtils sur l'interface utilisateur qui ne sont pas détectés par votre suite de tests habituelle.
La mise à jour de Docusaurus est un bon exemple : à moins de revoir toutes les pages une à une, il est difficile de s'assurer qu'il n'y a pas de régression visuelle. Docusaurus v3 est sur le point de sortir (actuellement en beta), et nous aimerions vous aider à effectuer cette mise à jour en toute confiance.
Cet article présente un flux de travail de test sur la régression visuelle basé sur GitHub Actions, Playwright et Argos. Il n'est pas directement lié à Docusaurus ou React, et peut être adapté pour fonctionner avec d'autres applications frontend et d'autres frameworks.
Nous sommes heureux d'annoncer Docusaurus 2.4.
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 2.3.
La mise à jour devrait être facile : comme expliqué dans notre documentation sur le processus de version, les versions mineures respectent le versionnement sémantique.
