Migration manuelle

This manual migration process should be run after the automated migration process, to complete the missing parts, or debug issues in the migration CLI output.

Project setup

package.json

Scoped package names

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é. In another words, all Docusaurus' official packages are namespaced under @docusaurus/.

Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now provided by @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

Please use the most recent Docusaurus 2 version, which you can check out here (using the latest tag).

CLI commands

Meanwhile, CLI commands are renamed to docusaurus <command> (instead of docusaurus-command).

The "scripts" section of your package.json should be updated as follows:

package.json

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

A typical Docusaurus 2 package.json may look like this:

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"
    ]
  }
}

Update references to the build directory

In Docusaurus 1, all the build artifacts are located within website/build/<PROJECT_NAME>.

In Docusaurus 2, it is now moved to just website/build. Make sure that you update your deployment configuration to read the generated files from the correct build directory.

If you are deploying to GitHub pages, make sure to run yarn deploy instead of yarn publish-gh-pages script.

.gitignore

The .gitignore in your website should contain:

.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. You can modify it to reflect the D2 changes, or copy the default Docusaurus v2 README.

Site configurations

docusaurus.config.js

Rename siteConfig.js to docusaurus.config.js.

Dans Docusaurus 2, nous découpons chaque fonctionnalité (blog, docs, pages) en plugins pour la modularité. Presets are bundles of plugins and for backward compatibility we built a @docusaurus/preset-classic preset which bundles most of the essential plugins present in Docusaurus 1.

Add the following preset configuration to your docusaurus.config.js.

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Docs folder path relative to website dir.
          path: '../docs',
          // Sidebars file relative to website dir.
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

We recommend moving the docs folder into the website folder and that is also the default directory structure in v2. Vercel supports Docusaurus project deployments out-of-the-box if the docs directory is within the website. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one website directory.

If you are migrating your Docusaurus v1 website, and there are pending documentation pull requests, you can temporarily keep the /docs folder to its original place, to avoid producing conflicts.

Refer to migration guide below for each field in siteConfig.js.

Updated fields

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é. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. Les docs ne sont pas encore tout à fait prêtes et nous les mettrons à jour ici quand elles le seront. To overwrite Infima's CSS variables, create your own CSS file (e.g. ./src/css/custom.css) and import it globally by passing it as an option to @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

/**
 * You can override the default Infima variables here.
 * Note: this is not a complete list of --ifm- variables.
 */
: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.

Alteratively, use the following tool to generate the different shades for your website and copy the variables into 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. To customize them, use the themeConfig field in your 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.`, // You can also put own HTML here.
    },
    image: 'img/docusaurus.png',
    // ...
  },
};

headerIcon, headerLinks

In Docusaurus 1, header icon and header links were root fields in 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

Your Algolia DocSearch v1 config (found here) should be updated for Docusaurus v2 (example).

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é. Pass it as a blog option to @docusaurus/preset-classic instead:

docusaurus.config.js

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

cname

Déprécié. Create a CNAME file in your static folder instead with your custom domain. Files in the static folder will be copied into the root of the build folder during execution of the build command.

customDocsPath, docsUrl, editUrl, enableUpdateBy, enableUpdateTime

BREAKING: editUrl should point to (website) Docusaurus project instead of docs directory.

Déprécié. Pass it as an option to @docusaurus/preset-classic docs instead:

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Equivalent to `customDocsPath`.
          path: 'docs',
          // Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`.
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
          // Equivalent to `docsUrl`.
          routeBasePath: 'docs',
          // Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
          remarkPlugins: [],
          rehypePlugins: [],
          // Equivalent to `enableUpdateBy`.
          showLastUpdateAuthor: true,
          // Equivalent to `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',
        },
      },
    ],
  ],
};

Removed fields

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

• blogSidebarTitle
• cleanUrl - Clean URL is used by default now.
• defaultVersionShown - Versioning is not ported yet. Vous ne serez pas en mesure de migrer vers Docusaurus 2 si vous utilisez les versions. Restez à l'écoute.
• disableHeaderTitle
• disableTitleTagline
• docsSideNavCollapsible is available at docsPluginOptions.sidebarCollapsible, and this is turned on by default now.
• facebookAppId
• facebookComments
• facebookPixelId
• fonts
• highlight - We now use Prism instead of highlight.js.
• markdownOptions - We use MDX in v2 instead of Remarkable. Vos options de Markdown doivent être converties en plugins Remark/Rehype.
• markdownPlugins - We use MDX in v2 instead of Remarkable. Vos plugins Markdown doivent être convertis en plugins Remark/Rehype.
• manifest
• onPageNav - This is turned on by default now.
• separateCss - It can imported in the same manner as custom.css mentioned above.
• scrollToTop
• scrollToTopOptions
• translationRecruitingLink
• twitter
• twitterUsername
• useEnglishUrl
• users
• usePrism - We now use Prism instead of 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 !

Urls

In v1, all pages were available with or without the .html extension.

Par exemple, ces 2 pages existent :

• https://v1.docusaurus.io/docs/en/installation
• https://v1.docusaurus.io/docs/en/installation.html

If cleanUrl was:

• true: links would target /installation
• false: links would target /installation.html

In v2, by default, the canonical page is /installation, and not /installation.html.

If you had cleanUrl: false in v1, it's possible that people published links to /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.

As an escape hatch, you could use @docusaurus/plugin-client-redirects to create client-side redirects from /installation.html to /installation.

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

If you want to keep the .html extension as the canonical URL of a page, docs can declare a slug: installation.html front matter.

Components

Sidebar

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. However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.

Vous devrez migrer votre barre latérale si elle contient le type de catégorie. Rename subcategory to category and ids to items.

sidebars.json

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

Footer

website/core/Footer.js is no longer needed. If you want to modify the default footer provided by Docusaurus, swizzle it:

npm

npm run swizzle @docusaurus/theme-classic Footer

Yarn

yarn swizzle @docusaurus/theme-classic Footer

pnpm

pnpm run swizzle @docusaurus/theme-classic Footer

This will copy the current <Footer /> component used by the theme to a src/theme/Footer directory under the root of your site, you may then edit this component for customization.

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. Just configure the footer in docusaurus.config.js with themeConfig.footer:

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

Pages

Please refer to creating pages to learn how Docusaurus 2 pages work. After reading that, notice that you have to move pages/en files in v1 to src/pages instead.

In Docusaurus v1, pages received the siteConfig object as props.

In Docusaurus v2, get the siteConfig object from useDocusaurusContext instead.

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 is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! 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 :

• Index page - Flux (recommended), Docusaurus 2, Hermes
• Help/Support page - Docusaurus 2, Flux

Content

Replace AUTOGENERATED_TABLE_OF_CONTENTS

This feature is replaced by inline table of content

Update Markdown syntax to be MDX-compatible

In Docusaurus 2, the Markdown syntax has been changed to MDX. Il se peut donc que les documents existants contiennent des erreurs de syntaxe que vous devrez mettre à jour. A common example is self-closing tags like <img> and <br> which are valid in HTML would have to be explicitly closed now ( <img/> and <br/>). Toutes les balises des documents MDX doivent être des JSX valides.

Front matter is parsed by gray-matter. If your front matter use special characters like :, you now need to quote it: title: Part 1: my part1 title → title: "Part 1: my part1 title".

Tips: You might want to use some online tools like HTML to JSX to make the migration easier.

Language-specific code tabs

Refer to the multi-language support code blocks section.

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.

The fields authorFBID and authorTwitter have been deprecated. They are only used for generating the profile image of the author which can be done via the authors field.

Deployment

The CNAME file used by GitHub Pages is not generated anymore, so be sure you have created it in /static/CNAME if you use a custom domain.

The blog RSS feed is now hosted at /blog/rss.xml instead of /blog/feed.xml. Vous pouvez configurer les redirections côté serveur pour que les abonnements des utilisateurs continuent à fonctionner.

Test your 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

cd website
npm start

Yarn

cd website
yarn start

pnpm

cd website
pnpm start

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

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build