Aller au contenu principal
Version: 2.0.0-beta.1 🚧

Introduction

⚡️ Docusaurus vous aidera à mettre en place un beau site de documentation en un rien de temps.

💸 La construction d'une pile de technologies personnalisées est coûteuse. Au lieu de cela, mettez l'accent sur votre contenu et écrivez simplement des fichiers Markdown.

💥 Vous en voulez plus ? Utilisez les fonctionnalités avancées comme la gestion des versions, i18n, la recherche et les personnalisations de thèmes.

💅 Consultez les les meilleurs sites Docusaurus pour vous inspirer et lisez quelques témoignages.

🧐 Docusaurus est un générateur de site statique. Il construit une application monopage avec une navigation rapide côté client, en exploitant toute la puissance de React pour rendre votre site interactif. Il fournit des fonctionnalités de documentation prêtes à l'emploi, mais peut être utilisé pour créer tout type de site (site web personnel, de produit, blog, pages de présentation de marketing, etc).

Docusaurus Slash Introduction

Procédure accélérée ⏱️#

Comprenez Docusaurus en 5 minutes en jouant !

Créez un nouveau site Docusaurus et suivez le très court tutoriel intégré.

Installez Node.js et créez un nouveau site Docusaurus :

npx @docusaurus/[email protected] init my-website classic

Démarrer le site :

cd my-website
npx docusaurus start

Ouvrez http://localhost:3000 et suivez le tutoriel.

astuce

Utilisez new.docusaurus.io pour tester immédiatement Docusaurus dans votre navigateur !

Ou lisez le tutoriel de 5 minutes en ligne.

Avertissement#

Docusaurus v2 est en bêta mais est déjà assez stable et largement utilisé.

Nous vous encourageons vivement à utiliser Docusaurus v2 plutôt que Docusaurus v1, car Docusaurus v1 sera bientôt déprécié.

Un nombre d'utilisateurs exploitent déjà Docusaurus v2 (tendances).

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

Utilisez Docusaurus v1 si :

  • ❌ Vous ne voulez pas de single-page-application (SPA)
  • ❌ Vous avez besoin de support pour IE11

Fonctionnalités#

Docusaurus est construit avec une haute considération pour l'expérience du développeur et du contributeur.

  • ⚛️ Développé avec 💚 et React
    • Étendre et personnaliser avec React
    • Contrôlez entièrement l'expérience de navigation de votre site en fournissant vos propres composants React
  • Pluggable
    • Créez votre site à partir d'un template de base, puis utilisez des fonctionnalités avancées et des plugins
    • Mettez vos plugins en open source pour les partager avec la communauté
  • ✂️ Expérience développeur
    • Commencez à écrire vos docs dès maintenant
    • 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, Vercel 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. Nous partageons avec vous nos meilleures pratiques pour vous aider à construire votre site documentaire correctement.

  • 🎯 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 - Traduisez votre site dans de multiples langues

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

Principes de conception#

  • Peu de choses à apprendre - Docusaurus devrait être facile à apprendre et à utiliser car l'API est assez petite. La plupart des choses seront toujours réalisables par les utilisateurs, même si cela leur prend plus de code et plus de temps à écrire. Il vaut mieux ne pas avoir d'abstractions que d'avoir des abstractions erronées, et nous ne voulons pas que les utilisateurs aient à bidouiller des abstractions erronées. Conférence obligatoire - Surface minimale de l'API.
  • Intuitif - Les utilisateurs ne se sentiront pas dépassés lorsqu'ils consulteront le répertoire d'un projet Docusaurus ou lorsqu'ils ajouteront de nouvelles fonctionnalités. Il doit être intuitif et facile à développer, en utilisant des approches qui leur sont familières.
  • Architecture en couches - Les séparations des préoccupations entre chaque couche de notre pile (contenu/thème/style) doivent être claires - bien abstraites et modulaires.
  • Des valeurs par défaut raisonnables - Les optimisations et les configurations courantes et populaires en matière de performances sont effectuées pour les utilisateurs, mais ceux-ci ont la possibilité de les remplacer.
  • Pas de verrou de vendeur - Les utilisateurs ne sont pas tenus d'utiliser les plugins par défaut ou CSS, bien qu'ils soient fortement encouragés. Certaines pièces de niveau inférieur au niveau de l'infra comme React Loadable, React Router ne peuvent pas être remplacées parce que nous faisons l'optimisation des performances par défaut sur elles. Mais pas ceux de niveau supérieur, comme le choix des moteurs Markdown, des frameworks CSS, de la méthodologie CSS, qui seront entièrement laissés aux utilisateurs.

Nous pensons qu'en tant que développeurs, savoir comment une bibliothèque fonctionne est utile pour nous permettre de mieux l'utiliser. C'est pourquoi nous nous efforçons d'expliquer l'architecture et les différentes composants de Docusaurus en espérant que les utilisateurs qui la lisent pourront mieux comprendre cet outil et être encore plus compétents dans son utilisation.

Comparaison avec d'autres outils#

Parmi tous les générateurs de sites statiques, Docusaurus se concentre sur les sites de documentation et dispose de nombreuses fonctionnalités prêtes à l'emploi.

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.

Dokz est un thème Gatsby pour construire un site web de documentation. Il est actuellement moins utilisé que Docusaurus.

Next.js#

Next.js est un autre framework hybride React très populaire. Il peut vous aider à construire un bon site web de documentation, mais il n'est pas orienté vers le domaine de la documentation, et il faudra beaucoup plus de travail pour mettre en œuvre ce que Docusaurus fournit tel quel.

Nextra est un générateur de site statique basé sur Next.js. Il est actuellement moins utilisé que Docusaurus.

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.

MkDocs#

MkDocs est un générateur de sites statiques Python populaire dont la proposition de valeur est similaire à celle de Docusaurus.

C'est une bonne option si vous n'avez pas besoin d'une application mono-page, et que vous ne prévoyez pas de tirer parti de React.

Material pour MkDocs est un beau thème.

Docsify#

Docsify permet de créer facilement un site web de documentation, mais n'est pas un générateur de site statique et n'est pas adapté au référencement.

GitBook#

GitBook a un design très épuré 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.

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 !