Aller au contenu principal
Version: 2.0.0-alpha.73 🚧

Introduction

Avertissement#

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 Jamstack moderne
  • ✅ Vous voulez une single-page-application (SPA) avec un routage côté client
  • ✅ Vous voulez la pleine puissance de React et MDX
  • ✅ Vous n'avez pas besoin de support pour IE11
astuce

Accédez à new.docusaurus.io pour tester immédiatement Docusaurus dans CodeSandbox.

Utilisez Docusaurus v1 si :

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

Un meilleur Docusaurus arrive#

Docusaurus Slash Introduction

Docusaurus 1 était un pur générateur de sites de documentation. 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, documentations versionnées, et i18n (bientôt).

En outre, Docusaurus 2 est un générateur de sites statiques performant et peut être utilisé pour créer extrêmement rapidement des sites Web courants axés sur le contenu (par exemple, documentation, blogs, pages de présentation de produit et de marketing, etc).

Même si notre objectif principal sera toujours de vous aider à obtenir des documentations correctes et bien faites, il est possible de construire n'importe quel type de site Web à l'aide de Docusaurus 2 puisqu'il s'agit simplement d'une application React. Docusaurus peut maintenant être utilisé pour construire n'importe quel site web, pas seulement des sites de documentation.

Fonctionnalités#

Docusaurus est construit avec une grande attention à la manière dont vous allez construire votre site et le maintenir avec vos collaborateurs et contributeurs.

  • ⚛️ Développé avec 💚 et React
    • Étendre et personnaliser avec React
    • Prenez le contrôle total de l'expérience de navigation de votre site en utilisantswizzling dans vos propres composants
  • Pluggable
    • Créez votre site à l'aide d'un modèle de base, puis choisissez et ajoutez des fonctionnalités créées par nous et notre communauté
    • Publiez vos plugins en open source pour les partager avec vos collègues documentalistes, parce que partager, c'est se soucier des autres
  • ✂️ Expérience développeur
    • Plusieurs modèles de démarrage pour que votre site soit opérationnel, commencez à rédiger votre documentation dès à présent
    • Point d'entrée de configuration universel pour le rendre plus supportable par les contributeurs
    • Rechargement à chaud avec une construction incrémentale rapide comme l'éclair en cas de changement
    • Fractionnement du code et des données en fonction de la route
    • Publiez facilement sur GitHub, Netlify, et d'autres services de déploiement

Notre objectif commun est d'aider vos utilisateurs à trouver rapidement ce dont ils ont besoin et à mieux comprendre vos produits. Avec l'expérience de Docusaurus 1, nous partageons avec vous nos meilleures pratiques pour vous aider à construire votre site Docusaurus correctement et bien.

  • 🎯 Référencement convivial
    • Les fichiers HTML sont générés de manière statique pour tous les chemins possibles
    • un référencement spécifique à chaque page pour aider vos utilisateurs à accéder à vos documents officiels en rapport direct avec leurs problèmes
  • 📝 Propulsé par MDX
    • Écrire des composants interactifs via JSX et React intégrés dans markdown
    • Partagez votre code dans des éditeurs dynamiques pour que vos utilisateurs aiment vos produits sur le champ
  • 🔍 Recherche - Votre site complet est interrogeable
  • 💾 Document versionné - vous aide à garder la documentation en synchronisation avec les versions du projet.
  • 🌍 i18n

Docusaurus 2 est conçu pour être accessible avec bienveillance à tous vos utilisateurs, et rapide comme l'éclair.

  • ⚡️ Rapide comme l'éclair - Docusaurus 2 suit le modèle PRPL qui garantit un chargement rapide de votre contenu
  • 🦖 Accessible - Une attention particulière à l'accessibilité, afin que votre site soit accessible à tous les utilisateurs

Comparaison avec d'autres outils#

Parmi tous les générateurs de sites statiques, Docusaurus se concentre sur les sites de documents et possède la structure prête à l'emploi dont vous avez besoin.

Nous avons également étudié d'autres grands générateurs de sites statiques et nous souhaitons partager notre point de vue sur la comparaison, en espérant vous aider à vous y retrouver parmi les choix multiples qui s'offrent à vous.

Gatsby#

Gatsby est doté d'un grand nombre de fonctionnalités, d'un riche écosystème de plugins et est capable de faire tout ce que fait Docusaurus. Naturellement, cela a pour contrepartie une courbe d'apprentissage plus élevée. Gatsby fait beaucoup de choses bien et est adapté à la construction de nombreux types de sites Web. D'un autre côté, Docusaurus essaie de faire une chose super bien - être le meilleur outil pour écrire et publier du contenu.

GraphQL est également au cœur de Gatsby, même si vous n'avez pas nécessairement besoin de GraphQL pour créer un site Gatsby. Dans la plupart des cas, lorsque vous construisez des sites Web statiques, vous n'aurez pas besoin de la flexibilité que GraphQL offre.

De nombreux aspects du Docusaurus 2 ont été inspirés par les meilleures choses de Gatsby et c'est une excellente alternative.

GitBook#

GitBook a une conception très propre et a été utilisé par de nombreux projets open source. L'accent étant mis sur un produit commercial plutôt que sur un outil open-source, nombre de ses exigences ne correspondent plus aux besoins d'un site de documentation d'un projet open source. En conséquence, beaucoup se sont tournés vers d'autres produits. Vous pouvez lire le passage de Redux à Docusaurus ici.

Actuellement, GitBook n'est gratuit que pour les équipes open-source et sans but lucratif. Docusaurus est gratuit pour tout le monde.

Jekyll#

Jekyll est l'un des générateurs de sites statiques les plus aboutis et s'est avéré un outil très utile. En fait, avant Docusaurus, la plupart des sites Open Source de Facebook étaient ou étaient construits sur Jekyll ! Il est extrêmement simple pour démarrer. Nous voulons apporter une expérience de développement similaire à celle de la construction d'un site statique avec Jekyll.

En comparaison avec le HTML généré statiquement et l'interactivité ajouté en utilisant les balises <script /> , les sites Docusaurus sont des applications React. Grâce aux outils modernes de l'écosystème JavaScript, nous espérons établir de nouvelles normes en matière de performances des sites de documentation, d'optimisation du pipeline de construction des ressources et de facilité d'installation.

VuePress#

VuePress présente de nombreuses similitudes avec Docusaurus - tous deux sont fortement axés sur les sites Web axés sur le contenu et offrent des fonctions de documentation sur mesure dès le départ. Cependant, VuePress est propulsé par Vue, tandis que Docusaurus est propulsé par React. Si vous voulez une solution basée sur Vue, VuePress serait un choix décent.

Rester informé#

Il manque quelque chose ?#

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @docusaurus.

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