Aller au contenu principal
Version : Canary 🚧

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.

💅 Check the best Docusaurus sites for inspiration.

🧐 Docusaurus est un gĂ©nĂ©rateur de site statique. Il construit une application mono-page 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).

ProcĂ©dure accĂ©lĂ©rĂ©e ⏱​

DĂ©couvrez 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 create-docusaurus@latest my-website classic

DĂ©marrez le site :

cd my-website
npx docusaurus start

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

astuce

Utilisez docusaurus.new pour tester immĂ©diatement Docusaurus dans votre navigateur !

Ou lisez le tutoriel de 5 minutes en ligne.

Docusaurus : la documentation en toute simplicité​

Dans cette présentation à l'événement communautaire d'Algolia, l'équipe Open Source de Meta a partagé un bref aperçu de Docusaurus. Ils ont décrit comment démarrer avec le projet, activer les plugins, et mettre en place des fonctionnalités telles que la documentation et le blog.

Migration depuis la v1​

Docusaurus v2+ a été totalement réécrit à partir de Docusaurus v1, profitant d'une chaßne d'outils complÚtement modernisée. AprÚs la sortie officielle de la v2, nous vous encourageons vivement à utiliser Docusaurus v2+ plutÎt que Docusaurus v1, car Docusaurus v1 a été déprécié.

Beaucoup 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 (...vraiment ? IE a dĂ©jĂ  atteint sa fin de vie et n'est plus officiellement pris en charge)

Pour les utilisateurs de la v1 qui souhaitent passer Ă  la v2+, vous pouvez suivre nos guides de migration.

FonctionnalitĂ©s​

Docusaurus est construit en accordant une grande attention à l'expérience des développeurs et des contributeurs.

  • ⚛ DĂ©veloppĂ© avec 💚 et React :
    • Étendez et personnalisez 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 modĂšle 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
    • Un point d'entrĂ©e universel pour la configuration afin de faciliter la maintenance 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 : aidez vos utilisateurs Ă  trouver rapidement ce dont ils ont besoin et Ă  mieux comprendre vos produits. Nous partageons nos meilleures pratiques pour vous aider Ă  construire votre site documentaire correctement et bien.

  • 🎯 RĂ©fĂ©rencement convivial :
    • Les fichiers HTML sont gĂ©nĂ©rĂ©s statiquement pour chaque chemin possible.
    • 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 :
    • Écrivez des composants interactifs avec JSX et React qui sont incorporĂ©s dans le Markdown.
    • Partagez votre code dans des Ă©diteurs en ligne pour que vos utilisateurs aiment vos produits sur le champ.
  • 🔍 Recherche : Votre site complet est interrogeable.
  • đŸ’Ÿ Document versionnĂ© : permet de synchroniser la documentation avec les versions du projet.
  • 🌍 Internationalisation (i18n) : traduisez votre site dans de multiples langues.

Docusaurus v2+ est conçu pour ĂȘtre accessible avec bienveillance Ă  tous vos utilisateurs, et rapide comme l'Ă©clair.

  • âšĄïž Rapide comme l'Ă©clair. Docusaurus v2+ suit le modĂšle PRPL qui garantit un chargement rapide de votre contenu.
  • 🩖 Accessible. Une attention particuliĂšre Ă  l'accessibilitĂ©, en rendant votre site accessible Ă  tous les utilisateurs.

Principes de conception​

  • Peu Ă  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 infrastructures de base comme React Loadable et React Router ne peuvent pas ĂȘtre Ă©changĂ©es car nous faisons une optimisation de performance par dĂ©faut sur elles, mais pas des infrastructures de niveau supĂ©rieur. Le choix des moteurs Markdown, des frameworks CSS, de la mĂ©thodologie CSS et d'autres architectures sera entiĂšrement rĂ©servĂ© aux utilisateurs.

Nous croyons que, en tant que dĂ©veloppeurs, savoir comment une bibliothĂšque fonctionne nous aide Ă  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 v2+ ont été inspirés par les meilleures choses de Gatsby et c'est une excellente alternative.

Docz est un thÚme Gatsby pour construire des sites 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.

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 est un générateur de sites statiques Python populaire dont les propositions de valeur sont similaires à celles 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é l'installation.

Rspress​

Rspress is a fast static site generator based on Rspack, a Rust-based bundler. It supports content writing with MDX (Markdown with React components), integrated text search, multilingual support (i18n), and extensibility through plugins. Designed for creating elegant documentation and static websites, Rspress produces static HTML files that are easy to deploy.

Rspress and Docusaurus are quite similar. They both have their pros and cons. Rspress was created more recently and benefits from a modern infrastructure that enables faster site builds. Docusaurus stands out for its maturity, comprehensive feature set, flexibility, and strong community. It is also modernizing its infrastructure regularly to remain competitive in terms of performance.

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

Pour de nouvelles demandes de fonctionnalitĂ©s, vous pouvez crĂ©er un message sur notre tableau de nouvelles demandes de fonctionnalitĂ©s (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 !