Version : Canary 🚧

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.

Couleur principale :

Arrière-plan :

Nom de la variable CSS	Hex	Ajustement	Taux de contraste
`--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 🏅

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;
}

`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 y insérer votre propre code HTML.
    },
    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',
          // 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
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](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 :

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

npm
Yarn
pnpm

cd website
npm start

cd website
yarn start

cd website
pnpm start

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

npm
Yarn
pnpm

npm run build

yarn build

pnpm run 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 avec MDX​

Onglets de code spécifiques au langage​

Front matter​

Déploiement​

Testez votre site​