{"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\/it\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Linee guida in tempo reale \u2014 MDX e altri framework","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Puoi avere il miglior progetto open source, ma se non ha una buona documentazione, \u00e8 probabile che non decolli mai. Una buona documentazione in ufficio ti permetter\u00e0 di non rispondere alle stesse domande. La documentazione garantisce anche che le persone possano comprendere il progetto se dipendenti chiave lasciano l'azienda o cambiano ruolo. Le linee guida dinamiche aiutano a garantire l'integrit\u00e0 dei dati. <\/p>\n

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

Se hai bisogno di scrivere un testo lungo, Markdown \u00e8 un'ottima alternativa all'HTML. A volte la sintassi di Markdown non \u00e8 sufficiente. In questo caso, possiamo usare l'HTML al suo interno. Ad esempio, elementi personalizzati. Quindi, se stai costruendo un sistema di design con componenti web nativi, \u00e8 facile includerli nella documentazione testuale. Se stai usando React (o qualsiasi altro framework JSX, come Preact o Vue), puoi fare lo stesso usando MDX. <\/p>\n

<\/p>\n

Questo articolo \u00e8 una panoramica ampia degli strumenti per la scrittura di documentazione e la creazione di linee guida. Non tutti gli strumenti elencati qui utilizzano MDX, ma questo viene incluso sempre pi\u00f9 spesso negli strumenti di documentazione.<\/p>\n

<\/p>\n

Che cos'\u00e8 MDX?<\/h2>\n

<\/p>\n

File .mdx<\/code> \u0438\u043c\u0435\u0435\u0442 \u0442\u043e\u0442 \u0436\u0435 \u0441\u0438\u043d\u0442\u0430\u043a\u0441\u0438\u0441 \u0447\u0442\u043e \u0438 Markdown, \u043d\u043e \u043f\u043e\u0437\u0432\u043e\u043b\u044f\u0435\u0442 \u0438\u043c\u043f\u043e\u0440\u0442\u0438\u0440\u043e\u0432\u0430\u0442\u044c \u0438\u043d\u0442\u0435\u0440\u0430\u043a\u0442\u0438\u0432\u043d\u044b\u0435 \u043a\u043e\u043c\u043f\u043e\u043d\u0435\u043d\u0442\u044b JSX \u0438 \u0432\u0441\u0442\u0440\u0430\u0438\u0432\u0430\u0442\u044c \u0438\u0445 \u0432 \u0432\u0430\u0448 \u043a\u043e\u043d\u0442\u0435\u043d\u0442. \u041f\u043e\u0434\u0434\u0435\u0440\u0436\u043a\u0430 \u043a\u043e\u043c\u043f\u043e\u043d\u0435\u043d\u0442\u043e\u0432 Vue \u043d\u0430\u0445\u043e\u0434\u0438\u0442\u044c\u0441\u044f \u0432 \u0430\u043b\u044c\u0444\u0435. \u0414\u043b\u044f \u0442\u043e\u0433\u043e, \u0447\u0442\u043e\u0431\u044b \u043d\u0430\u0447\u0430\u0442\u044c \u0440\u0430\u0431\u043e\u0442\u0430\u0442\u044c \u0441 MDX, \u0434\u043e\u0441\u0442\u0430\u0442\u043e\u0447\u043d\u043e \u0443\u0441\u0442\u0430\u043d\u043e\u0432\u0438\u0442\u044c «Create React App». \u0415\u0441\u0442\u044c \u043f\u043b\u0430\u0433\u0438\u043d\u044b \u0434\u043b\u044f Next.js \u0438 Gatsby. \u0421\u043b\u0435\u0434\u0443\u044e\u0449\u0430\u044f \u0432\u0435\u0440\u0441\u0438\u044f Docusaurus (\u0432\u0435\u0440\u0441\u0438\u044f 2) \u0442\u0430\u043a\u0436\u0435 \u0431\u0443\u0434\u0435\u0442 \u0438\u043c\u0435\u0442\u044c \u0432\u0441\u0442\u0440\u043e\u0435\u043d\u043d\u0443\u044e \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u043a\u0443.<\/p>\n

<\/p>\n

Scrivere documentazione con Docusaurus<\/h2>\n

<\/p>\n

Docusaurus \u00e8 stato sviluppato da Facebook. Viene utilizzato in ciascun progetto open source, eccetto React. Al di fuori dell'azienda, \u00e8 usato da Redux, Prettier, Gulp e Babel.<\/p>\n

<\/p>\n

\"LineeProgetti che utilizzano Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus pu\u00f2 essere utilizzato per scrivere qualunque<\/em> documentazione, non solo per descrivere il front-end. Si basa su React, ma non \u00e8 necessario conoscerlo per utilizzarlo. Prende i tuoi file Markdown e, con un tocco di magia, produce una documentazione ben strutturata, formattata e leggibile con un design accattivante. <\/p>\n

<\/p>\n

\"Linee
\nNel sito di Redux puoi vedere il template standard di Docusaurus<\/em><\/p>\n

<\/p>\n

I siti creati con Docusaurus possono anche includere un blog basato su Markdown. La sintassi \u00e8 evidenziata grazie a Prism.js. Nonostante Docusaurus sia comparso relativamente di recente, \u00e8 stato riconosciuto come il miglior strumento del 2018 su StackShare. <\/p>\n

<\/p>\n

Altre opzioni per la creazione di contenuti<\/h2>\n

<\/p>\n

Docusaurus \u00e8 stato progettato specificamente per la creazione di documentazione. Certo, ci sono milioni di modi per realizzare un sito: puoi avviare la tua soluzione in qualsiasi linguaggio, CMS o utilizzare un generatore di siti statici.<\/p>\n

<\/p>\n

Ad esempio, la documentazione per React, il sistema di design di IBM, Apollo e Ghost CMS utilizzano Gatsby, un generatore di siti statici spesso impiegato per i blog. Se lavori con Vue, VuePress \u00e8 un'ottima scelta. Un'altra opzione \u00e8 utilizzare un generatore scritto in Python, MkDocs. \u00c8 open source e configurabile tramite un file YAML. GitBook \u00e8 un'altra buona alternativa, ma \u00e8 gratuito solo per team aperti e non commerciali. Inoltre, puoi semplicemente caricare file markdown utilizzando Git e lavorarci su GitHub. <\/p>\n

<\/p>\n

Documentazione dei componenti: Docz, Storybook e Styleguidist<\/h2>\n

<\/p>\n

Linee guida, design del sistema, librerie di componenti: qualunque sia il termine che usate, \u00e8 un argomento molto in voga al giorno d'oggi. L'emergere di framework per componenti come React e degli strumenti menzionati qui ha permesso di trasformarli da progetti ambiziosi a strumenti utili. <\/p>\n

<\/p>\n

Storybook, Docz e Styleguidist fanno tutte la stessa cosa: mostrano elementi interattivi e documentano le loro API. Un progetto pu\u00f2 avere decine o addirittura centinaia di componenti, ognuno con vari stati e stili. Per garantire il riutilizzo dei componenti, \u00e8 fondamentale che tutte le persone sappiano che esistono. Catalogare i componenti \u00e8 sufficiente. Le linee guida offrono una panoramica facile da cercare di tutti i vostri componenti, contribuendo a mantenere coerenza visiva e a evitare il lavoro duplicato.<\/p>\n

<\/p>\n

Questi strumenti offrono un modo conveniente per visualizzare diversi stati. Pu\u00f2 essere difficile riprodurre ogni stato di un componente nel contesto di un'applicazione reale. Invece di cliccare sull'applicazione reale, \u00e8 meglio sviluppare un componente separato. \u00c8 possibile simulare stati difficili da ottenere (ad esempio, lo stato di caricamento). <\/p>\n

<\/p>\n

Oltre a una dimostrazione visiva dei vari stati e a un elenco delle propriet\u00e0, \u00e8 spesso necessario scrivere una descrizione generale del contenuto: giustificazioni del design, casi d'uso o descrizioni dei risultati dei test utente. Markdown \u00e8 molto semplice da apprendere \u2014 idealmente, le linee guida dovrebbero essere una risorsa condivisa per designer e sviluppatori. Docz, Styleguidist e Storybook offrono un modo semplice per mescolare Markdown con componenti.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Attualmente, Docz funziona solo con React, ma \u00e8 in lavorazione il supporto per Preact, Vue e componenti web. Docz \u00e8 il pi\u00f9 recente dei tre strumenti, ma \u00e8 riuscito a raccogliere oltre 14.000 stelle su GitHub. Docz offre due componenti \u2014 <Playground><\/code> e < Props ><\/code>. Vengono importati e utilizzati nei file. .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\/src\/Button\";\n\n## Puoi _scrivere_ **markdown**\n### Puoi importare e utilizzare i componenti\n\n