Pular para o conteúdo principal
Version: Canary 🚧

Introdução

⚡ Docusaurus vai te ajudar a criar um site de documentação incrível 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 cria uma SPA com navegação rápida do lado do cliente, aproveitando todo o poder do React para tornar seu site totalmente interativo.
Foi criado com a ideia de fornecer funcionalidades voltadas para documentações, mas pode ser usado para criar qualquer tipo de página (website pessoal, produto, blog, páginas de marketing, etc).

Faixa Rápida ⏱️​

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 create-docusaurus@latest my-website classic

Iniciar o site:

cd my-website
npx docusaurus start

Open http://localhost:3000 and follow the tutorial.

tip

Visite docusaurus.new para experimentar Docusaurus agora no seu navegador!

Ou leia um tutorial de 5 minutos online.

Docusaurus: Documentation Made Easy​

In this presentation at Algolia Community Event, Meta Open Source team shared a brief walk-through of Docusaurus. They covered how to get started with the project, enable plugins, and set up functionalities like documentation and blogging.

Migrating from v1​

Docusaurus v2+ has been a total rewrite from Docusaurus v1, taking advantage of a completely modernized toolchain. After v2's official release, we highly encourage you to use Docusaurus v2+ over Docusaurus v1, as Docusaurus v1 has been deprecated.

A lot of users are already using Docusaurus v2+ (trends).

Use Docusaurus v2+ if:

  • ✅ 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 o Docusaurus v2 se:

  • ❌ Você não quer um aplicativo de página única (SPA)
  • ❌ You need support for IE11 (...do you? IE has already reached end-of-life and is no longer officially supported)

For existing v1 users that are seeking to upgrade to v2+, you can follow our migration guides.

Funcionalidades​

Docusaurus is built with high attention to the developer and contributor experience.

  • ⚛️ Built with 💚 and React:
    • Amplie e personalize com React
    • Obtenha controle total da experiência de navegação de seu site fornecendo seus próprios componentes React
  • Pluggable:
    • 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
  • ✂️ Developer experience:
    • 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
    • Hot reloading with lightning-fast incremental build on changes
    • Divisão de dados e código baseado em rota
    • Publish to GitHub Pages, Netlify, Vercel, and other deployment services with ease

Our shared goal—to help your users quickly find what they need and understand your products better. We share our best practices to help you build your docs site right and well.

  • 🎯 SEO amigável:
    • HTML files are statically generated for every possible path.
    • Page-specific SEO to help your users land on your official docs directly relating their problems at hand.
  • 📝 Powered by MDX:
    • Write interactive components via JSX and React embedded in Markdown.
    • Share your code in live editors to get your users to love your products on the spot.
  • 🔍 Search: Your full site is searchable.
  • 💾 Document Versioning: Helps you keep documentation in sync with project releases.
  • 🌍 Internationalization (i18n): Translate your site in multiple locales.

Docusaurus v2+ is born to be compassionately accessible to all your users, and lightning-fast.

  • ⚡️ Lightning-fast. Docusaurus v2+ follows the PRPL Pattern that makes sure your content loads blazing fast.
  • 🦖 Accessible. Attention to accessibility, making your site equally accessible to all users.

Princípios de design​

  • Little to learn. Docusaurus should be easy to learn and use as the API is quite small. 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. Mandatory talk—Minimal API Surface Area.
  • Intuitive. Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. Deve parecer intuitivo e fácil de desenvolver, utilizando abordagens que conheçam.
  • Layered architecture. The separations of concerns between each layer of our stack (content/theming/styling) should be clear—well-abstracted and modular.
  • Sensible defaults. Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
  • No vendor lock-in. Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core infrastructures like React Loadable and React Router cannot be swapped because we do default performance optimization on them, but not higher-level ones. Choice of Markdown engines, CSS frameworks, CSS methodology, and other architectures will be entirely up to users.

We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.

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.

We've also studied other main static site generators and would like to share our insights on the comparison, hopefully helping you navigate through the prismatic choices out there.

Gatsby​

Gatsby is packed with a lot of features, has a rich ecosystem of plugins, and is capable of doing everything that Docusaurus does. 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.

Many aspects of Docusaurus v2+ were inspired by the best things about Gatsby and it's a great alternative.

Docz is a Gatsby theme to build documentation websites. 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 is an opinionated static site generator built on top of 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 is a popular Python static site generator with value propositions similar to Docusaurus.

It is a good option if you don't need a single-page application and don't plan to leverage 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 has a very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs of open source projects' documentation sites. 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. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites' performance, asset building pipeline and optimizations, and ease to set up.

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.

For new feature requests, you can create a post on our feature requests board (Canny), which is a handy tool for road-mapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. 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!