Version: 2.1.0

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.

Configuração do projeto

`package.json`

Nomes de pacotes com escopo

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. Em outras palavras, todos os pacotes oficiais do Docusaurus têm namespaces sob @docusaurus/.

Enquanto isso, as funcionalidades padrão do doc site fornecidas pelo Docusaurus 1 agora são fornecidas pelo @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

Use a versão mais recente do Docusaurus 2, que você pode conferir aqui (usando a tag mais recente ).

Comandos CLI

Enquanto isso, os comandos CLI são renomeados para docusaurus <command> (em vez de docusaurus-command).

Os "scripts" da seção do seu package.json devem ser atualizados da seguinte forma:

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

Um típico Docusaurus 2 package.json pode se parecer com isto:

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

Atualize as referências ao diretório `build`

No Docusaurus 1, todos os artefatos de construção estão localizados em website/build/<PROJECT_NAME>.

No Docusaurus 2, agora foi movido para apenas website/build. Certifique-se de atualizar sua configuração de implantação para ler os arquivos gerados no diretório build correto.

Se você estiver fazendo deploy no GitHub pages, certifique-se de executar o script yarn deploy em vez do script yarn publish-gh-pages.

`.gitignore`

O .gitignore no seu site deve conter:

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

Configuração do site

`docusaurus.config.js`

Renomeie siteConfig.js para docusaurus.config.js.

No Docusaurus 2, dividimos cada funcionalidade (blog, documentos, páginas) em plug-ins para modularidade. Presets são pacotes de plug-ins e, para compatibilidade com versões anteriores, construímos um preset @docusaurus/preset-classic que agrupa a maioria dos plug-ins essenciais presentes no Docusaurus 1.

Adicione a seguinte configuração predefinida ao seu docusaurus.config.js.

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Caminho da pasta de documentos em relação ao diretório do site.
          path: '../docs',
          // Arquivo de barras laterais relativo ao diretório do site.
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

Recomendamos mover a pasta docs para a pasta website e essa também é a estrutura de diretório padrão na v2. Vercel supports Docusaurus project deployments out-of-the-box if the docs directory is within the website. Em geral, também é melhor que os documentos estejam dentro do site, de modo que os documentos e o restante do código do site sejam colocados em um diretório website.

Se você estiver migrando seu site Docusaurus v1 e houver solicitações de pull de documentação pendentes, você pode manter temporariamente a pasta /docs em seu local original, para evitar conflitos de produção.

Consulte o guia de migração abaixo para cada campo em siteConfig.js.

Campos atualizados

`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. Escrevemos uma estrutura CSS personalizada para Docusaurus 2 chamada Infima que usa variáveis CSS para os temas. Os documentos ainda não estão prontos e vamos atualizar aqui quando estiver. Para sobrescrever as variáveis CSS do Infima, crie seu próprio arquivo CSS (por exemplo, ./src/css/custom.css) e importe-o globalmente passando-o como uma opção para @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);
}

Recomendamos usar o ColorBox para encontrar os diferentes tons de cores para a cor principal escolhida.

Como alternativa, use a ferramenta a seguir para gerar os diferentes tons para o seu site e copie as variáveis em 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. Para personalizá-los, use o campo themeConfig no seu 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`

No Docusaurus 1, o ícone do cabeçalho e os links do cabeçalho eram campos raiz no 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

Sua configuração do Algolia DocSearch v1 (encontrada aqui) deve ser atualizada para Docusaurus v2 (exemplo).

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. Passe-o como uma opção de blog para @docusaurus/preset-classic em vez disso:

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

`cname`

Descontinuada. Criar um arquivo CNAME na sua pasta static em vez disso com o seu domínio personalizado. Arquivos na pasta static serão copiados na raiz da pasta build durante a execução do comando de compilação.

`customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime`

QUEBRA: editUrl deve apontar para o projeto (website) Docusaurus em vez do diretório docs.

Descontinuada. Passe-o como uma opção para documentos @docusaurus/preset-classic:

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Equivalente a `customDocsPath`.
          path: 'docs',
          // Equivalente a `editUrl` mas deve apontar para o diretório `website` em vez de` website/docs`.
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
          // Equivalent to `docsUrl`.
          routeBasePath: 'docs',
          // Plugins Remark e Rehype passados para MDX. Substitui `markdownOptions` e` markdownPlugins`.
          remarkPlugins: [],
          rehypePlugins: [],
          // Equivalente a `enableUpdateBy`.
          showLastUpdateAuthor: true,
          // Equivalente a `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',
        },
      },
    ],
  ],
};

Campos removidos

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

blogSidebarTitle
cleanUrl - URL de limpeza é usada por padrão agora.
defaultVersionShown - Versioning ainda não é reportado. Você não seria capaz de migrar para o Docusaurus 2 se estivesse usando versionamento. Fique atento.
disableHeaderTitle
disableTitleTagline
docsSideNavCollapsible está disponível em docsPluginOptions.sidebarCollapsible, e isso está ativado por padrão agora.
facebookAppId
facebookComments
facebookPixelId
fonts
highlight - Agora usamos Prism ao invés de highlight.js.
Opções markdown - Usamos o MDX na v2 em vez de Remarkable. Your Markdown options have to be converted to Remark/Rehype plugins.
markdownPlugins - Usamos o MDX na v2 em vez de Remarkable. Your Markdown plugins have to be converted to Remark/Rehype plugins.
manifest
onPageNav - Agora isso está ativado por padrão.
separateCss - Ele pode ser importado da mesma maneira que custom.css mencionado acima.
scrollToTop
scrollToTopOptions
translationRecruitingLink
twitter
twitterUsername
useEnglishUrl
users
usePrism - Agora usamos Prism ao invés de highlight.js
wrapPagesHTML

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

Urls

Na v1, todas as páginas estavam disponíveis com ou sem a extensão .html.

Por exemplo, existem estas 2 páginas:

Se cleanUrl foi:

true: os links teriam como destino /installation
false: os links teriam como destino /installation.html

Em v2, por padrão, a página canônica é /installation, e não /installation.html.

Se você tinha cleanUrl: false na v1, é possível que pessoas publicaram links para /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.

Componentes

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. Renomeie subcategory para category e ids para items.

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

website/core/Footer.js não é mais necessário. If you want to modify the default footer provided by Docusaurus, swizzle it:

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic Footer

yarn swizzle @docusaurus/theme-classic Footer

pnpm run swizzle @docusaurus/theme-classic Footer

Isto irá copiar o atual componente <Footer /> usado pelo tema para o diretório src/theme/Foot na raiz do seu site, então você pode editar este componente de personalização.

Não deslize o Rodapé apenas para adicionar o logotipo à esquerda. O logotipo é intencionalmente removido na v2 e movido para baixo. Basta configurar o rodapé no docusaurus.config.js com themeConfig.footer:

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

Páginas

Please refer to creating pages to learn how Docusaurus 2 pages work. Depois de ler isso, note que você precisa mover páginas/en arquivos na v1 para src/pages em vez disso.

No Docusaurus v1, as páginas receberam o objeto siteConfig como props.

No Docusaurus v2, obtenha o objeto do site `` em useDocusaurusContext em vez disso.

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

CompLibrary está obsoleto em v2, então você precisa escrever seu próprio componente React ou usar estilos de Infima (Docs estarão disponíveis em breve, desculpe por isso! 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

Conteúdo

Substitua AUTOGENERATED_TABLE_OF_CONTENTS

This feature is replaced by inline table of content

Atualize a sintaxe Markdown para ser compatível com MDX

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. Um exemplo comum é um auto-fechamento de tags como <img> e <br> que são válidas em HTML teriam que ser explicitamente fechadas agora ( <img/> e <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".

Dicas: Você deve querer usar algumas ferramentas on-line, como HTML para JSX para tornar a migração mais fácil.

Guias de código específicos do idioma

Consulte a seção blocos de código de suporte multilíngue.

Front matter

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

Os campos authorFBID e authorTwitter foram descontinuados. They are only used for generating the profile image of the author which can be done via the authors field.

Deployment

O arquivo CNAME usado pelo GitHub Pages não é mais gerado, então certifique-se que o criou em /static/CNAME se você usar um domínio personalizado.

O feed de RSS do blog agora está hospedado em /blog/rss.xml ao invés de /blog/feed.xml. Você pode querer configurar redirecionamentos do lado do servidor para que as assinaturas dos usuários continuem funcionando.

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

cd website
yarn start

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

yarn build

Migração manual

Configuração do projeto​

package.json​

Nomes de pacotes com escopo​

Comandos CLI​

Atualize as referências ao diretório build​

.gitignore​

README​

Configuração do site​

docusaurus.config.js​

Campos atualizados​

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​

Campos removidos​

Urls​

Componentes​

Barra Lateral​

Rodapé​

Páginas​

Conteúdo​

Substitua AUTOGENERATED_TABLE_OF_CONTENTS​

Atualize a sintaxe Markdown para ser compatível com MDX​

Guias de código específicos do idioma​

Front matter​

Deployment​

Teste seu site​