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.

Imagen de Editor Markdown

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:

ElementoSoporteNotas
Encabezados
Párrafos
Saltos de líneaParcialPara saltar de línea podrás pulsar INTRO o bien agregar una barra invertida \ al final de la línea.
Negrita
Cursiva
Citas
Listas ordenadas
Listas no ordenadas
Código
Línea horizontal
Enlaces
Imágenes
HTML
Tablas
Bloques de código avanzados
Resaltado de sintaxis
Notas al pié
IDs de cabeceraParcialNo podrás definir Ids personalizados para las cabeceras, pero se generan automáticamente.
Listas de definiciones
Texto tachado
Listas de tareasPodrás usar corchetes [ ], pero no guiones.
Emojis (copiar y pegar)
Emojis (shortcodes)No
Enlaces automáticos
Deshabilitar enlaces automáticos

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.