Ir para o conteúdo principal
Version: 2.0.0-beta.19

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": "^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.

CSS Variable NameHexAdjustmentContrast Rating
--ifm-color-primary-lightest#3cad6eFail 🔴
--ifm-color-primary-lighter#359962Fail 🔴
--ifm-color-primary-light#33925dFail 🔴
--ifm-color-primary#2e85550AA 👍
--ifm-color-primary-dark#29784cAA 👍
--ifm-color-primary-darker#277148AA 👍
--ifm-color-primary-darkest#205d3bAAA 🏅

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

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

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

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

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

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

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.

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.

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