Version: 2.0.0-beta.5 🚧

Migração manual

Este processo de migração manual deve ser executado após o processo de migração automatizado, para concluir as partes ausentes ou depurar problemas na saída da CLI de migração.

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": "^16.8.4",    "react-dom": "^16.8.4"  },  "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. Você pode modificá-lo para refletir as alterações do D2 ou copiar o padrão README do Docusaurus v2.

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. Agora suporta Projeto Docusaurus implantações prontas para uso se o diretório docs estiver dentro de 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.

Primary Color:

CSS Variable Name	Hex	Adjustment
`--ifm-color-primary-lightest`	`#80aaef`
`--ifm-color-primary-lighter`	`#5a91ea`
`--ifm-color-primary-light`	`#4e89e8`
`--ifm-color-primary`	`#3578e5`	0
`--ifm-color-primary-dark`	`#1d68e1`
`--ifm-color-primary-darker`	`#1b62d4`
`--ifm-color-primary-darkest`	`#1751af`

Replace the variables in src/css/custom.css with these new variables.

--ifm-color-primary: #3578e5;--ifm-color-primary-dark: #1d68e1;--ifm-color-primary-darker: #1b62d4;--ifm-color-primary-darkest: #1751af;--ifm-color-primary-light: #4e89e8;--ifm-color-primary-lighter: #5a91ea;--ifm-color-primary-lightest: #80aaef;

`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: 'Facebook Open Source Logo',        src: 'https://docusaurus.io/img/oss_logo.png',        href: 'https://opensource.facebook.com/',      },      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // Você também pode colocar seu próprio HTML aqui.    },    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: { //... },    },    // ...  },};

caution

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/master/website',          // equivalente a `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 = {  // ...  themeConfig: {    googleAnalytics: {      trackingID: 'UA-141789564-1',    },    // ...  },};

`gaGtag`#

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    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. Suas opções em Markdown precisam ser convertidas em plugins Remark/Rehype.
markdownPlugins - Usamos o MDX na v2 em vez de Remarkable. Seus plugins markdown têm de ser convertidos em plugins Remark/Rehype.
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.

Como uma saída de emergência, você pode usar @docusaurus/plugin-client-redirects para criar redirecionamentos do lado do cliente de /installation.html para /installation.

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

Se você deseja manter a extensão .html como o url canônico de uma página, os documentos podem declarar um frontmatter slug: installation.html.

Componentes#

Barra Lateral#

Na versão anterior, a categoria aninhada da barra lateral não é permitida e a categoria da barra lateral pode conter apenas o id do documento. No entanto, v2 permite uma barra lateral aninhada infinita e temos muitos tipos de Item sidebar além de documento.

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']},

Rodapé#

website/core/Footer.js não é mais necessário. Se você deseja modificar o rodapé padrão fornecido pelo Docusaurus, swizzle:

npm
Yarn

npm run swizzle @docusaurus/theme-classic Footer

yarn 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: 'Facebook Open Source Logo',        src: 'img/oss_logo.png',        href: 'https://opensource.facebook.com',      },    },  },};

Páginas#

Por favor, consulte criando páginas para saber como as páginas do Docusaurus 2 funcionam. 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 `emuseDocusaurusContext` 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:

Página de índice - Flux (recomendado), Docusaurus 2, Hermes
Página de ajuda/suporte - Docusaurus 2, Flux

Conteúdo#

Substitua AUTOGENERATED_TABLE_OF_CONTENTS#

Este recurso é substituído por inline tabela de conteúdo

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

No Docusaurus 2, a sintaxe markdown foi alterada para 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.

Frontmatter é analisada por gray-matter. Se a sua frontmatter usar caracteres especiais como :, você agora precisa citá-lo: title: Parte 1: meu título da parte 1 -> title: Parte 1: "meu título da parte 1".

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.

Material inicial#

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. Eles são usados apenas para gerar a imagem de perfil do autor que pode ser feita através do campo author_image_url.

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

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

yarn build

Configuração do projeto#

package.json#

Nomes de pacotes com escopo#

tip

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#

caution

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#

Material inicial#

Deployment#

Teste seu site#

`package.json`#

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

`.gitignore`#

`README`#

`docusaurus.config.js`#

`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`#