Docusaurus a été officiellement annoncé il y a plus de neuf mois comme moyen pour construire facilement des sites web de documentation open source. Depuis, il a accumulé plus de 8600 GitHub Stars, et est utilisé par de nombreux projets open source populaires tels que React Native, Babel, Jest, Reason et Prettier.
Il existe un dicton selon lequel le meilleur logiciel est en constante évolution, et le pire ne l'est pas. Si vous ne le savez pas, nous avons planifié et travaillé sur la prochaine version de Docusaurus 🎉.
Introduction
Tout a commencé avec cette issue RFC ouverte par Yangshun vers la fin du mois de juin 2018.
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
Voici quelques-uns des problèmes que je constate actuellement dans Docusaurus et comment nous pouvons les résoudre dans la version 2. Un certain nombre de ces idées ont été inspirées par VuePress et d'autres générateurs de sites statiques. Dans l'écosystème actuel des générateurs de sites statiques, ...
La plupart des améliorations suggérées sont mentionnées dans l'issue ; je fournirai des détails sur certains problèmes de Docusaurus 1 et sur la façon dont nous allons les résoudre dans Docusaurus 2.
Infrastructure
Contenu
Un site web Docusaurus 1 est en fait construit dans un tas de pages HTML statiques. Malgré l'utilisation de React, nous n'utilisions pas pleinement les fonctionnalités offertes par React, comme l'état des composants, qui permet de créer des pages dynamiques et interactives. React n'a été utilisé que comme moteur de template pour le contenu statique et l'interactivité doit être ajoutée par des balises de script et dangerouslySetInnerHTML😱.
En plus de cela, il n'y a pas de moyen facile de modifier la façon dont Docusaurus charge le contenu. Par exemple, l'ajout de préprocesseurs CSS tels que Sass et Less n'était pas pris en charge de manière native et impliquait de nombreux bidouillages de la part des utilisateurs pour ajouter des scripts personnalisés.
Pour Docusaurus 2, nous utiliserons webpack comme un bundler de module et nous changeons la façon dont nous servons le contenu. L'ajout de préprocesseurs CSS sera aussi simple que l'ajout d'un chargeur webpack. Au lieu d'un pur HTML statique, pendant la construction, nous allons créer une version de l'application rendue par le serveur et rendre le HTML correspondant. Un site Docusaurus sera essentiellement une application isomorphique/universelle. Cette approche est fortement inspirée par Gatsby.
Gestion des versions
Si vous utilisez Docusaurus depuis un certain temps, vous avez peut-être remarqué que Docusaurus crée des docs versionnés si et seulement si le contenu des docs est différent.
Par exemple, si nous avons un docs/hello.md :
---
id: hello
title: hello
---
Hello world !
Et nous créons la version 1.0.0, Docusaurus va créer versioned_docs/version-1.0.0/hello.md :
---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !
Cependant, si aucune modification n'est apportée au hello.md lors de la création de la v2.0.0, Docusaurus ne créera pas de docs versionnés pour ce document. En d'autres termes, versioned_docs/version-2.0.0/hello.md n'existera pas.
Cela peut être très déroutant pour les utilisateurs ; s'ils veulent modifier la documentation de la v2.0.0, ils doivent modifier versioned_docs/version-1.0.0/hello.md ou ajouter manuellement versioned_docs/version-2.0.0/hello.md. Cela pourrait potentiellement conduire à des bogues non désirés. Voici un véritable scénario dans Jest.
En plus, cela ajoute de la complexité au sein de la base de code car nous avons besoin d'un mécanisme de secours de version. Et pendant le temps de compilation, Docusaurus doit remplacer le lien vers la version correcte. C'est aussi la cause d'un bogue où renommer la documentation casse les liens dans les anciennes versions.
Pour Docusaurus 2, à chaque fois que nous créons une nouvelle version, nous prendrons plutôt un instantané de toutes les docs. Nous n'exigerons pas que le contenu d'un document ait changé. Il s'agit d'un compromis entre la complexité et la place occupée pour une meilleure expérience du développeur et de l'utilisateur. Nous utiliserons plus d'espace pour une meilleure séparation des préoccupations et une justesse garantie.
Traduction
Docusaurus propose une fonctionnalité de traduction facile en utilisant Crowdin. Les fichiers de documentation écrits en anglais sont envoyés à Crowdin pour une traduction par les utilisateurs au sein d’une communauté. Nous avons toujours supposé que l'Anglais est la langue par défaut, mais cela peut ne pas être le cas pour tous les utilisateurs. Nous avons vu beaucoup de projets open source non-anglais utilisant Docusaurus.
Pour Docusaurus 2, nous ne supposerons pas que l'anglais est la langue par défaut. Lorsqu'un utilisateur active l'internationalisation, il doit définir une langue par défaut dans siteConfig.js. Nous supposerons alors que tous les fichiers de docs sont écrits dans cette langue.
En outre, après avoir travaillé sur le MVP de Docusaurus 2, j'ai réalisé qu'il est possible de ne pas utiliser Crowdin pour les traductions. Ainsi, nous pourrions avoir besoin d'ajouter un workflow supplémentaire pour activer ce scénario. Cependant, nous recommanderons toujours fortement aux gens d'utiliser Crowdin pour une intégration plus facile.
Personnalisation
Mise en page
Dans l'état actuel des choses, Docusaurus est chargé de l'ensemble de la mise en page et du style, ce qui rend involontairement très difficile pour les utilisateurs de personnaliser l'apparence de leur site selon leurs souhaits.
Pour le Docusaurus 2, la mise en page et le style doivent être contrôlés par l'utilisateur. Docusaurus gérera la génération de contenu, le routage, la traduction et la gestion de version. Inspiré par create-react-app et VuePress, Docusaurus fournira toujours un thème par défaut, dont l'utilisateur pourra se défaire pour personnaliser davantage la mise en page et le style. Cela signifie qu'il est tout à fait possible pour l'utilisateur de modifier les méta HTML en utilisant React Helmet. Les thèmes communautaires sont également tout à fait possibles. Cette approche, qui permet aux utilisateurs de prendre en charge la mise en page et le style, est adoptée par la plupart des générateurs de sites statiques.
Markdown
Notre analyse Markdown est actuellement alimentée par Remarkable. Que se passe-t-il si l'utilisateur veut utiliser Markdown-it ou même MDX ? Et puis il y a une question de savoir quel colorateur syntaxique utiliser, (par ex : Prism ou Highlight.js). Nous devrions laisser ces choix ouverts à l'utilisateur.
Pour Docusaurus 2, les utilisateurs peuvent s'en débarrasser et choisir leur propre analyseur syntaxique de Markdown. Peu importe s'ils veulent utiliser un autre analyseur Markdown tel que Remark, ou même leur propre analyseur Markdown interne. En règle générale, l'utilisateur doit fournir un composant React, dans lequel nous fournirons un props enfant contenant la chaîne RAW de Markdown. Par défaut, nous utiliserons Remarkable pour l'analyseur Markdown et Highlight.js pour la coloration de la syntaxe. L'analyseur par défaut pourrait encore changer à l'avenir, car nous sommes toujours en train d'expérimenter différents analyseurs de Markdown.
Recherche
Notre fonctionnalité de recherche principale est basée sur Algolia. Les utilisateurs demandent à pouvoir utiliser différentes solutions de recherche, telles que lunrjs pour la recherche hors ligne.
J'aime personnellement Algolia et nous avons une grande expérience de travail avec eux. Ils sont très réactifs; nous pouvons facilement soumettre une pull request à Algolia car leur DocSearch est open source. Par exemple, j'ai récemment soumis cette PR qui permet à DocSearch de récupérer les langues alternatives dans le sitemap.
Pour Docusaurus 2, nous allons permettre aux utilisateurs de personnaliser la boîte de recherche. Les utilisateurs doivent simplement se détacher du thème par défaut et modifier l'interface utilisateur de recherche (un composant React). Cependant, nous utiliserons toujours Algolia dans le thème par défaut.
Stabilité
Les logiciels ne seront jamais parfaits, mais nous voulons que Docusaurus ne tombe pas en panne lorsque nous ajoutons de nouvelles fonctionnalités. Lorsque Docusaurus a été publié pour la première fois, il ne disposait pas de suites de tests automatisés solides. Par conséquent, de nombreuses régressions n'ont pas été détectées à temps. Bien que nous ayons récemment ajouté un grand nombre de tests, la couverture des tests est encore relativement faible.
Pour Docusaurus 2, nous ajoutons des tests au fur et à mesure du développement puisque nous optons pour une nouvelle réécriture. Je pense donc qu'il devrait être plus stable que jamais et qu'il devrait être plus difficile de casser des choses par rapport à Docusaurus 1.
Foire aux questions
Y aura-t-il des changements importants ?
Si vous avez lu l'article jusqu'ici, vous devriez être en mesure de remarquer qu'il y aura des changements importants. Bien que nous essayions de minimiser le nombre de changements brutaux et de le rendre rétrocompatible autant que possible, nous pensons que certains changements sont nécessaires. Cela est principalement dû au fait que Docusaurus 2 est une réécriture et ré-architecture majeure de la base de code.
La liste exacte des changements de rupture n'est pas encore totalement connue car le développement n'est pas finalisé à 100%. Cependant, une chose que je soulignerai est que nous allons déprécier beaucoup d'options dans siteConfig.js et nous prévoyons de le garder aussi léger que possible. Par exemple, le cleanUrl de siteConfig sera dépréciée car toutes les URL pour les sites Docusaurus 2 seront sans l'extension .html.
Notre objectif est que la plupart des sites soient en mesure de mettre à jour Docusaurus 2 sans trop de douleur. Nous inclurons également un guide de migration lorsque nous publierons Docusaurus 2. Le moment venu, n'hésitez pas à nous contacter sur Discord ou Twitter pour poser vos questions et obtenir de l'aide.
Quand est prévue la sortie de Docusaurus 2 ?
Pour l'instant, nous n'avons pas de date exacte prévue pour la parution. J'estime personnellement que nous pourrions être en mesure de publier une version alpha d'ici un à deux mois, mais il ne s'agit bien sûr que d'une estimation.
Une chose que j'aimerais partager est que, bien que Docusaurus fasse partie de Facebook Open Source et que la plupart des membres de l'équipe soient des employés de Facebook, le travail de maintenance et de développement est principalement effectué en dehors des heures de travail normales. Je suis actuellement un étudiant de dernière année de premier cycle à NTU Singapour, J'ai donc dû jongler entre faire mon cours, mon projet de dernière année et maintenir/développer Docusaurus. Cependant, cela ne veut pas dire que nous ne voulons pas améliorer Docusaurus. En fait, nous voulons le rendre aussi génial que possible.
Pour l'instant, le travail actuel de Docusaurus 2 est toujours hébergé dans un dépôt privé. Dans un avenir proche, nous le déplacerons dans le dépôt public. Lorsque ce moment arrivera, j'encourage tout le monde à s'y intéresser et à y contribuer d'une manière ou d'une autre. Avant cela, veuillez rester à l'écoute 😉!
Réflexions finales
Docusaurus a eu un impact important sur la communauté open source, comme en témoignent les nombreux projets populaires qui utilisent Docusaurus pour la documentation. Afin d'aller plus vite dans le futur, nous profitons de l'occasion pour corriger certains problèmes fondamentaux de Docusaurus 1 et nous nous efforçons de rendre Docusaurus meilleur pour tout le monde. En fait, on peut dire que le Docusaurus 2 n'est plus un simple projet ; les travaux ont commencé et, espérons-le, nous pourrons le voir se concrétiser dans un avenir proche.
La mission de Docusaurus a toujours été de vous faciliter l'accès à un site web avec de la documentation. Cette mission ne change pas avec Docusaurus 2.
Nous voulons faire également savoir aux personnes comme nous travaillons sur Docusaurus 2, nous serons moins susceptibles d'accepter de nouvelles fonctionnalités/changements majeurs sur Docusaurus 1.
Si vous utilisez Docusaurus, vous faites partie de notre communauté ; continuez à nous faire savoir comment nous pouvons améliorer Docusaurus pour vous. Si vous appréciez le travail que nous faisons, vous pouvez soutenir Docusaurus sur Open Collective.
Si vous parrainez notre travail sur Open Collective, nous vous offrons personnellement une aide pour la maintenance et la mise à jour du site web Docusaurus.
Enfin, si vous ne l'avez pas encore fait, cliquez sur le bouton star et watch sur GitHub, et suivez-nous sur Twitter.