Version: 2.3.1

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.
          path: '../docs',
          // Fichier sidebars relatif au répertoire du site.
          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 dans le 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 remplacer les variables Infima par défaut ici.
 * Remarque : ce n'est pas une liste complète 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.

Alternativement, 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

Aim for at least WCAG-AA contrast ratio for the primary color to ensure readability. Use the Docusaurus website itself to preview how your color palette would look like. You can use alternative palettes in dark mode because one color doesn't usually work in both light and dark mode.

Primary Color:

Background:

CSS Variable Name	Hex	Adjustment	Contrast Rating
`--ifm-color-primary-lightest`	`#3cad6e`		Fail 🔴
`--ifm-color-primary-lighter`	`#359962`		Fail 🔴
`--ifm-color-primary-light`	`#33925d`		Fail 🔴
`--ifm-color-primary`	`#2e8555`	0	AA 👍
`--ifm-color-primary-dark`	`#29784c`		AA 👍
`--ifm-color-primary-darker`	`#277148`		AA 👍
`--ifm-color-primary-darkest`	`#205d3b`		AAA 🏅

Replace the variables in src/css/custom.css with these new 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;
}

`footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible`

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 mettre votre propre HTML ici.
    },
    image: 'img/docusaurus.png',
    // ...
  },
};

`headerIcon`, `headerLinks`

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',
          // Équivalent à  `editUrl` mais devrait pointer à la place 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 à 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 frontmatter.

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
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic Footer

yarn swizzle @docusaurus/theme-classic Footer

pnpm 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 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 de 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 :

Page d'index - Flux (recommandé), Docusaurus 2, Hermes
Page d'aide/support - Docusaurus 2, Flux

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 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 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 frontmatter 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".

Conseils: Vous pouvez utiliser des outils en ligne tels que HTML to JSX pour faciliter la migration.

Onglets de code spécifiques au language

Reportez-vous à la section blocs de code prenant en charge le multi-language.

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
yarn start

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

yarn build

Migration manuelle

Configuration du projet​

package.json​

Noms de paquets étendus​

Commandes du CLI​

Mettez à jour les références vers le répertoire build​

.gitignore​

README​

Configurations du site​

docusaurus.config.js​

Champs mis à jour​

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

colors​

footerIcon, copyright, ogImage, twitterImage, docsSideNavCollapsible​

headerIcon, headerLinks​

algolia​

blogSidebarCount​

cname​

customDocsPath, docsUrl, editUrl, enableUpdateBy, enableUpdateTime​

gaTrackingId​

gaGtag​

Champs supprimés​

URL​

Composants​

Barre latérale​

Footer​

Pages​

Contenu​

Remplacez AUTOGENERATED_TABLE_OF_CONTENTS​

Mettez à jour la syntaxe Markdown pour être compatible MDX​

Onglets de code spécifiques au language​

Front matter​

Déploiement​

Testez votre site​