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

Instalação

Docusaurus is essentially a set of 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 version >= 14 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed.
    • When installing Node.js, you are recommended to check all checkboxes related to dependencies.
  • 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 create-docusaurus@latest [name] [template]

Exemplo:

npx create-docusaurus@latest website classic

Se você não especificar o nome ou template, ele irá te pedir na hora. We recommend the classic template so that you can get started quickly, and it contains features found in 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.

The template also accepts a git repo URL or a local file path, with the latter evaluated relative to the current working directory. The repo/folder content will be copied to the site directory.

FB-Only

If you are setting up a new Docusaurus website for a Facebook open source project, use the facebook template instead, which comes with some useful Facebook-specific defaults:

npx create-docusaurus@latest my-website facebook

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

npx create-docusaurus@latest my-website classic --skip-install

You can also use the template's TypeScript variant by passing the --typescript flag.

npx create-docusaurus@latest my-website classic --typescript

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. More details can be found in the blog guide
  • /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

Monorepos

If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase the latest features, instead of depending on a released version; your contributors can also conveniently update the docs as they implement features. An example monorepo folder structure is below:

my-monorepo
├── package-a # Another package, your actual project
│ ├── src
│ └── package.json # Package A's dependencies
├── website # Docusaurus root
│ ├── docs
│ ├── src
│ └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies

In this case, you should run npx create-docusaurus within the ./my-monorepo folder.

If you're using a hosting provider such as Netlify or Vercel, you will need to change the Base directory of the site to where your Docusaurus root is. In this case, that would be ./website. Read more about configuring ignore commands in the deployment docs.

Read more about monorepos in the Yarn documentation (Yarn is not the only way to set up a monorepo, but it's a common solution), or checkout Docusaurus and Jest for some real-world examples.

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

caution

You are browsing the documentation of an outdated version. The snippet below shows how to upgrade to the latest version.

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

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?

Ask for help on Stack Overflow, on our GitHub repository, our Discord server, or Twitter.