Migração manual

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

No Docusaurus 2, usamos nomes de pacotes com escopo definido:

• docusaurus → @docusaurus/core

Isso fornece uma distinção clara entre os pacotes oficiais do Docusaurus e os pacotes mantidos pela comunidade. 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. Portanto, precisamos adicionar esta dependência também:

package.json

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

tip

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

O site D1 pode ter um arquivo README existente. 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.

No Docusaurus 2, dividimos cada funcionalidade (blog, documentos, páginas) em plug-ins para modularidade. 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

Nenhuma ação necessária, esses campos de configuração não foram modificados.

colors

Descontinuada. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. Os documentos ainda não estão prontos e vamos atualizar aqui quando estiver. 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 usa 7 tonalidades de cada cor.

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

We recommend using ColorBox to find the different shades of colors for your chosen primary color.

Alternatively, use the following tool to generate the different shades for your website and copy the variables into src/css/custom.css.

tip

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

As meta informações do site, como ativos, SEO e informações de direitos autorais, agora são tratadas por temas. 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: "Getting Started" },
  { page: "help", label: "Help" },
  { href: "https://github.com/", label: "GitHub" },
  { blog: true, label: "Blog" },
],

Agora, ambos os campos são tratados pelo tema:

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: { //... },
    },
    // ...
  },
};

warning

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

Você pode entrar em contato com a equipe do DocSearch (@shortcuts, @s-pace) para obter suporte. Eles podem atualizá-lo para você e acionar um novo rastreamento do seu site para restaurar a pesquisa (caso contrário, você terá que esperar até 24 horas para o próximo rastreamento agendado)

blogSidebarCount

Descontinuada. Pass it as a blog option to @docusaurus/preset-classic instead:

docusaurus.config.js

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

cname

Descontinuada. 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.

Descontinuada. 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

Todos os seguintes campos estão obsoletos, você pode remover do seu arquivo de configuração.

• blogSidebarTitle
• cleanUrl - Clean URL is used by default now.
• defaultVersionShown - Versioning is not ported yet. Você não seria capaz de migrar para o Docusaurus 2 se estivesse usando versionamento. Fique atento.
• 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. Your Markdown options have to be converted to Remark/Rehype plugins.
• markdownPlugins - We use MDX in v2 instead of Remarkable. Your Markdown plugins have to be converted to Remark/Rehype plugins.
• 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

Pretendemos implementar muitos dos campos de configuração obsoletos como plug-ins no futuro. Valorizamos a ajuda!

Urls

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

Por exemplo, existem estas 2 páginas:

• 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.

Por motivos de SEO e evitando quebras de links, você deve configurar regras de redirecionamento do servidor no seu provedor de hospedagem.

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

In previous version, nested sidebar category is not allowed and sidebar category can only contain doc ID. However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.

Você terá que migrar sua barra lateral se ela contiver um tipo de categoria. 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.

Não deslize o Rodapé apenas para adicionar o logotipo à esquerda. O logotipo é intencionalmente removido na v2 e movido para baixo. 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.

No v2, você tem que aplicar o layout do tema em cada página. O componente de Layout tem propriedades de metadado.

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! Enquanto isso, inspecione o site V2 ou veja https://infima.dev/ para ver quais estilos estão disponíveis).

Você pode migrar a CommonJS para importações/exportações da ES6.

Aqui está uma página típica do 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;

O seguinte código pode ser útil para a migração de várias páginas:

• 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. Daí que possa haver alguma sintaxe não compatível com a documentação existente que seria necessário atualizar. 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/>). Todas as tags em documentos MDX precisam ser JSX válidos.

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

Os campos da frente do Docusaurus para o blog foram alterados de camelCase para snake_case para consistência na documentação.

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. Você pode querer configurar redirecionamentos do lado do servidor para que as assinaturas dos usuários continuem funcionando.

Test your site

Após a migração, a estrutura da pasta deverá ficar assim:

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

Inicie o servidor de desenvolvimento e corrija quaisquer erros:

npm

cd website
npm start

Yarn

cd website
yarn start

pnpm

cd website
pnpm start

Você também pode tentar criar o site para produção:

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build