CLI Commands
O Docusaurus fornece um conjunto de scripts para ajudar você a gerar, servir e implantar seu site. Estes scripts podem ser invocados com o comando Executar quando usando Yarn ou npm. Alguns comandos comuns são:
yarn run start: prepara e serve o site a partir de um servidor localyarn run examples: cria exemplos de arquivos de configuração
Executando pela linha de comando
Os scripts podem ser executados usando o Yarn ou npm. Se você já passou por nosso guia de introdução, você já pode estar familiarizado com o comando start. É o comando que diz ao Docusaurus para executar o script docusaurus-start, que gera o site e inicia um servidor. Ele geralmente é chamado desta forma:
yarn run start
O mesmo script pode ser chamado usando o npm:
npm run start
Para executar algum outro script em particular, basta substituir o comando start nos exemplos acima pelo comando associado ao seu script.
Usando argumentos
Alguns comandos podem receber argumentos opcionais. Por exemplo, para iniciar um servidor na porta 8080, você pode adicionar o argumento --port ao executar o script start:
yarn run start --port 8080
Caso prefira usar o npm para executar o Docusaurus, você ainda pode usar argumentos de linha de comando inserindo um -- entre npm run <comando> e os argumentos do comando:
npm run start -- --port 8080
Configuração
Esses scripts são definidos dentro da chave "scripts" do seu arquivo website/package.json como parte do processo de instalação. Se precisar de ajuda para configurá-los novamente, dê uma olhada no guia de instalação.
O Docusaurus oferece atalhos padrões para que você possa executar comandos seguindo as convenções do Node. Em vez de digitar docusaurus-start toda vez, você pode usar yarn run start ou npm start para fazer a mesma coisa.
Comandos
docusaurus-builddocusaurus-examplesdocusaurus-publishdocusaurus-rename-versiondocusaurus-startdocusaurus-version <version>docusaurus-write-translations
Referência
docusaurus-build
Atalho: build.
| Opções | Padrão | Descrição |
|---|---|---|
--skip-image-compression | false | Pula a etapa de compressão dos assets de imagem. Geralmente, você não vai querer pular isso a não ser que as suas imagens já estejam otimizadas. |
--skip-next-release | false | Ignora os documentos de versões posteriores quando o versionamento estiver ativado. Isto fará com que os arquivos HTML dos documentos no diretório /docs não sejam gerados. |
Gera o site estático, aplicando as traduções, se necessário. Útil para preparar e construir o site antes de ser publicado.
Veja também docusaurus-start.
docusaurus-examples
Atalho: examples
| Argumentos | Padrão | Descrição |
|---|---|---|
<recurso> | - | Gera arquivos de exemplo adicionais para o recurso especificado, seja ele translations ou versions. |
Exemplo
docusaurus-examples <recurso>
Se nenhum recurso for especificado, o comando cria um exemplo com as configurações mínimas necessárias para o funcionamento do site. Este comando é abordado em detalhes no guia de preparação do site.
docusaurus-publish
Atalho: publish-gh-pages
Constrói e depois implementa o site estático no GitHub Pages. Este comando foi criado originalmente para ser executado durante a etapa de implementação no CircleCI e, portanto, espera que algumas variáveis de ambiente sejam definidas:
As seguintes variáveis de ambiente são geralmente definidas manualmente pelo usuário no arquivo config.yml do CircleCI.
GIT_USER: O usuário Git a ser associado ao commit de deploy.USE_SSH: Controla se a conexão com o seu repositório do GitHub será realizada via SSH, em vez de HTTPS.
Exemplo
GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
As seguintes variáveis de ambiente são definidas pelo CircleCI durante o processo de build.
CIRCLE_BRANCH: A branch do Git associada ao commit que disparou a execução do CircleCI.CI_PULL_REQUEST: Presume-se que o valor desta seja verdadeiro caso a execução do CI tenha sido disparada por um commit de um pull request.
As seguintes devem ser configuradas por você no seu siteConfig.js na forma dos campos organizationName e projectName, respectivamente. Caso não estejam definidas nas configurações do seu site, o script verificará se elas estão presentes no ambiente do CircleCI.
CIRCLE_PROJECT_USERNAME: O nome de usuário ou de organização que hospeda o repositório Git (ex.: "facebook").CIRCLE_PROJECT_REPONAME: O nome do repositório git (ex.: "Docusaurus").
Você pode aprender mais sobre como configurar deploys automáticos no CircleCI no guia de publicação.
docusaurus-rename-version
Atalho: rename-version
Renomeia uma versão existente da documentação para um novo nome de versão.
| Argumentos | Padrão | Descrição |
|---|---|---|
<versãoAtual> | - | Versão a ser renomeada. |
<novaVersão> | - | Novo nome da versão. |
Exemplo
docusaurus-rename-version <versãoAtual> <novaVersão>
Consulte o guia de versionamento para saber mais.
docusaurus-start
Alias: start.
Esse comando criará o site estático, aplicará traduções, se necessário, e depois iniciará um servidor local.
| Opções | Padrão | Descrição |
|---|---|---|
--port <número> | 3000 | O site será servido na porta 3000 por padrão, mas se a porta estiver ocupada, o Docusaurus tentará encontrar uma disponível. |
--host <host> | localhost | Específica um host a ser usado. Pro exemplo, se você quiser que seu servidor seja acessível externamente, você pode usar --host 0.0.0.0. |
--watch | - | Permite monitorar os arquivos e recarregar automaticamente a página no navegador quando os arquivos forem alterados. O padrão é true. Desative isso usando --no-watch. |
You can specify the browser application to be opened by setting the BROWSER environment variable before the command, e.g.:
$ BROWSER=firefox yarn start
docusaurus-version <version>
Atalho: version
Gera uma nova versão da documentação. Isso criará uma nova cópia do seu site, que será armazenada no diretório da versão criada. Isso é útil para salvar os estados da documentação da sua API que correspondam a versões específicas do seu software. Aceita qualquer string como um número de versão.
Consulte o guia de versionamento para saber mais.
docusaurus-write-translations
Atalho: write-translations
Escreve todas as strings em Inglês que precisam ser traduzidas para um arquivo website/i18n/en.json. O script irá analisar todos os arquivos dentro de website/pages/en, o arquivo siteConfig.js e outros arquivos de configuração em busca de strings em inglês para que sejam traduzidas no Crowdin. Consulte o guia de tradução para saber mais.