Le changement est inévitable, et de temps en temps, il arrive. Au cours des dernières années, des changements nous ont été imposés, des changements sur lesquels nous n’avions aucun contrôle direct. Mais chez Layer0/Edgio, le changement récent est l’un de nos propres faits, un changement qui était très nécessaire : une réécriture complète et une refonte de la documentation Edgio.
Cette révision devait être fondamentale et contrôlable. La vérité est que nous voulions prendre les choses en main comme nous ne l’avons jamais fait auparavant. Et donc, fortement inspirés par les docs bêta de React, nous nous sommes lancés sur les épaules des géants en créant une instance du repo de base et en l’affinant pour notre cas d’utilisation spécifique.
Tout d’abord
La première étape était le canal de discorde Reactiflux. Pour le dire simplement, la communauté a aidé à identifier le repo de documentation bêta de React.
Le REACT beta repo comme une longueur d’avance
Nous avons passé quelques jours à étudier comment le site bêta de React Docs avait été construit, quelles technologies il utilise et comment nous pouvons exploiter et construire au-dessus de cette pile pour répondre à nos besoins spécifiques. Notre intuition sur MDX et Next.js était juste et nous nous sommes retrouvés avec une longueur d’avance.
Technologies
Voici quelques-unes des principales technologies utilisées:
- MDX : Markdown fonctionnel avec composants React intégrés
- Next.js : framework React
- Webpack : module bundler
- Composants stylisés : style
- Algolia : recherche
- Prism : coloration syntaxique du code
MDX : MDX est une forme étendue de Markdown pour l’ère des composants. Il rend le markdown fonctionnel en vous permettant d’intégrer JSX dans n’importe quel document markdown, faisant passer la création de contenu avec markdown à un nouveau niveau.
Nous savions déjà ce qu’était MDX et à quel point il pouvait être puissant grâce à des articles comme MDX, l’ingrédient secret et la documentation frontale, les guides de style et l’essor de MDX. Cela a ouvert la voie à certains des composants personnalisés que nous avons créés.
Next.js : jumeler MDX avec Next.js n’est pas quelque chose de nouveau, donc le premier instinct a été de lire la documentation officielle ou ce billet de blog. Il y a quelques approches pour obtenir markdown dans les pages Next.js comme avoir un document markdown local et le transformer en HTML en utilisant des paquets comme remark et remark-html dans l’un des getStaticProps, getStaticPaths, ou getServerSideProps
Une autre approche est de définir un fichier `.md` ou `.mdx` directement comme pages Next.js avec le paquet @next/mdx, ou si vous aimez traiter les choses de niveau inférieur, suivez l’approche de l’équipe de React et DIY.
Webpack : next.config.js (ou next.config.mjs) est utilisé par le serveur Next.js et les phases de compilation. C’est là que vous pouvez configurer Next.js pour des cas d’utilisation avancés, comme laisser markdown lire les extensions de fichier `.mdx` dans le répertoire pages et les charger en tant que pages Next.js.
Webpack utilise des chargeurs pour prétraiter les fichiers. L’un des cas d’utilisation les plus courants est le transpilage et l’un de ces paquets communs est babel-loader (charge le code ES2015+ et transpile vers ES5 en utilisant Babel). Pour charger des fichiers `.mdx` avec Webpack dans Next.js, @mdx-js/loader est utilisé.
Le riche écosystème de plugins Remark/Rehype peut être sollicité par @mdx-js/loader pour une transformation fine du markdown en html.
Composants stylisés : bien qu’il existe une pléthore de façons d’écrire CSS dans Next.js, nous avons choisi des composants stylisés. Avec Styled Components, nous sommes en mesure de créer des styles de composants de manière plus colocalisée, modulaire, couplée et moins intrusive. Apprenez à utiliser des composants stylisés dans React ou explorez les composants stylisés Happy Path pour plus d’informations sur les composants stylisés.
Algolia : nous avons mis à niveau vers la dernière version de DocSearch v3 qui est construite sur Algolia Autocomplete, offrant des améliorations à l’accessibilité et à la réactivité pour une expérience plus fluide sur les ordinateurs de bureau et les appareils mobiles. Couplé avec cela est le Crawler Algolia pour extraire les informations les plus pertinentes lors de l’exécution de votre recherche.
Prism : Prism est le surligneur de syntaxe de code bien testé et fiable. Il n’est pas seulement plus facile de démarrer, il dispose également d’un riche écosystème de plugins, et est extensible avec des valeurs par défaut raisonnables pour des opérations comme le thème.
Fonctionnalités
Alors que la refonte comporte une modification essentiellement esthétique à la valeur nominale, il existe d’autres fonctionnalités telles que :
Une nouvelle page d’accueil avec des détails importants
Commencez avec les quatre piliers de la plate-forme Layer0/Edgio et construisez votre chemin vers le haut et dans plus de fonctionnalités Layer0/Edgio a à offrir.
Thème
Il suffit de cliquer sur un bouton pour passer d’un thème à l’autre. Passez du mode clair au mode sombre ou vice-versa ou laissez votre système d’exploitation décider.
Navigation améliorée
Les deux modes de navigation principaux, menu (à gauche) et table des matières (à droite), ont été repensés pour améliorer la navigation et la numérisation. Un nouveau contrôle de pagination (en bas) vous aide à savoir quel guide est le prochain et lequel vient avant.
Blocs de code améliorés
Avec PrismJS, la mise en évidence de la syntaxe et la personnalisation sont complètement simples.
Recherche améliorée
La recherche Algolia a été mise à niveau vers la v3, ce qui nous donne beaucoup plus de contrôle sur le contenu indexé pour les résultats. Cela fonctionne également sur les appareils mobiles.
Mais attendez, il y a plus
Le repo React beta Docs a beaucoup de choses à faire pour elle, et nous avons pu tirer parti de la puissance de l’open-source ici. Il y a certaines choses que nous obtenons presque hors de la boîte, comme table des matières, docs pagination, fil d’Ariane, SEO etc Certains d’entre eux ont été modifiés pour mieux servir notre contexte, et d’autres encore sont en cours d’exploration.
Contribution
Pour nous, cette nouvelle documentation est un pas dans la bonne direction et le début d’un nouveau départ. Nous souhaitons que vous nous rejoigniez dans cette aventure, alors que nous continuons à vous aider à rendre vos sites Web plus rapides et plus sûrs sans compromettre l’expérience des développeurs. Le code source pour les documents de développement Layer0 est dans un dépôt ouvert sur GitHub et nous accueillons les commentaires et les demandes de pull. Si vous avez trouvé une faute de frappe ou une meilleure façon d’expliquer quelque chose, veuillez soumettre une demande de tirage ou déposer un problème! Consultez également nos directives de contribution.
