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

Introdução

⚡ Docusaurus vai te ajudar a enviar um site de belíssima documentação num piscar de olhos.

💸 Construir uma stack tecnológica personalizada é caro. Em vez disso, se concentre em seu conteúdo e apenas escreva arquivos Markdown.

💥 Pronto para mais? Use recursos avançados como versão, i18n, pesquisa e personalização de temas.

💅 Confira os melhores sites do Docusaurus para inspiração e leia alguns depoimentos.

🧐 Docusaurus é um gerador de site-estático. Ele compila uma aplicação de uma página única com uma rápida navegação no lado do cliente, utilizando o poder completo do React para tornar seu site interativo. Ele fornece funcionalidades da documentação fora da caixa, mas pode ser usado para criar qualquer tipo de site (website pessoal, produto, blog, páginas de marketing, etc).

Introdução ao Docusaurus Slash

Fast Track ⏱️#

Entenda o Docusaurus em 5 minutos jogando!

Crie um novo site Docusaurus e siga o muito breve tutorial incorporado.

Instale o Node.js e crie um novo site Docusaurus:

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

Iniciar o site:

cd my-websitenpx docusaurus start

Abra http://localhost:3000 e siga o tutorial.

tip

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

Ou leia o tutorial de 5 minutos online.

Isenção de responsabilidade#

O Docusaurus v2 é beta, mas já é bastante estável e amplamente utilizado.

Nós te encorajamos muito a usar o Docusaurus v2 sobre o Docusaurus v1, já que o Docusaurus v1 não vai mais ser usado.

Muitos usuários já estão usando o Docusaurus v2 (tendências).

Use o Docusaurus v2 se:

  • ✅ Você quer um site moderno de documentação do Jamstack
  • ✅ Você quer uma aplicação de página única (SPA) com roteamento do lado cliente
  • ✅ Você quer o poder completo do React e do MDX
  • ✅ Você não precisa de suporte para o IE11

Use Docusaurus v1 se:

  • ❌ Você não quer um aplicativo de página única (SPA)
  • ❌ Você precisa de suporte para o IE11

Funcionalidades#

O Docusaurus é construído com grande atenção para o desenvolvedor e para o colaborador.

  • ⚛️ Construído com 💚 e React
    • Amplie e personalize com React
    • Obtenha controle total da experiência de navegação de seu site fornecendo seus próprios componentes React
  • Plugável
    • Inicialize o seu site com um modelo básico, depois use recursos e plugins avançados
    • Abra o código dos seus plug-ins para compartilhar com a comunidade
  • ✂️ Experiência do desenvolvedor
    • Comece a escrever sua documentação agora mesmo
    • Ponto de entrada de configuração universal para torná-lo mais fácil de manter pelos contribuidores
    • Recarregamento a quente com base incremental extremamente rápida nas mudanças
    • Divisão de dados e código baseado em rota
    • Publicar no GitHub Pages, Netlify, Vercel e outros serviços de deploy com facilidade

Nosso objetivo comum - ajudar seus usuários a encontrar o que precisam rapidamente e entender melhor seus produtos. Compartilhamos com você as nossas melhores práticas ajudando você a construir o seu site de documentos diretamente e bem.

  • 🎯 SEO amigável
    • Arquivos HTML são gerados estaticamente por todos os caminhos possíveis
    • SEO específico para ajudar seus usuários a pousarem em sua documentação oficial diretamente relacionando seus problemas
  • 📝 Desenvolvido por MDX
    • Escrever componentes interativos via JSX e React incorporados em markdown
    • Compartilhe seu código em editores ao vivo para fazer com que seus usuários amem seus produtos na hora
  • 🔍 Pesquisa - Seu site completo é pesquisável
  • 💾 Versão do Documento - Ajuda você a manter a documentação sincronizada com as versões do projeto.
  • 🌍 i18n - Traduza seu site em várias localidades

Docusaurus 2 nasceu para ser compassivamente acessível a todos os seus usuários, e muito rápido.

  • ⚡ Raio rápido - Docusaurus 2 segue o padrão PRPL que garante que seu conteúdo carregue rápido
  • 🦖 Acessível - Atenção à acessibilidade, tornando seu site igualmente acessível para todos os usuários

Princípios de design#

  • Pouco para aprender - Docusaurus deve ser fácil de aprender e usar, já que a API é muito pequena. A maioria das coisas ainda será alcançada pelos usuários, mesmo que leve mais código e mais tempo para escrever. Não ter abstrações é melhor do que ter as abstrações erradas, e não queremos que os usuários tenham que hackear as abstrações erradas. Conversa obrigatória - Área mínima de Superfície da API.
  • Intuitivo - Os usuários não se sentirão sobrecarregados ao olhar para o diretório do projeto de um projeto Docusaurus ou ao adicionar novas funcionalidades. Deve parecer intuitivo e fácil de desenvolver, utilizando abordagens que conheçam.
  • Construção em Camadas - As separações das preocupações entre cada camada da nossa pilha (conteúdo/tema/estilo) devem ser claras - bem abstraídas e modulares.
  • Padrões sensíveis - Otimizações e configurações de desempenho comuns e populares serão feitas para usuários mas eles têm a opção de substituí-las.
  • Sem bloqueio de fornecedor - Os usuários não são obrigados a usar os plug-ins ou CSS padrão, embora sejam altamente encorajados a fazê-lo. Certas peças básicas de nível inferior, como React Loadable, React Router, não podem ser trocadas porque fazemos a otimização de desempenho padrão nelas. Mas não os de nível mais alto, como a escolha de mecanismos de Markdown, frameworks CSS, metodologia CSS serão inteiramente de responsabilidade dos usuários.

Acreditamos que, como desenvolvedores, saber como uma biblioteca funciona é útil para nos tornarmos melhores em seu uso. Daí estamos dedicando esforços para explicar a arquitetura e vários componentes do Docusaurus, com a esperança de que os usuários que a lerem ela adquiram uma compreensão mais profunda da ferramenta e sejam ainda mais proficientes em usá-la.

Comparação com outras ferramentas#

Em todos os geradores de sites estáticos, o Docusaurus tem um foco exclusivo em sites de documentação e tem muitos recursos prontos para uso.

Também estudamos outros geradores de sites estáticos principais e gostaríamos de compartilhar nossos insights sobre a comparação, esperançosamente para ajudá-lo a navegar pelas escolhas prismáticas que existem.

Gatsby#

Gatsby está cheio de muitos recursos, tem um rico ecossistema de plugins e é capaz de fazer tudo o que o Docusaurus faz. Naturalmente, isso tem o custo de uma curva de aprendizado mais alta. Gatsby faz muitas coisas bem e é adequado para construir muitos tipos de sites. Por outro lado, Docusaurus tenta fazer uma coisa muito bem - ser a melhor ferramenta para escrever e publicar conteúdo.

GraphQL também é um belo núcleo para o Gatsby, embora você não necessite realmente do GraphQL para construir um site do Gatsby. Na maioria dos casos ao construir sites estáticos, você não precisará da flexibilidade que o GraphQL oferece.

Muitos aspectos do Docusaurus 2 foram inspirados nas melhores coisas sobre Gatsby e é uma ótima alternativa.

Docz é um tema Gatsby para construir o site da documentação. Atualmente é menos destaque do que o Docusaurus.

Next.js#

Next.js é outro framework híbrido muito popular em React. Ele pode ajudá-lo a construir um bom site de documentação, mas não é consultado para o caso de uso da documentação, e vai precisar de muito mais trabalho para implementar o que o Docusaurus oferece fora da caixa.

Nextra é um gerador estático pensado construído sobre o Next.js. Atualmente é menos destaque do que o Docusaurus.

VuePress#

VuePress tem muitas semelhanças com o Docusaurus - ambas se concentram fortemente em sites centrados no conteúdo e fornecem recursos de documentação personalizados. No entanto, VuePress é alimentado por Vue, enquanto o Docusaurus é alimentado por React. Se você quiser uma solução baseada em Vue, o VuePress seria uma escolha decente.

MkDocs#

MkDocs é um popular static-site-generator em Python com proposição de valores semelhante ao Docusaurus.

É uma boa opção se você não precisa de um aplicativo de página única e não planeja aproveitar o React.

Material para MkDocs é um belo tema.

Docsify#

Docsify torna fácil a criação de um site de documentação, mas não é um gerador estático de sites e não tem o recurso de SEO amigável.

GitBook#

GitBook tem um design muito limpo e foi usado por vários projetos de código aberto. Com seu foco mudando para um produto comercial em vez de uma ferramenta de código aberto, muitos de seus requisitos não atendem mais às necessidades de um site de documentação de projeto de código aberto. Como resultado, muitos recorreram a outros produtos. Você pode ler sobre a mudança do Redux para o Docusaurus aqui.

Atualmente, o GitBook é gratuito apenas para equipes sem fins lucrativos. O Docusaurus é gratuito para todos.

Jekyll#

Jekyll é um dos geradores de sites estáticos mais maduros e tem sido uma ótima ferramenta de uso — na verdade, antes do Docusaurus, a maioria dos sites de código aberto do Facebook são/foram construídos em Jekyll! É extremamente simples começar. Queremos trazer uma experiência de desenvolvedor semelhante à construção de um site estático com Jekyll.

Em comparação com as tags <script /> geradas em HTML e interatividade adicionada, os sites do Docusaurus são aplicativos React. Usando ferramentas modernas de ecossistema do JavaScript, esperamos definir novos padrões para o desempenho dos sites, pipeline de compilação de ativos e otimizações e facilitação de configuração.

Mantendo-se informado#

Falta alguma coisa?#

Se você encontrar problemas com a documentação ou tiver sugestões sobre como melhorar a documentação ou o projeto em geral. por favor arquive um problema para nós, ou envie um tweet mencionando a conta do Twitter @docusaurus.

Para novas funcionalidades solicitadas, você pode criar um post em nosso Canny board, que é uma ferramenta útil para planejamento e permite ordenar por votos, o que dá à equipe central um melhor indicador de quais recursos estão em alta demanda, em comparação com problemas com o GitHub que são mais difíceis de testar. Evite fazer uma solicitação para novos recursos (especialmente grandes), pois alguém pode já estar trabalhando nisso ou fazer parte de nosso planejamento. Fale conosco primeiro!