Guía Markdown de Docusaurus
Un generador de sitios estático que permite documentar proyectos con Markdown.
Docusaurus es un gerador de sitios estáticos open source que te permite redactar los contenidos del sitio que vayas a crear con Markdown. Desarrollado con Node.js, Docusaurus es un proyecto de Facebook y está especialmente pensado para crear documentaciones.
Acerca de Docusaurus
El uso de Docusaurus está muy extendido, siendo miles las empresas o particulares que documentan sus proyectos con este generador. Docusaurus no solo permite redactar el texto de la documentación de un proyecto, sino que también es posible crear páginas estáticas mediante la sintaxis JSX de React, pudiendo también crear blogs, secciones de noticias y cualquier otro tipo de contenido organizado.
Docusaurus es ideal para generar documentaciones. Sin embargo, su primera versión es todo lo personalizable que uno desearía a la hora de crear otro tipo de sitio web. Docusaurus utiliza el proceador de Markdown remarkable.
Actualmente existen dos verisones parelelas de Docusaurus, que son la primera y la segunda versión:
Docusaurus v1: La primera versión de Docusaurus generará una web estática que no será una aplicación SPA, siendo por ello muy estable e incluyendo soporte para nevegadores antiguos como Internet Explorer 11.
Docusaurus v2: La segunda versión de docusaurus generará una aplicación SPA que seguirá la filosofía de la Jamstack, combinando el uso de React con archivos MDX, que es un formato de archivo que acepta el uso de React junto con la sintaxis Markdown. Esta versión es también mas presonalizble, pudiendo crear una web completa que no se tendrá que limitar a las páginas de la documentación de tu proyecto. Podrás crear landing pages, blogs o secciones de noticias, todo ello combinado con la búsqueda mediante Algolia, soporte para traducciones, diferentes versiones y todos los elementos necesarios para el posicionamiento SEO. Sin embaro, no es compatible con Internet Explorer 11 o versiones anteriores.
Actualmente son muchos los proyectos que usan Docusaurus. Por ejemplo, la documetnación del framework SCIWP de WordPress ha sido creada mediante Docusaurus.
Puedes accecer a la web oficial de Docusaurus desde aquí. Si por el contrairo prefieres usar Docusaurus v2, accede a esta web.
Soporte Markdown
Docusaurus soporta los siguientes elementos de la sintaxis básica y avanzada de markdown:
| Elemento | Soporte | Notas |
|---|---|---|
| Encabezados | Sí | |
| Párrafos | Sí | |
| Saltos de línea | Parcial | Para saltar de línea podrás pulsar INTRO o bien agregar una barra invertida \ al final de la línea. |
| Negrita | Sí | |
| Cursiva | Sí | |
| Citas | Sí | |
| Listas ordenadas | Sí | |
| Listas no ordenadas | Sí | |
| Código | Sí | |
| Línea horizontal | Sí | |
| Enlaces | Sí | |
| Imágenes | Sí | |
| HTML | Sí | |
| Tablas | Sí | |
| Bloques de código avanzados | Sí | |
| Resaltado de sintaxis | Sí | |
| Notas al pie | Sí | |
| IDs de cabecera | Parcial | No podrás definir Ids personalizados para las cabeceras, pero se generan automáticamente. |
| Listas de definiciones | Sí | |
| Texto tachado | Sí | |
| Listas de tareas | Sí | Podrás usar corchetes [ ], pero no guiones. |
| Emojis (copiar y pegar) | Sí | |
| Emojis (shortcodes) | No | |
| Enlaces automáticos | Sí | |
| Deshabilitar enlaces automáticos | Sí |
Además de soportar HTMl, Docusaurusus también soporta React gracias al uso del formato MDX.
Alternativas a Docusaurus
Existen también otros generadores de sitios web estáticos que te permitirán crear documentaciones, como por ejemplo Docusaurus.
👋 Hola! Soy Edu, me encanta crear cosas y he redactado este tutorial. Si te ha resultado útil, el mayor favor que me podrías hacer es el de compatirlo en Twitter.
Sígueme en Twitter para estar al día con mi contenido. 😊
