{"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 viventi \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, c'\u00e8 la possibilit\u00e0 che non decolli mai. Una buona documentazione in ufficio ti consente di non rispondere sempre alle stesse domande. Inoltre, la documentazione garantisce che le persone possano comprendere il progetto se i membri chiave dell'azienda lasciano o cambiano ruoli. Linee guida viventi aiutano a mantenere l'integrit\u00e0 dei dati. <\/p>\n

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

Se hai bisogno di scrivere un testo lungo, Markdown \u00e8 un'ottima alternativa a HTML. A volte la sintassi di Markdown non \u00e8 sufficiente. In questo caso, possiamo utilizzare HTML al suo interno. Ad esempio, elementi personalizzati. Quindi, se stai costruendo un sistema di design con componenti web nativi, \u00e8 facile integrarli nella documentazione testuale. Se utilizzi React (o qualsiasi altro framework JSX, come Preact o Vue), puoi fare lo stesso utilizzando 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 viene sempre pi\u00f9 frequentemente integrato negli strumenti di documentazione.<\/p>\n

<\/p>\n

Cos'\u00e8 MDX?<\/h2>\n

<\/p>\n

all'interno di ogni container per impostazione predefinita apparir\u00e0 cos\u00ec: .mdx<\/code> ha la stessa sintassi del Markdown, ma consente di importare componenti interattivi JSX e di integrarli nel tuo contenuto. Il supporto per i componenti Vue \u00e8 attualmente in fase alfa. Per iniziare a lavorare con MDX, \u00e8 sufficiente installare \u00abCreate React App\u00bb. Sono disponibili plugin per Next.js e Gatsby. La prossima versione di Docusaurus (versione 2) avr\u00e0 anche supporto integrato.<\/p>\n

<\/p>\n

Scrivere documentazione con Docusaurus<\/h2>\n

<\/p>\n

Docusaurus \u00e8 stato creato da Facebook. Lo utilizzano in ogni progetto open source, tranne che per React. Al di fuori dell'azienda, \u00e8 utilizzato 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 da chiunque<\/em> documentazione, non solo per descrivere il frontend. Ha React sotto il cofano, ma non \u00e8 necessario conoscere React per utilizzarlo. Prende i tuoi file Markdown e, con un pizzico di magia, la documentazione ben strutturata, formattata e leggibile con un bel design \u00e8 pronta. <\/p>\n

<\/p>\n

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

<\/p>\n

I siti creati con Docusaurus possono includere anche un blog basato su Markdown. Prism.js \u00e8 gi\u00e0 integrato per l'evidenziazione della sintassi. Nonostante Docusaurus sia relativamente 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 specificamente progettato per la creazione di documentazione. Certo, ci sono milioni di modi per creare un sito: puoi implementare una tua soluzione in qualsiasi lingua, CMS o utilizzare un generatore di siti statici.<\/p>\n

<\/p>\n

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

<\/p>\n

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

<\/p>\n

Linee guida, sistemi di design, librerie di componenti: qualunque sia il termine che usi, sono diventati molto popolari di recente. L'emergere di framework basati sui componenti, come React, e degli strumenti menzionati qui, ha permesso di trasformarli da progetti vanitosi in strumenti utili. <\/p>\n

<\/p>\n

Storybook, Docz e Styleguidist fanno tutti la stessa cosa: mostrano elementi interattivi e documentano le loro API. Un progetto pu\u00f2 avere decine o persino centinaia di componenti, tutti con vari stati e stili. Se desideri che i componenti siano riutilizzabili, le persone devono sapere che esistono. Per questo \u00e8 sufficiente catalogare i componenti. Le linee guida forniscono una panoramica facile da cercare di tutti i tuoi componenti. Questo aiuta a mantenere la coerenza visiva ed evitare il lavoro duplicato.<\/p>\n

<\/p>\n

Questi strumenti forniscono un modo semplice per visualizzare i vari stati. Pu\u00f2 essere difficile riprodurre ogni stato di un componente nel contesto di un'applicazione reale. Invece di cliccare su un'applicazione reale, \u00e8 opportuno sviluppare un componente separato. \u00c8 possibile modellare stati difficili da raggiungere (ad esempio, lo stato di caricamento). <\/p>\n

<\/p>\n

Accanto alla dimostrazione visiva di diversi stati e a un elenco di 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 imparare: idealmente, le linee guida dovrebbero essere una risorsa condivisa per designer e sviluppatori. Docz, Styleguidist e Storybook offrono un modo facile per mescolare Markdown con componenti.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Attualmente Docz funziona solo con React, ma \u00e8 in corso un attivo lavoro per supportare Preact, Vue e componenti web. Docz \u00e8 lo strumento pi\u00f9 recente dei tre, ma ha gi\u00e0 raccolto oltre 14.000 stelle su Github. Docz presenta due componenti \u2014 <Playground><\/code> e < Props ><\/code>. Vengono importati e usati 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 usare i componenti\n\n