Nous sommes très heureux de vous présenter Docusaurus pour vous aider à gérer un ou plusieurs sites web open source.
Nous avons créé Docusaurus pour les raisons suivantes :
- Mettre l'accent sur la rédaction d'une bonne documentation au lieu de s'inquiéter de l'infrastructure d'un site Web.
- Fournir des fonctionnalités dont bon nombre de nos sites web open source ont besoin comme le support des blogs, la recherche et la mise en page.
- Faciliter l'envoi de mises à jour, de nouvelles fonctionnalités et de corrections de bogues pour tout le monde en même temps.
- Et enfin, donner une apparence et une sensation cohérentes à tous nos projets open source.
Docusaurus est un outil conçu pour permettre aux équipes de publier facilement des sites Web de documentation sans avoir à se soucier de l'infrastructure et des détails de conception. En gros, tout ce qu'un utilisateur doit fournir, ce sont des fichiers de documentation écrits en Markdown, la personnalisation d'une page d'accueil déjà fournie, écrite en React, et quelques modifications de configuration. Docusaurus s'occupe du reste en fournissant des styles par défaut, le formatage du site et une navigation simple dans les documents. La mise en route est facile, puisque les utilisateurs peuvent l'installer à l'aide de npm ou yarn via un simple script d'initialisation qui crée un site web d'exemple fonctionnel dès le départ.
Docusaurus offre également des fonctionnalités de base pour les sites Web et la documentation, notamment la prise en charge des blogs, l'internationalisation, la recherche et la gestion de version. Bien que certains projets puissent ne nécessiter aucune de ces fonctionnalités, leur activation est généralement une question de mise à jour des options de configuration au lieu de devoir ajouter l'infrastructure dès le départ. Au fur et à mesure que de nouvelles fonctionnalités sont ajoutées à Docusaurus, les utilisateurs peuvent facilement mettre à jour la dernière version. Pour ce faire, il suffit d'exécuter npm ou yarn update et de mettre à jour les options de configuration. Les utilisateurs ou les équipes n'auront plus besoin de retravailler manuellement l'ensemble de leur infrastructure de site Web chaque fois qu'une nouvelle fonctionnalité est ajoutée.
La naissance de docusaurus
Lorsque Facebook a lancé son programme open source, de nombreuses équipes ont mis en place un site web personnalisé pour chacun de leurs projets open source. Cette approche a posé des problèmes lorsqu'il a été demandé à l'équipe du programme open source d'aider les équipes de projet pour améliorer leur documentation. Chaque site étant unique, l'ajout d'une infrastructure de base telle qu'un blog, une navigation cohérente, une recherche, etc. est devenu un véritable défi.
L'équipe open source a tenté d'atténuer ce problème en proposant un modèle standard, basé sur Jekyll, qui pourrait être utilisé comme point de départ pour un site web de projet. Nous avons demandé à nos nouveaux projets de copier manuellement la source de notre modèle dans leur dépôt, de rédiger leur documentation et de la publier. Cette approche de modèle a été adoptée par la plupart des projets open source lancés ; certains projets existants ont même converti leurs implémentations de sites web personnalisés vers le nouveau modèle également.
Le problème de l'approche consistant à "copier le modèle dans votre dépôt" est que, même si la formule est cohérente, il devient impossible d'effectuer des mises à jour dans toute une série de projets utilisant déjà le modèle. Ceci est dû au fait que nous avons perdu le contrôle du modèle après qu'un projet l'ait copié dans son dépôt. Les projets étaient libres de modifier le modèle comme ils le souhaitaient et d'y appliquer leurs propres fonctionnalités spécifiques de projet. Ainsi, bien que les projets partagent la même formule de génération de sites, ils ont maintenant suffisamment divergé pour ne plus pouvoir profiter des nouvelles fonctionnalités que nous avons ajoutées au modèle au fil du temps. Il n'y avait aucun moyen facile de demander à tous les projets en cours de "copier" une nouvelle version du modèle, car cela risquait de casser leur site existant ou de supprimer des fonctionnalités qu'ils avaient ajoutées eux-mêmes. Au lieu de cela, nous devions appliquer les mises à jour manuellement à chaque projet, un par un. Cela est devenu très problématique lorsque les projets ont commencé à demander à notre équipe une prise en charge de l'internationalisation au sein du modèle, ce qui nécessitait des changements de bas niveau dans la façon dont le modèle était structuré et généré.
Nous avons donc commencé à réfléchir à ce que nous pourrions faire pour atténuer le défi que représente la mise à jour et la cohérence des sites dans l'ensemble de notre portefeuille. Nous voulions également que plusieurs projets partagent le même logiciel de génération de site. Nous voulions qu'ils commencent avec le même modèle, tout en ayant la possibilité de personnaliser et d'adapter le thème de leur site en fonction de leurs besoins. Ils doivent être en mesure d'étendre et de personnaliser leur site, mais lorsque nous mettons à jour l'infrastructure sous-jacente avec des correctifs et des fonctionnalités, le projet doit pouvoir être mis à jour simplement et sans aucune altération.
Docusaurus est né !
Chez Facebook, Docusaurus nous permet de mettre rapidement en place différents projets avec des sites de documentation, notamment pour les équipes qui n'ont pas beaucoup d'expérience en matière de développement web ou qui souhaitent avant tout un site de base pour présenter leur projet. Docusaurus prend déjà en charge les sites ayant besoin de fonctionnalités plus avancées comme l'internationalisation pour Jest et la gestion de version pour React Native. Lorsque les différents projets demandent de nouvelles fonctionnalités pour leurs sites, celles-ci sont ajoutées à Docusaurus et fournies simultanément à tous les projets ! Au final, cela permet de réduire considérablement le travail nécessaire à la maintenance de différents sites pour différents projets. Nos équipes peuvent se concentrer sur la santé de leurs projets en consacrant plus de temps à l'ajout de fonctionnalités, à la correction des bogues et à la rédaction de la documentation.
Mise en route et fonctionnement
Nous voulions avant tout que les sites utilisant Docusaurus soient simples à utiliser. Avec une commande d'installation et quelques configurations simples, vous pouvez réellement avoir un site web fonctionnel par défaut.
Lorsque vous exécutez docusaurus-init, vous verrez une structure similaire à :
root-of-repo
├── docs-examples-from-docusaurus
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ ├── example-doc4.md
│ └── example-doc5.md
├── website
│ ├── blog-examples-from-docusaurus
│ │ ├── 2016-03-11-blog-post.md
│ │ └── 2017-04-10-blog-post-two.md
│ ├── core
│ │ └── Footer.js
│ ├── node_modules
│ ├── package.json
│ ├── pages
│ ├── sidebars.json
│ ├── siteConfig.js
│ └── static
À l'exception de node_modules et package.json, tous les répertoires et fichiers que vous voyez sont ceux dans lesquels vous personnalisez et ajoutez du contenu à votre site Web reposant sur Docusaurus. Le dossier docs est l'endroit où vous ajoutez votre Markdown qui représente votre documentation; le dossier blog est l'endroit où vous ajoutez votre Markdown pour vos articles du blog; siteConfig.js est l'endroit où vous faites la plupart des personnalisations pour votre site; sidebars.json est l'endroit où vous maintenez la disposition et le contenu de la barre latérale pour votre documentation; le dossier pages est l'endroit où vous ajoutez des personnalisations de pages pour votre site; le dossier static est l'endroit où vont toutes vos ressources statiques (par ex, feuilles de style CSS et images); et le dossier core est l'endroit où vous pouvez personnaliser les composants de base du site, dans ce cas le pied de page.
Comment fonctionne Docusaurus ?
Docusaurus est écrit principalement en JavaScript et React, en remplacement de Jekyll que nous utilisions dans l'ancien modèle. Nous utilisons Remarkable pour notre rendu Markdown et highlight.js pour notre coloration syntaxique des blocs de code. Le cœur des fonctionnalités de Docusaurus se trouve dans le répertoire lib du dépôt de Docusaurus. La structure générale ressemble à :
root-of-Docusaurus
├── lib
│ ├── core
│ ├── server
│ │ ├── generate.js
│ │ ├── server.js
│ │ └── ...et d'autres fichiers
│ ├── static
│ ├── build-files.js
│ ├── copy-examples.js
│ ├── generate-feed.js
│ ├── publish-gh-pages.js
│ ├── rename-version.js
│ ├── start-server.js
│ ├── versions.js
│ └── write-translations.js
Les fichiers clés ici sont build-files.js et start-server.js. Il existe de nombreuses similitudes entre ces deux fichiers : build-files.js est utilisé pour construire les artefacts physiques destinés à être servis par un serveur web externe. start-server.js est utilisé pour exécuter le serveur Docusaurus et tester localement votre site. Tous deux suivent le processus général suivant, qui consiste à prendre l'ensemble du Markdown et de la configuration pour créer un site web exécutable :
- Traite les paramètres de votre site web dans
siteConfig.js - Lit les métadonnées du document qui existent dans tous les fichiers Markdown de votre répertoire docs.
- Crée une table des matières pour vos documents à partir des ID extraits des métadonnées.
- Convertit le Markdown en HTML, y compris en remplaçant les liens.
- Ces fichiers seront placés dans un répertoire build/docs du site compilé, et toutes les versions traduites seront placées dans un dossier spécifique de la langue dans le dossier build/docs.
- Répéte les étapes 1 à 3 pour les articles du blog.
- Le fichier du blog ira dans un répertoire build/blog du site compilé.
- Lit le fichier main.css et concatène tout le css défini par l'utilisateur dans le fichier css maître qui se trouvera dans le répertoire build/css du site compilé.
- Copie les images dans un répertoire build/img du site compilé.
- Prend toutes les pages personnalisées qui ont été ajoutées au dossier de pages du site et compile/copie celles dans le répertoire de compilation racine du site compilé. Toutes les versions traduites seront placées dans un dossier spécifique à la langue dans build.
- Crée des fichiers CNAME et sitemap.xml et les ajoute à build.
Notez que ce processus ne prend pas totalement en compte le fonctionnement des traductions ou des versions. Les détails sous-jacents de ces fonctionnalités seront conservés pour de futurs articles de blog.
La structure finale de votre site compilé ressemblera à ceci :
build
├── website
│ ├── CNAME
│ ├── blog
│ ├── css
│ ├── docs
│ ├── en
│ ├── help.html # page personnalisée
│ ├── img
│ ├── index.html # page d'accueil
│ ├── sitemap.xml
│ └── users.html # page personnalisée
Communauté
Nous accueillons vos contributions pour Docusaurus, que vous souhaitiez l'utiliser pour votre propre site, que vous vouliez contribuer au noyau de Docusaurus ou que vous ayez simplement des questions. Suivez-nous sur GitHub et Twitter.
Remerciements
Docusaurus n'existerait pas sans le travail du reste de l'équipe centrale de Docusaurus : Eric Nakagawa, Hector Ramos, Eric Vicenti et Frank Li - un ancien stagiaire de Facebook qui a mis en œuvre la technologie et les fonctionnalités de base.
Un grand merci également à nos premiers adoptants de Docusaurus :
Sans leur dévouement pour créer ou migrer leurs sites web vers la plateforme, nous n'aurions pas été dans la position où nous sommes aujourd'hui.