Skip to main content
Version: 2.0.0-alpha.70

Introduction

Attention#

Docusaurus v2 est encore en alpha (depuis mi-2019) mais déjà assez stable.

Nous vous encourageons fortement à utiliser Docusaurus v2 plutôt que Docusaurus v1.

La plupart des utilisateurs utilisent déjà la v2 (tendances), y compris React Native, Redux et bien d'autres.

Utilisez Docusaurus v2 si:

  • ✅ Vous voulez un site de documentation moderne utilisant la Jamstack
  • ✅ Vous voulez une single-page-application (SPA) avec un routing côté client
  • ✅ Vous voulez la pleine puissance de React et MDX
  • ✅ Vous n'avez pas besoin de support pour IE11

Utilisez Docusaurus v1 si:

  • ❌ Vous ne voulez pas de single-page-application (SPA)
  • ❌ Vous préférez la stabilité plutôt que la modernité (essayez Docusaurus 1 à la place)
  • ❌ Vous avez besoin de support pour IE11

Un meilleur Docusaurus arrive#

Docusaurus Slash Introduction

Docusaurus 1 était un générateur de site de documentation simple. Dans Docusaurus 2, nous l'avons reconstruit de zéro, en permettant une plus grande personnalisation, mais préservant les meilleures parties de Docusaurus 1 - facile à démarrer, documentation versionnés, et i18n (bientôt).

Au-delà de cela, Docusaurus 2 est un générateur de site statique performant et peut être utilisé pour créer des sites web courants (documentation, blogs, landing pages de produits et de marketing, etc) très rapidement.

Bien que notre objectif principal reste de vous aider à créer rapidement de la documentation de qualité, il est possible de construire n'importe quel type de site web en utilisant Docusaurus 2, car c'est juste une application React. Docusaurus peut maintenant être utilisé pour construire n'importe quel site web, pas seulement des sites de documentation.

Fonctionnalités#

Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors.

  • ⚛️ Développé avec 💚 et React
    • Extend and customize with React
    • Gain full control of your site's browsing experience by swizzling in your own components
  • Pluggable
    • Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community
    • Open source your plugins to share with your fellow documentarians, because sharing is caring
  • ✂️ Developer experience
    • Multiple bootstrapping templates to get your site up and running, start writing your docs right now
    • Universal configuration entry point to make it more maintainable by contributors
    • Hot reloading with lightning fast incremental build on changes
    • Route-based code and data splitting
    • Publish to GitHub Pages, Netlify, and other deployment services with ease

Our shared goal — to help your users find what they need fast, and understand your products better. With the experience of Docusaurus 1, we share with you our best practices to help you build your doc 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 love your products on the spot
  • 🔍 Search - Your full site is searchable
  • 💾 Document Versioning - Helps you keep documentation in sync with project releases.
  • 🌍 i18n (coming soon)

Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast.

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

Comparaison avec d'autres outils#

Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need.

We've also studied other main static site generators and would like to share our insights on the comparison, hopefully to help 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. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.

GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.

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

GitBook#

GitBook has 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 as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus here.

Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.

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! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with 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 build pipeline and optimizations, and ease to setup.

VuePress#

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

Rester informé#

Il manque quelque chose ?#

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 Twitter account.

Pour de nouvelles demandes de fonctionnalités, vous pouvez créer un message sur notre tableau Canny, qui est un outil pratique pour la cartographie de la route et permet de trier par votes, donnant à l'équipe principale un meilleur indicateur de fonctionnalités étant en forte demande, par rapport aux issues de GitHub qui sont plus difficiles à trier. Évitez de faire un Pull Request pour de nouvelles fonctionnalités (en particulier celles grandes) car quelqu'un pourrait déjà y travailler ou fera déjà partie de notre feuille de route. Parlez-nous d'abord !