Instalação
Docusaurus consists of a set of npm packages.
Use the Fast Track to understand Docusaurus in 5 minutes ⏱!
Use docusaurus.new to test Docusaurus immediately in your browser!
Requirements
- Node.js version 18.0 or above (which can be checked by running
node -v
). You can use nvm for managing multiple Node versions on a single machine installed.- Ao instalar o Node.js, é recomendável que você marque todas as caixas de seleção relacionadas às dependências.
Scaffold project website
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
We recommend the classic
template so that you can get started quickly, and it contains features found in Docusaurus 1. The classic
template contains @docusaurus/preset-classic
which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). Você pode começar bem rápido com o template classic e customizar depois quando você conseguir mais familiaridade com o Docusaurus.
You can also use the template's TypeScript variant by passing the --typescript
flag. 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.
Project structure
Assuming you chose the classic template and named your site my-website
, you will see the following files generated under a new directory my-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
Project structure rundown
/blog/
- Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting thepath
option. More details can be found in the blog guide/docs/
- Contains the Markdown files for the docs. Customize the order of the docs sidebar insidebars.js
. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting thepath
option. More details can be found in the docs guide/src/
- Non-documentation files like pages or custom React components. É 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
- Any JSX/TSX/MDX file within this directory will be converted into a website page. More details can be found in the pages guide
/static/
- Static directory. Any contents inside here will be copied into the root of the finalbuild
directory/docusaurus.config.js
- A config file containing the site configuration. This is the equivalent ofsiteConfig.js
in Docusaurus v1/package.json
- A Docusaurus website is a React app. Você pode instalar e usar quaisquer pacotes npm que você goste/sidebars.js
- Used by the documentation to specify the order of documents in the sidebar
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.
Running the development server
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
and contents will be generated within the /build
directory, which can be copied to any static file hosting service like GitHub pages, Vercel or Netlify. Check out the docs on deployment for more details.
Updating your Docusaurus version
Há muitas maneiras de atualizar sua versão do Docusaurus. One guaranteed way is to manually change the version number in package.json
to the desired version. Note that all @docusaurus/
-namespaced packages should be using the same version.
You are browsing the documentation of an outdated version. The snippet below shows how to upgrade to the latest version.
{
"dependencies": {
"@docusaurus/core": "3.5.2",
"@docusaurus/preset-classic": "3.5.2",
// ...
}
}
Then, in the directory containing package.json
, run your package manager's install command:
- npm
- Yarn
- pnpm
npm install
yarn install
pnpm 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 add @docusaurus/core @docusaurus/preset-classic
Use new unreleased features of Docusaurus with the @canary
npm dist tag
Problemas?
Ask for help on Stack Overflow, on our GitHub repository, our Discord server, or X.