{"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\/es\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Gu\u00edas en vivo \u2014 MDX y otros marcos","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Puede que tengas el mejor proyecto de c\u00f3digo abierto, pero si no tiene una buena documentaci\u00f3n, es probable que nunca despegue. En la oficina, una buena documentaci\u00f3n te permitir\u00e1 no responder las mismas preguntas repetidamente. La documentaci\u00f3n tambi\u00e9n garantiza que las personas pueden entender el proyecto si los empleados clave dejan la empresa o cambian de roles. Las gu\u00edas en vivo ayudar\u00e1n a asegurar la integridad de los datos. <\/p>\n

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

Si necesitas escribir un texto largo, Markdown es una excelente alternativa a HTML. A veces, la sintaxis de Markdown no es suficiente. En este caso, podemos usar HTML dentro de \u00e9l. Por ejemplo, elementos personalizados. Por lo tanto, si est\u00e1s construyendo un sistema de dise\u00f1o con componentes web nativos, es f\u00e1cil incluirlos en la documentaci\u00f3n textual. Si utilizas React (o cualquier otro marco JSX, como Preact o Vue), puedes hacer lo mismo utilizando MDX. <\/p>\n

<\/p>\n

Este art\u00edculo es una amplia revisi\u00f3n de herramientas para escribir documentaci\u00f3n y crear gu\u00edas. No todas las herramientas enumeradas aqu\u00ed utilizan MDX, pero cada vez se integra m\u00e1s en las herramientas de documentaci\u00f3n.<\/p>\n

<\/p>\n

\u00bfQu\u00e9 es MDX?<\/h2>\n

<\/p>\n

Archivo .mdx<\/code> tiene la misma sintaxis que Markdown, pero permite importar componentes JSX interactivos y embebidos en su contenido. El soporte para componentes de Vue est\u00e1 en alfa. Para comenzar a trabajar con MDX, simplemente instale 'Create React App'. Hay complementos para Next.js y Gatsby. La pr\u00f3xima versi\u00f3n de Docusaurus (versi\u00f3n 2) tambi\u00e9n tendr\u00e1 soporte incorporado.<\/p>\n

<\/p>\n

Escribiendo documentaci\u00f3n con Docusaurus<\/h2>\n

<\/p>\n

Docusaurus fue creado por Facebook. Lo utilizan en cada proyecto de c\u00f3digo abierto, excepto en React. Fuera de la empresa, lo utilizan Redux, Prettier, Gulp y Babel.<\/p>\n

<\/p>\n

\"Gu\u00edasProyectos que utilizan Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus se puede utilizar para escribir cualquier<\/em> documentaci\u00f3n, no solo para describir el frontend. Bajo el cap\u00f3 tiene React, pero no es necesario estar familiarizado con \u00e9l para usarlo. Toma tus archivos Markdown, un toque de magia, y la documentaci\u00f3n bien estructurada, formateada y legible con un bonito dise\u00f1o est\u00e1 lista. <\/p>\n

<\/p>\n

\"Gu\u00edas
\nEn el sitio de Redux se puede ver la plantilla est\u00e1ndar de Docusaurus.<\/em><\/p>\n

<\/p>\n

Los sitios creados con Docusaurus tambi\u00e9n pueden incluir un blog basado en Markdown. Para la resaltaci\u00f3n de sintaxis, Prism.js est\u00e1 integrado de inmediato. A pesar de que Docusaurus apareci\u00f3 relativamente recientemente, ha sido reconocido como la mejor herramienta de 2018 en StackShare. <\/p>\n

<\/p>\n

Otras opciones para crear contenido<\/h2>\n

<\/p>\n

Docusaurus est\u00e1 dise\u00f1ado espec\u00edficamente para crear documentaci\u00f3n. Por supuesto, hay un mill\u00f3n y una manera de hacer un sitio: puedes desplegar tu propia soluci\u00f3n en cualquier lenguaje, CMS o utilizar un generador de sitios est\u00e1ticos.<\/p>\n

<\/p>\n

Por ejemplo, la documentaci\u00f3n de React, el sistema de dise\u00f1o de IBM, Apollo y Ghost CMS utilizan Gatsby, que es un generador de sitios est\u00e1ticos que se usa a menudo para blogs. Si trabajas con Vue, VuePress ser\u00e1 una buena opci\u00f3n para ti. Otra alternativa es usar un generador escrito en Python: MkDocs. Es de c\u00f3digo abierto y se configura a trav\u00e9s de un solo archivo YAML. GitBook tambi\u00e9n es una buena opci\u00f3n, pero es gratuito solo para equipos abiertos y no comerciales. Tambi\u00e9n puedes simplemente subir archivos markdown utilizando git y trabajar con ellos en Github. <\/p>\n

<\/p>\n

Documentaci\u00f3n de componentes: Docz, Storybook y Styleguidist<\/h2>\n

<\/p>\n

Gu\u00edas, sistemas de dise\u00f1o, bibliotecas de componentes: como sea que los llames, se han vuelto muy populares \u00faltimamente. La aparici\u00f3n de frameworks de componentes, como React, y las herramientas mencionadas aqu\u00ed, ha permitido convertirlos de proyectos vanidosos en herramientas \u00fatiles. <\/p>\n

<\/p>\n

Storybook, Docz y Styleguidist hacen lo mismo: muestran elementos interactivos y documentan su API. Un proyecto puede tener decenas o incluso cientos de componentes, todos con diferentes estados y estilos. Si quieres que los componentes sean reutilizables, la gente debe saber que existen. Para ello, es suficiente con catalogar los componentes. Las gu\u00edas proporcionan una visi\u00f3n general f\u00e1cil de buscar de todos tus componentes. Esto ayuda a mantener la coherencia visual y evitar el trabajo repetido.<\/p>\n

<\/p>\n

Estas herramientas ofrecen una manera conveniente de ver diferentes estados. Puede ser dif\u00edcil reproducir cada estado de un componente en el contexto de una aplicaci\u00f3n real. En lugar de hacer clic en una aplicaci\u00f3n real, vale la pena desarrollar un componente por separado. Puedes simular estados dif\u00edciles de alcanzar (por ejemplo, el estado de carga). <\/p>\n

<\/p>\n

Junto con la demostraci\u00f3n visual de varios estados y una lista de propiedades, a menudo es necesario escribir una descripci\u00f3n general del contenido: justificaci\u00f3n del dise\u00f1o, casos de uso o descripci\u00f3n de los resultados de la prueba de usuario. Markdown es muy f\u00e1cil de aprender; idealmente, las directrices deber\u00edan ser un recurso compartido para dise\u00f1adores y desarrolladores. Docz, Styleguidist y Storybook ofrecen una forma f\u00e1cil de mezclar Markdown con componentes.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Actualmente, Docz solo funciona con React, pero se est\u00e1 trabajando activamente en el soporte para Preact, Vue y componentes web. Docz es la m\u00e1s reciente de las tres herramientas, pero ha conseguido m\u00e1s de 14,000 estrellas en Github. Docz presenta dos componentes: <Playground><\/code> y < Props ><\/code>. Se importan y utilizan en archivos .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Puedes _escribir_ **markdown**\n### Puedes importar y usar componentes\n\n