Instalação
Docusaurus consists of a set of npm packages.
Use the Fast Track to understand Docusaurus in 5 minutes ⏱!
Visite docusaurus.new para experimentar Docusaurus agora no seu navegador!
Requisitos
- Node.js version 18.0 or above (which can be checked by running
node -v
). Você pode usar o nvm para gerenciar múltiplas versões do Node em uma única máquina.- Ao instalar o Node.js, é recomendável que você marque todas as caixas de seleção relacionadas às dependências.
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 my-website classic
Recomendamos o modelo clássico
para que você possa começar rapidamente, e ele contém 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.
Você também pode usar a variante de TypeScript passando a flag --typescript
. See TypeScript support for more information.
npx create-docusaurus@latest my-website classic --typescript
If you are setting up a new Docusaurus website for a Meta open source project, run this command inside an internal repository, which comes with some useful Meta-specific defaults:
scarf static-docs-bootstrap
Alternative installation commands
You can also initialize a new project using your preferred project manager:
- npm
- Yarn
- pnpm
npm init docusaurus
yarn create docusaurus
pnpm create docusaurus
Run npx create-docusaurus@latest --help
, or check out its API docs for more information about all available flags.
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ê desativou o plugin de blog, ou você pode mudar o nome do mesmo depois de definir a opçãopath
. 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 emsidebars.js
. Você pode excluir o diretório se você desativou o plugin de documentação, ou você pode mudar o nome depois de definir a opçãopath
. More details can be found in the docs guide/src/
- Arquivos não relacionados a documentação como páginas ou componentes React personalizados. É opcional colocar seus arquivos não relacionados à documentação aqui, mas colocando num diretório centralizado facilita especificar no caso de você precisar realizar algum tipo de linting ou processamento/src/pages
- Qualquer arquivo JSX/TSX/MDX dentro desse diretório será convertido numa página do site. More details can be found in the pages guide
/static/
- Diretório de arquivos estáticos. Qualquer conteúdo dentro desta pasta vai ser copiado para a raiz da pastabuild
/docusaurus.config.js
- Um arquivo de configuração que contém a configuração do site. Isso é o equivalente aositeConfig.js
no Docusaurus v1/package.json
- Um site Docusaurus é uma aplicação React. Você pode instalar e usar quaisquer pacotes npm que você goste/sidebars.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 latest features instead of depending on a released version. Then, your contributors can 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.
- npm
- Yarn
- pnpm
cd meu-site
npm run start
cd meu-site
yarn run start
cd meu-site
pnpm run start
By default, a browser window will open at 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
- Yarn
- pnpm
npm run build
yarn build
pnpm 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.
You are browsing the documentation of an unreleased version. If you want to use any unreleased feature, you can use the @canary
release.
{
"dependencies": {
"@docusaurus/core": "3.6.0",
"@docusaurus/preset-classic": "3.6.0",
// ...
}
}
Em seguida, no diretório que contém o package.json
, execute o comando de instalação do seu gerenciador de pacotes:
- npm
- Yarn
- pnpm
npm install
yarn install
pnpm install
npm install
may report several vulnerabilities and recommend running npm audit
to address them. Typically, these reported vulnerabilities, such as RegExp DOS vulnerabilities, are harmless and can be safely ignored. Also read this article, which reflects our thinking: npm audit: Broken by Design.
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 add @docusaurus/core @docusaurus/preset-classic
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 X.