Aller au contenu principal
Version : 3.7.0

Migration manuelle

Ce processus de migration manuelle doit ĂȘtre exĂ©cutĂ© aprĂšs le processus de migration automatisĂ©e, pour complĂ©ter les piĂšces manquantes, ou les problĂšmes de dĂ©bogage en sortie du CLI de migration.

Configuration du projet​

package.json​

Noms de paquets Ă©tendus​

Dans Docusaurus 2, nous utilisons des noms de paquets Ă©tendus :

  • docusaurus → @docusaurus/core

Ceci fournit une distinction claire entre les paquets officiels de Docusaurus et les paquets gérés par la communauté. En d'autres termes, tous les paquets officiels de Docusaurus sont nommés sous @docusaurus/.

Par ailleurs, les fonctionnalitĂ©s du site de doc par dĂ©faut fournies par Docusaurus 1 sont dĂ©sormais assurĂ©es par @docusaurus/preset-classic. Par consĂ©quent, nous devons Ă©galement ajouter cette dĂ©pendance :

package.json
{
dependencies: {
- "docusaurus": "^1.x.x",
+ "@docusaurus/core": "^2.0.0-beta.0",
+ "@docusaurus/preset-classic": "^2.0.0-beta.0",
}
}
astuce

Veuillez utiliser la version la plus récente de Docusaurus 2, que vous pouvez consulter ici (en utilisant la balise latest).

Commandes du CLI​

Par ailleurs, les commandes CLI sont renommées en docusaurus <command> (au lieu de docusaurus-command).

La section "scripts" de votre package.json doit ĂȘtre mise Ă  jour comme suit :

package.json
{
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
// ...
}
}

Un package.json typique de Docusaurus 2 peut ressembler Ă  ceci :

package.json
{
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"serve": "docusaurus serve",
"clear": "docusaurus clear"
},
"dependencies": {
"@docusaurus/core": "^2.0.0-beta.0",
"@docusaurus/preset-classic": "^2.0.0-beta.0",
"clsx": "^1.1.1",
"react": "^17.0.2",
"react-dom": "^17.0.2"
},
"browserslist": {
"production": [">0.5%", "not dead", "not op_mini all"],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
}
}

Mettez Ă  jour les rĂ©fĂ©rences vers le rĂ©pertoire build​

Dans Docusaurus 1, tous les artefacts de construction se trouvent dans website/build/<PROJECT_NAME>.

Dans Docusaurus 2, il est désormais transféré dans website/build. Assurez-vous de mettre à jour votre configuration de déploiement pour lire les fichiers générés à partir du répertoire build.

Si vous déployez sur des pages GitHub, assurez-vous d'exécuter yarn deploy au lieu du script yarn publish-gh-pages.

.gitignore​

Le .gitignore de votre website devrait contenir :

.gitignore
# dependencies
/node_modules

# production
/build

# generated files
.docusaurus
.cache-loader

# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*

README​

Le site web D1 peut avoir un fichier README existant. Vous pouvez le modifier pour refléter les modifications D2, ou copier le Docusaurus v2 README par défaut.

Configurations du site​

docusaurus.config.js​

Renommez siteConfig.js en docusaurus.config.js.

Dans Docusaurus 2, nous découpons chaque fonctionnalité (blog, docs, pages) en plugins pour la modularité. Les presets sont des bundles de plugins et pour une compatibilité ascendante nous avons construit un @docusaurus/preset-classic, preset qui regroupe la plupart des plugins essentiels présents dans Docusaurus 1.

Ajoutez la section preset suivante Ă  votre docusaurus.config.js.

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// Chemin du dossier Docs relatif au répertoire du site web.
path: '../docs',
// Fichier des barres latérales relatif au répertoire du site web.
sidebarPath: require.resolve('./sidebars.json'),
},
// ...
},
],
],
};

Nous recommandons de dĂ©placer le dossier docs dans le dossier website et c'est aussi la structure de rĂ©pertoire par dĂ©faut dans la v2. Vercel prend en charge les dĂ©ploiements de projets Docusaurus prĂȘts Ă  l'emploi si le rĂ©pertoire docs se trouve Ă  l'intĂ©rieur du website. Il est Ă©galement gĂ©nĂ©ralement prĂ©fĂ©rable que la documentation soit dans le site web afin que la documentation et le reste du code du site soient colocalisĂ©s dans un rĂ©pertoire website.

Si vous migrez votre site web Docusaurus v1 et qu'il y a des pull requests de documentation en attente, vous pouvez temporairement garder le dossier /docs Ă  sa place d'origine, pour Ă©viter de produire des conflits.

Reportez-vous au guide de migration ci-dessous pour chaque champ dans siteConfig.js.

Champs mis à jour​

baseUrl, tagline, title, url, favicon, organizationName, projectName, githubHost, scripts, stylesheets​

Aucune action requise, ces champs de configuration n'ont pas été modifiés.

colors​

DĂ©prĂ©ciĂ©. Nous avons Ă©crit un framework CSS personnalisĂ© pour Docusaurus 2 appelĂ© Infima qui utilise des variables CSS pour le thĂšme. Les docs ne sont pas encore tout Ă  fait prĂȘtes et nous les mettrons Ă  jour ici quand elles le seront. Pour Ă©craser les variables CSS d'Infima, crĂ©ez votre propre fichier CSS (par exemple ./src/css/custom.css) et importez-le globalement en le passant en option Ă  @docusaurus/preset-classic :

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};

Infima utilise 7 nuances de chaque couleur.

/src/css/custom.css
/**
* Vous pouvez surcharger les variables par défaut d'Infima ici.
* Remarque : il ne s'agit pas d'une liste exhaustive des variables --ifm-.
*/
:root {
--ifm-color-primary: #25c2a0;
--ifm-color-primary-dark: rgb(33, 175, 144);
--ifm-color-primary-darker: rgb(31, 165, 136);
--ifm-color-primary-darkest: rgb(26, 136, 112);
--ifm-color-primary-light: rgb(70, 203, 174);
--ifm-color-primary-lighter: rgb(102, 212, 189);
--ifm-color-primary-lightest: rgb(146, 224, 208);
}

Nous vous recommandons d'utiliser ColorBox pour trouver les différentes nuances de couleurs pour la couleur principale que vous avez choisie.

Sinon, utilisez l'outil suivant pour générer les différentes nuances pour votre site web et copiez les variables dans src/css/custom.css.

astuce

Visez au moins Taux de contraste WCAG-AA pour la couleur principale afin de garantir la lisibilitĂ©. Utilisez le site Web du Docusaurus lui-mĂȘme pour avoir un aperçu de votre palette de couleurs. Vous pouvez utiliser d'autres palettes en mode sombre, car une couleur ne fonctionne gĂ©nĂ©ralement pas en mode clair et en mode sombre.

Nom de la variable CSSHexAjustementTaux de contraste
--ifm-color-primary-lightest#3cad6eFail 🔮
--ifm-color-primary-lighter#359962Fail 🔮
--ifm-color-primary-light#33925dFail 🔮
--ifm-color-primary#2e85550AA 👍
--ifm-color-primary-dark#29784cAA 👍
--ifm-color-primary-darker#277148AA 👍
--ifm-color-primary-darkest#205d3bAAA 🏅

Remplacez les variables dans src/css/custom.css par ces nouvelles variables.

/src/css/custom.css
:root {
--ifm-color-primary: #2e8555;
--ifm-color-primary-dark: #29784c;
--ifm-color-primary-darker: #277148;
--ifm-color-primary-darkest: #205d3b;
--ifm-color-primary-light: #33925d;
--ifm-color-primary-lighter: #359962;
--ifm-color-primary-lightest: #3cad6e;
}

Les mĂ©tadonnĂ©es du site telles que les ressources, le rĂ©fĂ©rencement, les informations sur les droits d'auteur sont maintenant gĂ©rĂ©es par thĂšmes. Pour les personnaliser, utilisez le champ themeConfig dans votre docusaurus.config.js :

docusaurus.config.js
module.exports = {
// ...
themeConfig: {
footer: {
logo: {
alt: 'Meta Open Source Logo',
src: '/img/meta_oss_logo.png',
href: 'https://opensource.facebook.com/',
},
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // Vous pouvez également y insérer votre propre code HTML.
},
image: 'img/docusaurus.png',
// ...
},
};

Dans Docusaurus 1, l'icĂŽne d'entĂȘte et les liens d'entĂȘte Ă©taient des champs racine dans siteConfig :

siteConfig.js
headerIcon: 'img/docusaurus.svg',
headerLinks: [
{ doc: "doc1", label: "Pour commencer" },
{ page: "help", label: "Aide" },
{ href: "https://github.com/", label: "GitHub" },
{ blog: true, label: "Blog" },
],

Maintenant, ces deux champs sont tous deux traitĂ©s par le thĂšme :

docusaurus.config.js
module.exports = {
// ...
themeConfig: {
navbar: {
title: 'Docusaurus',
logo: {
alt: 'Docusaurus Logo',
src: 'img/docusaurus.svg',
},
items: [
{to: 'docs/doc1', label: 'Getting Started', position: 'left'},
{to: 'help', label: 'Help', position: 'left'},
{
href: 'https://github.com/',
label: 'GitHub',
position: 'right',
},
{to: 'blog', label: 'Blog', position: 'left'},
],
},
// ...
},
};

algolia​

docusaurus.config.js
module.exports = {
// ...
themeConfig: {
algolia: {
apiKey: '47ecd3b21be71c5822571b9f59e52544',
indexName: 'docusaurus-2',
algoliaOptions: { //... },
},
// ...
},
};
attention

Votre configuration Algolia DocSearch v1 (trouvĂ©e ici) doit ĂȘtre mise Ă  jour pour Docusaurus v2 (exemple).

Vous pouvez contacter l'équipe DocSearch (@shortcuts, @s-pace) pour obtenir de l'aide. Ils peuvent le mettre à jour pour vous et déclencher une réindexation de votre site pour rétablir la recherche (sinon, vous devrez attendre jusqu'à 24 heures pour la prochaine réindexation programmée)

blogSidebarCount​

DĂ©prĂ©ciĂ©. Transmettez-le Ă  la place comme option du blog Ă  @docusaurus/preset-classic :

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
postsPerPage: 10,
},
// ...
},
],
],
};

cname​

Déprécié. Créez un fichier CNAME dans votre dossier static à la place avec votre domaine personnalisé. Les fichiers dans le dossier static seront copiés à la racine du dossier build lors de l'exécution de la commande build.

customDocsPath, docsUrl, editUrl, enableUpdateBy, enableUpdateTime​

RUPTURE : editUrl devrait pointer vers le projet (website) Docusaurus au lieu du répertoire docs.

DĂ©prĂ©ciĂ©. Transmettez-le Ă  la place comme une option Ă  @docusaurus/preset-classic :

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// Équivalent à `customDocsPath`.
path: 'docs',
// Equivalent à `editUrl` mais doit pointer vers le répertoire `website` au lieu de `website/docs`.
editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
// Équivalent à `docsUrl`.
routeBasePath: 'docs',
// Les plugins Remark et Rehype sont passés au MDX. Remplace `markdownOptions` et `markdownPlugins`.
remarkPlugins: [],
rehypePlugins: [],
// Équivalent à `enableUpdateBy`.
showLastUpdateAuthor: true,
// Équivalent à `enableUpdateTime`.
showLastUpdateTime: true,
},
// ...
},
],
],
};

gaTrackingId​

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// ...
googleAnalytics: {
trackingID: 'UA-141789564-1',
},
},
],
],
};

gaGtag​

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// ...
gtag: {
trackingID: 'UA-141789564-1',
},
},
],
],
};

Champs supprimĂ©s​

Les champs suivants sont tous obsolĂštes, vous pouvez les supprimer de votre fichier de configuration.

  • blogSidebarTitle
  • cleanUrl - L'URL propre est maintenant utilisĂ©e par dĂ©faut.
  • defaultVersionShown - La gestion de version n'est pas encore portĂ©e. Vous ne serez pas en mesure de migrer vers Docusaurus 2 si vous utilisez les versions. Restez Ă  l'Ă©coute.
  • disableHeaderTitle
  • disableTitleTagline
  • docsSideNavCollapsible est disponible avec docsPluginOptions.sidebarCollapsible, et cela est activĂ© par dĂ©faut maintenant.
  • facebookAppId
  • facebookComments
  • facebookPixelId
  • fonts
  • highlight - Nous utilisons maintenant Prism au lieu de highlight.js.
  • markdownOptions - Nous utilisons MDX dans la v2 au lieu de Remarkable. Vos options de Markdown doivent ĂȘtre converties en plugins Remark/Rehype.
  • markdownPlugins - Nous utilisons MDX dans la v2 au lieu de Remarkable. Vos plugins Markdown doivent ĂȘtre convertis en plugins Remark/Rehype.
  • manifest
  • onPageNav - Ceci est activĂ© par dĂ©faut maintenant.
  • separateCss - Il peut ĂȘtre importer de la mĂȘme maniĂšre que custom.css mentionnĂ©e ci-dessus.
  • scrollToTop
  • scrollToTopOptions
  • translationRecruitingLink
  • twitter
  • twitterUsername
  • useEnglishUrl
  • users
  • usePrism - Nous utilisons maintenant Prism au lieu de highlight.js
  • wrapPagesHTML

Nous avons l'intention d'implémenter de nombreux champs de configuration obsolÚtes en tant que plugins à l'avenir. Toute aide sera appréciée !

URL​

Dans la v1, toutes les pages Ă©taient disponibles avec ou sans l'extension .html.

Par exemple, ces 2 pages existent :

Si cleanUrl Ă©tait :

  • true : les liens ciblaient /installation
  • false : les liens ciblaient /installation.html

Dans la v2, par défaut, la page canonique est /installation, et non /installation.html.

Si vous aviez cleanUrl: false dans la v1, il est possible que les gens aient publié des liens vers /installation.html.

Pour des raisons de référencement et en évitant de rompre les liens, vous devez configurer les rÚgles de redirection cÎté serveur sur votre hébergeur.

En tant que hatch d'échappement, vous pouvez utiliser @docusaurus/plugin-client-redirects pour créer des redirections cÎté client de /installation.html vers /installation.

module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
fromExtensions: ['html'],
},
],
],
};

Si vous voulez garder l'extension .html comme l'URL canonique d'une page, docs peut déclarer un slug: installation.html dans le front matter.

Composants​

Dans la version précédente, les catégories imbriquées dans la barre latérale ne sont pas autorisées et la catégorie de la barre latérale ne peut contenir que l'ID du doc. Cependant, la v2 permet une barre latérale imbriquée infinie et nous avons de nombreux types d'élément de barre latérale autre que le document.

Vous devrez migrer votre barre latérale si elle contient le type de catégorie. Renommer subcategory en category et ids en items.

sidebars.json
{
- type: 'subcategory',
+ type: 'category',
label: 'My Example Subcategory',
+ items: ['doc1'],
- ids: ['doc1']
},

website/core/Footer.js n'est plus nécessaire. Si vous voulez modifier le pied de page par défaut fourni par Docusaurus, swizzler le :

npm run swizzle @docusaurus/theme-classic Footer

Cela copiera le composant <Footer /> actuel utilisé par le thÚme dans un répertoire src/theme/Footer sous la racine de votre site, vous pouvez ensuite modifier ce composant pour la personnalisation.

Ne swizzlez pas le pied de page juste pour ajouter le logo sur la gauche. Le logo est dĂ©libĂ©rĂ©ment enlevĂ© en v2 et dĂ©placĂ© vers le bas. Il suffit de configurer le pied de page dans docusaurus.config.js avec themeConfig.footer :

module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Meta Open Source Logo',
src: '/img/meta_oss_logo.png',
href: 'https://opensource.facebook.com',
},
},
},
};

Pages​

Veuillez vous référer à la |création de pages](guides/creating-pages.mdx) pour apprendre comment fonctionnent les pages Docusaurus 2. AprÚs avoir lu cela, notez que vous devez déplacer les fichiers pages/en de la v1 vers src/pages à la place.

Dans Docusaurus v1, les pages ont reçu l'objet siteConfig comme props.

Dans Docusaurus v2, récupérer l'objet siteConfig depuis useDocusaurusContext à la place.

En v2, vous devez appliquer la mise en page du thÚme autour de chaque page. Le composant de mise en page prend des props de métadonnées.

CompLibrary est obsolÚte dans la v2, donc vous devez écrire votre propre composant React ou utiliser les styles Infima (Les docs seront bientÎt disponibles, désolé ! Pendant ce temps, inspectez le site Web V2 ou consultez https://infima.dev/ pour voir quels styles sont disponibles).

Vous pouvez migrer CommonJS vers les imports/exportations ES6.

Voici une page typique de Docusaurus v2 :

import React from 'react';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import Layout from '@theme/Layout';

const MyPage = () => {
const {siteConfig} = useDocusaurusContext();
return (
<Layout title={siteConfig.title} description={siteConfig.tagline}>
<div className="hero text--center">
<div className="container ">
<div className="padding-vert--md">
<h1 className="hero__title">{siteConfig.title}</h1>
<p className="hero__subtitle">{siteConfig.tagline}</p>
</div>
<div>
<Link
to="/docs/get-started"
className="button button--lg button--outline button--primary">
Get started
</Link>
</div>
</div>
</div>
</Layout>
);
};

export default MyPage;

Le code suivant pourrait ĂȘtre utile pour la migration de diffĂ©rentes pages :

Contenu​

Remplacez AUTOGENERATED_TABLE_OF_CONTENTS​

Cette fonctionnalité est remplacée par la table des matiÚres en ligne

Mettez Ă  jour la syntaxe Markdown pour ĂȘtre compatible avec MDX​

Dans Docusaurus 2, la syntaxe Markdown a Ă©tĂ© changĂ©e en MDX. Il se peut donc que les documents existants contiennent des erreurs de syntaxe que vous devrez mettre Ă  jour. Un exemple courant est celui des balises auto-fermantes comme <img> et <br> qui sont valides en HTML, mais doivent maintenant ĂȘtre explicitement fermĂ©es (<img/> et <br/>). Toutes les balises des documents MDX doivent ĂȘtre des JSX valides.

La partie haute (front matter) est analysĂ©e par gray-matter. Si votre front matter utilise des caractĂšres spĂ©ciaux comme :, vous devez maintenant le mettre entre quote : title: Partie 1: mon titre de la partie1 → title: "Partie 1: mon titre de la partie1".

Astuces : Vous pouvez utiliser des outils en ligne comme HTML vers JSX pour faciliter la migration.

Onglets de code spĂ©cifiques au langage​

Reportez-vous Ă  la section blocs de code multi-langage.

Front matter​

Les champs du frontmatter de Docusaurus pour le blog ont Ă©tĂ© changĂ©s de camelCase Ă  snake_case pour ĂȘtre cohĂ©rents avec la documentation.

Les champs authorFBID et authorTwitter ont Ă©tĂ© dĂ©prĂ©ciĂ©s. Ils ne sont utilisĂ©s que pour gĂ©nĂ©rer l'image de profil de l'auteur qui peut ĂȘtre faite via le champ authors.

DĂ©ploiement​

Le fichier CNAME utilisé par GitHub Pages n'est plus généré, donc assurez-vous de l'avoir créé dans /static/CNAME si vous utilisez un domaine personnalisé.

Le flux RSS du blog est maintenant hébergé dans /blog/rss.xml au lieu de /blog/feed.xml. Vous pouvez configurer les redirections cÎté serveur pour que les abonnements des utilisateurs continuent à fonctionner.

Testez votre site​

AprĂšs la migration, la structure de votre dossier devrait ressembler Ă  ceci :

my-project
├── docs
└── website
├── blog
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ └── index.js
├── package.json
├── sidebars.json
├── .gitignore
├── docusaurus.config.js
└── static

Démarrez le serveur de développement et corrigez les erreurs :

cd website
npm start

Vous pouvez Ă©galement essayer de construire le site pour la production :

npm run build