Aller au contenu principal
Version : 2.4.0

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 meilleurs sites Docusaurus pour trouver de l'inspiration et lire des testimonials.

🧐 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, produit, blog, pages d'accueil 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 embarqué.

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

npx [email protected] my-website classic

Démarrez le site :

cd my-website
npx docusaurus start

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

astuce

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

Ou lisez le tutoriel de 5 minutes en ligne.

Docusaurus : la documentation en toute simplicité​

Dans cette présentation lors de l'Algolia Community Event, l'équipe Meta Open Source a partagé une brève présentation 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 publication officielle de la v2, nous vous encourageons fortement à utiliser Docusaurus v2 plutôt que Docusaurus v1, car Docusaurus v1 est désormais obsolète.

Beaucoup d'utilisateurs utilisent déjà Docusaurus v2 (trends).

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 (...n'est-ce pas ? IE a déjà atteint sa fin de vie et n'est plus officiellement pris en charge)

For existing v1 users that are seeking to upgrade to v2, you can follow our migration guide.

Features​

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

  • ⚛️ Built with 💚 and 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é
  • ✂️ Developer experience:
    • 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.

  • 🎯 SEO friendly:
    • 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.
  • 📝 Powered by 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.
  • 🔍 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 2 est conçu pour être accessible avec bienveillance à tous vos utilisateurs, et rapide comme l'éclair.

  • ⚡️ Lightning-fast. Docusaurus 2 follows the PRPL Pattern that makes sure your content loads blazing fast.
  • 🦖 Accessible. Une attention particulière à l'accessibilité, en rendant votre site accessible à tous les utilisateurs.

Design principles​

  • Little to learn. 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. Mandatory talk—Minimal API Surface Area.
  • Intuitive. 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.
  • Layered architecture. Les séparations des préoccupations entre chaque couche de notre pile (contenu/thème/style) doivent être claires - bien abstraites et modulaires.
  • Sensible defaults. 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.
  • No vendor lock-in. 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.

Comparison with other tools​

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 is packed with a lot of features, has a rich ecosystem of plugins, and is capable of doing everything that Docusaurus does. 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.

Docz is a Gatsby theme to build documentation websites. Il est actuellement moins utilisé que Docusaurus.

Next.js​

Next.js is another very popular hybrid React framework. 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 is an opinionated static site generator built on top of Next.js. Il est actuellement moins utilisé que Docusaurus.

VuePress​

VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. 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 is a popular Python static site generator with value propositions similar to 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 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. 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. You may read about Redux's switch to Docusaurus here.

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

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

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

Staying informed​

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.

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. É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 !