{"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\/pt\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Diretrizes ao vivo \u2014 MDX e outras estruturas","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Voc\u00ea pode ter o melhor projeto de c\u00f3digo aberto, mas se n\u00e3o houver uma boa documenta\u00e7\u00e3o, h\u00e1 uma boa chance de que ele nunca decole. No escrit\u00f3rio, uma boa documenta\u00e7\u00e3o evita que voc\u00ea tenha que responder \u00e0s mesmas perguntas repetidamente. A documenta\u00e7\u00e3o tamb\u00e9m garante que as pessoas possam entender o projeto se funcion\u00e1rios-chave sa\u00edrem da empresa ou se os pap\u00e9is mudarem. Diretrizes ao vivo ajudam a garantir a integridade dos dados. <\/p>\n

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

Se voc\u00ea precisa escrever um texto longo, Markdown \u00e9 uma \u00f3tima alternativa ao HTML. \u00c0s vezes, a sintaxe do Markdown n\u00e3o \u00e9 suficiente. Neste caso, podemos usar HTML dentro dele. Por exemplo, elementos personalizados. Portanto, se voc\u00ea estiver construindo um sistema de design com componentes web nativos, \u00e9 f\u00e1cil incorpor\u00e1-los na documenta\u00e7\u00e3o textual. Se voc\u00ea estiver usando React (ou qualquer outro framework JSX, como Preact ou Vue), pode fazer isso da mesma forma usando MDX. <\/p>\n

<\/p>\n

Este artigo \u00e9 uma vis\u00e3o geral abrangente de ferramentas para escrever documenta\u00e7\u00e3o e criar diretrizes. Nem todas as ferramentas listadas aqui utilizam MDX, mas ele est\u00e1 sendo cada vez mais incorporado em ferramentas de documenta\u00e7\u00e3o.<\/p>\n

<\/p>\n

O que \u00e9 MDX?<\/h2>\n

<\/p>\n

Arquivo .mdx<\/code> tem a mesma sintaxe que o Markdown, mas permite importar componentes interativos JSX e incorpor\u00e1-los ao seu conte\u00fado. O suporte a componentes Vue est\u00e1 em fase alfa. Para come\u00e7ar a trabalhar com MDX, basta instalar o 'Create React App'. Existem plugins para Next.js e Gatsby. A pr\u00f3xima vers\u00e3o do Docusaurus (vers\u00e3o 2) tamb\u00e9m ter\u00e1 suporte integrado.<\/p>\n

<\/p>\n

Escrevendo documenta\u00e7\u00e3o com Docusaurus<\/h2>\n

<\/p>\n

O Docusaurus foi desenvolvido pelo Facebook. Ele \u00e9 utilizado em todos os projetos de c\u00f3digo aberto, exceto o React. Fora da empresa, ele \u00e9 utilizado pelo Redux, Prettier, Gulp e Babel.<\/p>\n

<\/p>\n

\"DiretrizesProjetos que utilizam Docusaurus.<\/em><\/p>\n

<\/p>\n

O Docusaurus pode ser usado para escrever (lembrando das pessoas em posi\u00e7\u00f5es elevadas), isso \u00e9 ruim<\/em> documenta\u00e7\u00e3o, n\u00e3o apenas para descrever o frontend. Ele \u00e9 baseado em React, mas n\u00e3o \u00e9 necess\u00e1rio estar familiarizado com ele para utiliz\u00e1-lo. Ele pega seus arquivos Markdown, um toque de m\u00e1gica e uma documenta\u00e7\u00e3o bem estruturada, formatada e leg\u00edvel, com um design bonito, est\u00e1 pronta. <\/p>\n

<\/p>\n

\"Diretrizes
\nNo site do Redux, voc\u00ea pode ver o modelo padr\u00e3o do Docusaurus.<\/em><\/p>\n

<\/p>\n

Sites criados com Docusaurus tamb\u00e9m podem incluir um blog baseado em Markdown. A sintaxe \u00e9 destacada automaticamente com Prism.js. Embora o Docusaurus tenha sido lan\u00e7ado relativamente h\u00e1 pouco tempo, j\u00e1 foi reconhecido como a melhor ferramenta de 2018 no StackShare. <\/p>\n

<\/p>\n

Outras op\u00e7\u00f5es para cria\u00e7\u00e3o de conte\u00fado<\/h2>\n

<\/p>\n

Docusaurus foi especificamente projetado para criar documenta\u00e7\u00e3o. Claro, existem milh\u00f5es de maneiras de fazer um site \u2014 voc\u00ea pode implementar sua pr\u00f3pria solu\u00e7\u00e3o em qualquer linguagem, CMS ou usar um gerador de sites est\u00e1ticos.<\/p>\n

<\/p>\n

Por exemplo, a documenta\u00e7\u00e3o para React, a IBM Design System, Apollo e Ghost CMS usam Gatsby \u2014 um gerador de sites est\u00e1ticos que \u00e9 frequentemente utilizado para blogs. Se voc\u00ea est\u00e1 trabalhando com Vue, VuePress pode ser uma boa op\u00e7\u00e3o para voc\u00ea. Outra alternativa \u00e9 usar um gerador escrito em Python \u2014 MkDocs. Ele \u00e9 open-source e configurado atrav\u00e9s de um \u00fanico arquivo YAML. GitBook tamb\u00e9m \u00e9 uma boa op\u00e7\u00e3o, mas \u00e9 gratuito apenas para equipes abertas e n\u00e3o comerciais. Al\u00e9m disso, voc\u00ea pode simplesmente enviar arquivos Markdown usando git e trabalhar com eles no Github. <\/p>\n

<\/p>\n

Documenta\u00e7\u00e3o de componentes: Docz, Storybook e Styleguidist<\/h2>\n

<\/p>\n

Diretrizes, sistemas de design, bibliotecas de componentes \u2014 como voc\u00ea os chama, se tornaram muito populares recentemente. O surgimento de frameworks de componentes, como React, e as ferramentas mencionadas aqui \u2014 permitiu que se transformassem de projetos f\u00fateis em ferramentas \u00fateis. <\/p>\n

<\/p>\n

Storybook, Docz e Styleguidist fazem a mesma coisa: exibem elementos interativos e documentam suas APIs. Um projeto pode ter dezenas ou at\u00e9 centenas de componentes \u2014 todos com diferentes estados e estilos. Se voc\u00ea quer que os componentes sejam reutilizados, as pessoas precisam saber que eles existem. Para isso, \u00e9 suficiente catalogar os componentes. As diretrizes fornecem uma vis\u00e3o geral que \u00e9 f\u00e1cil de pesquisar de todos os seus componentes. Isso ajuda a manter a consist\u00eancia visual e evitar trabalho duplicado.<\/p>\n

<\/p>\n

Essas ferramentas oferecem uma maneira conveniente de visualizar diferentes estados. Pode ser dif\u00edcil reproduzir cada estado de um componente no contexto de um aplicativo real. Em vez de clicar em um aplicativo real, \u00e9 melhor desenvolver um componente separado. Voc\u00ea pode simular estados de dif\u00edcil acesso (por exemplo, estado de carregamento). <\/p>\n

<\/p>\n

Al\u00e9m da demonstra\u00e7\u00e3o visual de v\u00e1rios estados e da lista de propriedades, muitas vezes \u00e9 necess\u00e1rio escrever uma descri\u00e7\u00e3o geral do conte\u00fado \u2014 justificativas de design, casos de uso ou descri\u00e7\u00e3o dos resultados de testes com usu\u00e1rios. O Markdown \u00e9 muito f\u00e1cil de aprender \u2014 idealmente, as diretrizes devem ser um recurso colaborativo para designers e desenvolvedores. Docz, Styleguidist e Storybook oferecem uma maneira f\u00e1cil de misturar Markdown com componentes.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Atualmente, o Docz funciona apenas com React, mas h\u00e1 um trabalho ativo para suportar Preact, Vue e componentes da web. O Docz \u00e9 a ferramenta mais nova das tr\u00eas, mas conseguiu reunir mais de 14.000 estrelas no Github. O Docz apresenta dois componentes \u2014 <Playground><\/code> e < Props ><\/code>. Eles s\u00e3o importados e usados em arquivos .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Voc\u00ea pode _escrever_ **markdown**\n### Voc\u00ea pode importar e usar componentes\n\n