{"id":34791,"date":"2019-10-31T22:00:25","date_gmt":"2019-10-31T19:00:25","guid":{"rendered":"https:\/\/prohoster.info\/blog\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki\/"},"modified":"2019-10-31T22:00:25","modified_gmt":"2019-10-31T19:00:25","slug":"zhivye-gajdlajny-mdx-i-drugie-frejmvorki","status":"publish","type":"post","link":"https:\/\/prohoster.info\/fr\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Lignes directrices en direct \u2014 MDX et autres frameworks","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

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\u00e9colle jamais. Dans un bureau, une bonne documentation vous \u00e9vitera de r\u00e9pondre plusieurs fois aux m\u00eames questions. La documentation garantit \u00e9galement que les gens peuvent comprendre le projet si des employ\u00e9s cl\u00e9s quittent l'entreprise ou si les r\u00f4les changent. Les lignes directrices en direct aident \u00e0 assurer l'int\u00e9grit\u00e9 des donn\u00e9es. <\/p>\n

<\/a><\/noindex><\/p>\n

Si vous devez \u00e9crire un long texte, Markdown est une excellente alternative \u00e0 HTML. Parfois, la syntaxe Markdown n'est pas suffisante. Dans ce cas, nous pouvons utiliser HTML \u00e0 l'int\u00e9rieur de celui-ci. Par exemple, des \u00e9l\u00e9ments personnalis\u00e9s. Donc, si vous construisez un syst\u00e8me 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\u00eame avec MDX. <\/p>\n

<\/p>\n

Cet article est un large aper\u00e7u des outils pour \u00e9crire de la documentation et cr\u00e9er des lignes directrices. Tous les outils \u00e9num\u00e9r\u00e9s ici n'utilisent pas MDX, mais il est de plus en plus inclus dans les outils de documentation.<\/p>\n

<\/p>\n

Qu'est-ce que MDX?<\/h2>\n

<\/p>\n

Le fichier .mdx<\/code> a le m\u00eame syntagme que Markdown, mais permet d'importer des composants interactifs JSX et de les int\u00e9grer dans votre contenu. Le support des composants Vue est en version alpha. Pour commencer \u00e0 travailler avec MDX, il vous suffit d'installer \u00ab Create React App \u00bb. Il existe des plugins pour Next.js et Gatsby. La prochaine version de Docusaurus (version 2) aura \u00e9galement un support int\u00e9gr\u00e9.<\/p>\n

<\/p>\n

\u00c9criture de documentation avec Docusaurus<\/h2>\n

<\/p>\n

Docusaurus a \u00e9t\u00e9 d\u00e9velopp\u00e9 par Facebook. Ils l'utilisent dans chaque projet open source sauf React. En dehors de l'entreprise, il est utilis\u00e9 par Redux, Prettier, Gulp et Babel.<\/p>\n

<\/p>\n

\"LignesProjets utilisant Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus peut \u00eatre utilis\u00e9 pour \u00e9crire par n'importe qui<\/em> de la documentation, pas seulement pour d\u00e9crire le frontend. Il est construit sur React, mais il n'est pas n\u00e9cessaire d'\u00eatre familier avec celui-ci pour l'utiliser. Il prend vos fichiers Markdown, un soup\u00e7on de magie et une documentation bien structur\u00e9e, format\u00e9e et lisible avec un beau design est pr\u00eate. <\/p>\n

<\/p>\n

\"Lignes
\nSur le site de Redux, vous pouvez consulter le mod\u00e8le standard de Docusaurus<\/em><\/p>\n

<\/p>\n

Les sites cr\u00e9\u00e9s avec Docusaurus peuvent \u00e9galement inclure un blog bas\u00e9 sur Markdown. Pour la mise en \u00e9vidence de la syntaxe, Prism.js est int\u00e9gr\u00e9 d\u00e8s le d\u00e9part. Bien que Docusaurus soit relativement r\u00e9cent, il a \u00e9t\u00e9 reconnu comme le meilleur outil de 2018 sur StackShare. <\/p>\n

<\/p>\n

D'autres options pour cr\u00e9er du contenu<\/h2>\n

<\/p>\n

Docusaurus est sp\u00e9cialement con\u00e7u pour cr\u00e9er de la documentation. Bien s\u00fbr, il existe mille et une fa\u00e7ons de r\u00e9aliser un site - vous pouvez d\u00e9ployer votre propre solution dans n'importe quel langage, CMS ou utiliser un g\u00e9n\u00e9rateur de site statique.<\/p>\n

<\/p>\n

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

<\/p>\n

Documentation des composants : Docz, Storybook et Styleguidist<\/h2>\n

<\/p>\n

Les directives, syst\u00e8mes de design, biblioth\u00e8ques de composants - peu importe comment vous les appelez, elles sont devenues tr\u00e8s populaires derni\u00e8rement. L'\u00e9mergence de frameworks de composants, tels que React et des outils mentionn\u00e9s ici, a permis de transformer ces projets de vanit\u00e9 en outils utiles. <\/p>\n

<\/p>\n

Storybook, Docz et Styleguidist font la m\u00eame chose : ils affichent des \u00e9l\u00e9ments interactifs et documentent leur API. Un projet peut avoir des dizaines voire des centaines de composants - tous avec diff\u00e9rents \u00e9tats et styles. Si vous souhaitez que les composants soient r\u00e9utilis\u00e9s, les gens doivent savoir qu'ils existent. Pour cela, il suffit de cataloguer les composants. Les directives offrent un aper\u00e7u facile \u00e0 rechercher de tous vos composants. Cela aide \u00e0 maintenir la coh\u00e9rence visuelle et \u00e0 \u00e9viter le travail r\u00e9p\u00e9titif.<\/p>\n

<\/p>\n

Ces outils offrent un moyen pratique d'examiner diff\u00e9rents \u00e9tats. Il peut \u00eatre difficile de reproduire chaque \u00e9tat d'un composant dans le contexte d'une application r\u00e9elle. Au lieu de cliquer dans une application r\u00e9elle, il vaut mieux d\u00e9velopper un composant s\u00e9par\u00e9. Vous pouvez simuler des \u00e9tats difficiles \u00e0 atteindre (comme l'\u00e9tat de chargement). <\/p>\n

<\/p>\n

En plus de la d\u00e9mo visuelle des diff\u00e9rents \u00e9tats et de la liste des propri\u00e9t\u00e9s, il est souvent n\u00e9cessaire d'\u00e9crire une description g\u00e9n\u00e9rale du contenu \u2014 justifications de conception, cas d'utilisation ou description des r\u00e9sultats des tests utilisateurs. Markdown est tr\u00e8s simple \u00e0 apprendre \u2014 id\u00e9alement, les lignes directrices devraient \u00eatre une ressource collaborative pour les designers et les d\u00e9veloppeurs. Docz, Styleguidist et Storybook offrent un moyen facile de m\u00e9langer Markdown avec des composants.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

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\u00e9cent des trois, mais il a r\u00e9ussi \u00e0 obtenir plus de 14 000 \u00e9toiles sur Github. Docz propose deux composants \u2014 <Playground><\/code> et < Props ><\/code>. Ils sont import\u00e9s et utilis\u00e9s dans les fichiers .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Vous pouvez _\u00e9crire_ **markdown**\n### Vous pouvez importer et utiliser des composants\n\n