Ir para o conteúdo principal
Version: 3.6.3

Introdução

⚡️ Docusaurus will help you ship a beautiful documentation site in no time.

💸 Construir uma stack tecnológica personalizada é caro. Instead, focus on your content and just write Markdown files.

💥 Pronto para mais? Use advanced features like versioning, i18n, search and theme customizations.

💅 Check the best Docusaurus sites for inspiration.

🧐 Docusaurus is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).

Fast Track ⏱️​

Understand Docusaurus in 5 minutes by playing!

Create a new Docusaurus site and follow the very short embedded tutorial.

Install Node.js and create a new Docusaurus site:

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

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

Or read the 5-minute tutorial 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 Docusaurus v1 if:

  • ❌ 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.

Features​

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 friendly:
    • 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.

Design principles​

  • 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.

Comparison with other tools​

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 is another very popular hybrid React framework. 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.

VitePress​

VitePress has many similarities with Docusaurus - both focus heavily on content-centric websites and provides tailored documentation features out of the box. However, VitePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VitePress would be a decent choice.

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 for MkDocs is a beautiful theme.

Docsify​

Docsify makes it easy to create a documentation website, but is not a static-site generator and is not SEO friendly.

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. You may read about Redux's switch to Docusaurus here.

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

Jekyll​

Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! É extremamente simples começar. Queremos trazer uma experiência de desenvolvedor semelhante à construção de um site estático com Jekyll.

In comparison with statically generated HTML and interactivity added using <script /> tags, Docusaurus sites are React apps. 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.

Staying informed​

Falta alguma coisa?​

If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please file an issue for us, or send a tweet mentioning the @docusaurus X account.

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!