Lignes directrices en direct — MDX et autres frameworks

Vous pouvez avoir le meilleur projet open source, mais s'il n'a pas de bonne documentation, il y a de fortes chances qu'il ne décolle jamais. Dans un bureau, une bonne documentation vous évitera de répondre plusieurs fois aux mêmes questions. La documentation garantit également que les gens peuvent comprendre le projet si des employés clés quittent l'entreprise ou si les rôles changent. Les lignes directrices en direct aident à assurer l'intégrité des données.

Si vous devez écrire un long texte, Markdown est une excellente alternative à HTML. Parfois, la syntaxe Markdown n'est pas suffisante. Dans ce cas, nous pouvons utiliser HTML à l'intérieur de celui-ci. Par exemple, des éléments personnalisés. Donc, si vous construisez un système de design avec des composants web natifs, il est facile de les inclure dans la documentation textuelle. Si vous utilisez React (ou tout autre framework JSX, comme Preact ou Vue), vous pouvez faire de même avec MDX.

Cet article est un large aperçu des outils pour écrire de la documentation et créer des lignes directrices. Tous les outils énumérés ici n'utilisent pas MDX, mais il est de plus en plus inclus dans les outils de documentation.

Qu'est-ce que MDX?

Le fichier .mdx a la même syntaxe que Markdown, mais permet d'importer des composants interactifs JSX et de les intégrer dans votre contenu. Le support des composants Vue est en alpha. Pour commencer à travailler avec MDX, il suffit d'installer « Create React App ». Il existe des plugins pour Next.js et Gatsby. La prochaine version de Docusaurus (version 2) aura également un support intégré.

Écriture de documentation avec Docusaurus

Docusaurus a été développé par Facebook. Ils l'utilisent dans chaque projet open source sauf React. En dehors de l'entreprise, il est utilisé par Redux, Prettier, Gulp et Babel.

Projets utilisant Docusaurus.

Docusaurus peut être utilisé pour écrire par n'importe qui de la documentation, pas seulement pour décrire le frontend. Il est construit sur React, mais il n'est pas nécessaire d'être familier avec celui-ci pour l'utiliser. Il prend vos fichiers Markdown, un soupçon de magie et une documentation bien structurée, formatée et lisible avec un beau design est prête.

Sur le site de Redux, vous pouvez consulter le modèle standard de Docusaurus

Les sites créés avec Docusaurus peuvent également inclure un blog basé sur Markdown. Pour la mise en évidence de la syntaxe, Prism.js est intégré dès le départ. Bien que Docusaurus soit relativement récent, il a été reconnu comme le meilleur outil de 2018 sur StackShare.

D'autres options pour créer du contenu

Docusaurus est spécialement conçu pour créer de la documentation. Bien sûr, il existe mille et une façons de réaliser un site - vous pouvez déployer votre propre solution dans n'importe quel langage, CMS ou utiliser un générateur de site statique.

Par exemple, la documentation de React, le système de design d'IBM, Apollo et Ghost CMS utilisent Gatsby - c'est un générateur de sites statiques souvent utilisé pour les blogs. Si vous travaillez avec Vue, VuePress sera une bonne option pour vous. Une autre option est d'utiliser un générateur écrit en Python - MkDocs. Il est open source et se configure avec un seul fichier YAML. GitBook est également une bonne option, mais il est gratuit uniquement pour les équipes ouvertes et non commerciales. Vous pouvez aussi simplement uploader des fichiers markdown en utilisant git et travailler avec eux sur Github.

Documentation des composants : Docz, Storybook et Styleguidist

Les directives, systèmes de design, bibliothèques de composants - peu importe comment vous les appelez, elles sont devenues très populaires dernièrement. L'émergence de frameworks de composants, tels que React et des outils mentionnés ici, a permis de transformer ces projets de vanité en outils utiles.

Storybook, Docz et Styleguidist font la même chose : ils affichent des éléments interactifs et documentent leur API. Un projet peut avoir des dizaines voire des centaines de composants - tous avec différents états et styles. Si vous souhaitez que les composants soient réutilisés, les gens doivent savoir qu'ils existent. Pour cela, il suffit de cataloguer les composants. Les directives offrent un aperçu facile à rechercher de tous vos composants. Cela aide à maintenir la cohérence visuelle et à éviter le travail répétitif.

Ces outils offrent un moyen pratique d'examiner différents états. Il peut être difficile de reproduire chaque état d'un composant dans le contexte d'une application réelle. Au lieu de cliquer dans une application réelle, il vaut mieux développer un composant séparé. Vous pouvez simuler des états difficiles à atteindre (comme l'état de chargement).

En plus de la démo visuelle des différents états et de la liste des propriétés, il est souvent nécessaire d'écrire une description générale du contenu — justifications de conception, cas d'utilisation ou description des résultats des tests utilisateurs. Markdown est très simple à apprendre — idéalement, les lignes directrices devraient être une ressource collaborative pour les designers et les développeurs. Docz, Styleguidist et Storybook offrent un moyen facile de mélanger Markdown avec des composants.

Docz

Actuellement, Docz fonctionne uniquement avec React, mais un travail actif est en cours pour prendre en charge Preact, Vue et les composants web. Docz est l'instrument le plus récent des trois, mais il a réussi à obtenir plus de 14 000 étoiles sur Github. Docz propose deux composants — <Playground> et < Props >. Ils sont importés et utilisés dans les fichiers .mdx.

import { Playground, Props } from "docz";
import Button from "..\/src\/Button";

## Vous pouvez _écrire_ **markdown**
### Vous pouvez importer et utiliser des composants

click

Vous pouvez envelopper vos propres composants React avec <Playground>, pour créer une alternative intégrée à CodePen ou CodeSandbox — c'est-à-dire vous voyez votre composant et vous pouvez l'éditer.

click

<Props> affichera toutes les propriétés disponibles pour ce composant React, les valeurs par défaut et si la propriété est requise.

<Props of={Button} />

Personnellement, je trouve que cette approche basée sur MDX est la plus facile à comprendre et la plus simple à utiliser.

Si vous êtes fan du générateur de sites statiques Gatsby, Docz offre une excellente intégration.

Styleguidist

Comme dans Docz, les exemples sont écrits en utilisant la syntaxe Markdown. Styleguidist utilise des blocs de code Markdown (triple citation) dans des fichiers ordinaires .md plutôt que dans MDX.

```js
 console.log('clicked')}>Push Me

Les blocs de code dans Markdown montrent généralement juste le code. Avec Styleguidist, tout bloc de code avec le tag de langue js, jsx ou javascript s'affichera comme un composant React. Comme dans Docz, le code est modifiable — vous pouvez changer les propriétés et voir instantanément le résultat.

Styleguidist créera automatiquement un tableau de propriétés à partir des déclarations PropTypes, Flow ou Typescript.

Styleguidist prend actuellement en charge React et Vue.

Storybook

Storybook se positionne comme un « environnement de développement UI de composants ». Au lieu d'écrire des exemples de composants dans des fichiers Markdown ou MDX, vous écrivez de l'historique dans des fichiers Javascript. Historique documentent l'état spécifique d'un composant. Par exemple, un composant peut avoir des histoires pour l'état de chargement et l'état désactivé (désactivé).

storiesOf('Button', module)
  .add('désactivé', () => (
    <Button désactivé>lorem ipsum<\/Button>
  ))

Storybook est beaucoup plus complexe que Styleguidist et Docz. Cependant, c'est l'option la plus populaire, le projet ayant plus de 36 000 étoiles sur Github. C'est un projet open source, avec 657 contributeurs et maintenu par des employés permanents. Il est utilisé par Airbnb, Algolia, Atlassian, Lyft et Salesforce. Storybook prend en charge plus de frameworks que ses concurrents : React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte et HTML standard.

La prochaine version introduira des fonctionnalités de Docz et intégrera MDX.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

De nouvelles fonctionnalités de Storybook apparaîtront progressivement au cours des prochains mois et il semble que ce sera un grand pas en avant.

Résultats

Les avantages de la bibliothèque de modèles sont célébrés dans des millions d'articles sur Medium. Lorsqu'ils sont bien réalisés, ils facilitent la création de produits connexes et le maintien de l'identité. Bien sûr, aucun de ces outils ne pourra magique ment créer un système de design. Cela nécessite une conception minutieuse et du CSS. Mais quand vient le temps de rendre le système de design accessible à toute l'entreprise, Docz, Storybook et Styleguidist sont d'excellentes options.

Du traducteur. C'est ma première expérience sur Habr. Si vous trouvez des inexactitudes ou avez des suggestions pour améliorer l'article, écrivez-moi en privé.

Source : habr.com