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

Instalação

O Docusaurus é essencialmente um pacote npm packages.

tip

Use o Fast Track para entender o Docusaurus em 5 minutos ⏱!

Use docusaurus.new to test Docusaurus immediately in your browser!

Requisitos#

  • Node.js versão >= 12.13.0 ou acima (que pode ser checado executando node -v). Você pode usar o nvm para gerenciar várias versões do Node em uma única máquina instalada
  • Yarn versão >= 1.5 (que pode ser verificado executando yarn --version). Yarn é um gerenciador de pacotes performant para JavaScript e substitui o cliente npm. Não é estritamente necessário, mas altamente encorajado.

Site do projeto Scaffold#

A maneira mais fácil de instalar o Docusaurus é usar a ferramenta de linha de comando que te ajuda a criar um esqueleto de site Docusaurus. Você pode executar este comando em um novo repositório vazio ou em um repositório existente, ele criará um novo diretório contendo os arquivos iniciais.

npx @docusaurus/init@latest init [nome] [template]

Exemplo:

npx @docusaurus/init@latest init my-website classic

Se você não especificar o nome ou template, ele irá te pedir na hora. Recomendamos o modelo clássico para que você comece rapidamente e contenha recursos encontrados no Docusaurus 1. O template classic contém o @docusaurus/preset-classic que inclui uma documentação padrão, um blog, uma página customizada, e um framework CSS (com suporte a modo escuro). Você pode começar bem rápido com o template classic e customizar depois quando você conseguir mais familiaridade com o Docusaurus.

[FB-Only]: Se você estiver configurando um novo site do Docusaurus para um projeto de código aberto do Facebook, em vez disso, use o template facebook, que vem com alguns padrões úteis específicos do Facebook:

npx @docusaurus/init@latest init my-website facebook

[Experimental]: Se você deseja configurar um novo site usando bootstrap, use o template bootstrap, como o seguinte:

npx @docusaurus/init@latest init my-website bootstrap

Se você deseja pular a instalação de dependências, use a opção --skip-install, como a seguinte:

npx @docusaurus/init@latest init my-website classic --skip-install

Estrutura do projeto#

Supondo que você escolheu o modelo clássico e nomeou seu site meu-site, você verá os seguintes arquivos gerados em um novo diretório meu-website/:

meu-site├── blog│   ├── 2019-05-28-hola.md│   ├── 2019-05-29-hello-world.md│   └── 2020-05-30-welcome.md├── docs│   ├── doc1.md│   ├── doc2.md│   ├── doc3.md│   └── mdx.md├── src│   ├── css│   │   └── custom.css│   └── pages│       ├── styles.module.css│       └── index.js├── static│   └── img├── docusaurus.config.js├── package.json├── README.md├── sidebars.js└── yarn.lock

Estrutura do projeto executada#

  • /blog/ - Contém os arquivos Markdown do blog. Você pode excluir o diretório se você não quiser/precisar de um blog. Mais detalhes podem ser encontrados no guia do blog
  • /docs/ - Contém os arquivos Markdown para a documentação. Personalize a ordem da barra lateral de documentos em sidebars.js. Mais detalhes podem ser encontrados no guia de documentação
  • /src/ - Arquivos não documentados como páginas ou componentes React personalizados. Você não precisa colocar estritamente seus arquivos não relacionados a documentação aqui, mas colocá-los em um diretório centralizado torna mais fácil especificá-los caso você precise fazer algum tipo de linting/processamento
    • /src/pages - Todos os arquivos dentro deste diretório serão convertidos em uma página do site. Mais detalhes podem ser encontrados no guia de documentação
  • /static/ - Diretório de arquivos estáticos. Qualquer conteúdo dentro desta pasta vai ser copiado para a raiz da pasta build
  • /docusaurus.config.js - Um arquivo de configuração que contém a configuração do site. Isso é o equivalente ao siteConfig.js no Docusaurus v1
  • /package.json - Um site Docusaurus é uma aplicação React. Você pode instalar e usar quaisquer pacotes npm que você goste
  • /sidebar.js - Utilizado pela documentação para especificar a ordem dos documentos na barra lateral

Executando o servidor de desenvolvimento#

Para pré-visualizar suas alterações enquanto você edita os arquivos, você pode usar um servidor local de desenvolvimento que vai servir o seu site e refletir as últimas alterações.

cd meu-sitenpm run start

Por padrão, uma janela do navegador será aberta em http://localhost:3000.

Parabéns! Você acabou de criar o seu primeiro site no Docusaurus! Navegue pelo site para ver o que está disponível.

Build#

Docusaurus é um gerador de site estático moderno logo nós temos que gerar o site em uma pasta com conteúdo estático e enviar a um servidor web para que possa ser acessado. Para gerar o site:

npm run build

e os conteúdos vão ser gerados dentro da pasta /build, que pode ser copiada para qualquer hospedagem de site estático como GitHub pages, Vercel ou Netlify. Confira a documentação em lancamento para mais detalhes.

Atualizando a sua versão do Docusaurus#

Há muitas maneiras de atualizar sua versão do Docusaurus. Uma maneira garantida é alterar manualmente o número de versão em package.json para a versão desejada. Observe que todos os pacotes @docusaurus/-namespaced devem estar usando a mesma versão.

important

Por favor, atualize para a versão mais recente do Docusaurus 2 exibida no topo da página, e não no que será mostrado abaixo.

package.json
"dependencies": {  "@docusaurus/core": "^2.0.0-beta.0",  "@docusaurus/preset-classic": "^2.0.0-beta.0",  // ...}

Em seguida, no diretório que contém o package.json, execute o comando de instalação do seu gerenciador de pacotes:

npm install

Para verificar se a atualização ocorreu com sucesso, execute:

npx docusaurus --version

Você deve ver a versão correta como saída.

Como alternativa, se você estiver usando o Yarn, você pode fazer:

yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
tip

Use novas funcionalidades não lançadas do Docusaurus com a @canary npm dist tag

Problemas?#

Peça ajuda no Stack Overflow, no nosso repositório do GitHub ou Twitter.