Cómo usar Markdown para documentación y archivos README
El archivo README.md es la primera impresión de cualquier repositorio de GitHub: explica qué hace el proyecto, cómo instalarlo y cómo usarlo. Un README bien escrito en Markdown con estructura clara, ejemplos de código y badges puede marcar la diferencia entre un proyecto que alguien adopta y uno que ignora. Esta guía cubre la sintaxis Markdown esencial para escribir documentación técnica de calidad, con ejemplos que puedes probar directamente en WikiPlus Editor de Markdown sin necesidad de crear ningún repositorio.
Estructura básica de un README.md
Un README bien estructurado sigue un orden que facilita la lectura progresiva. El título (# Nombre del Proyecto) va primero, seguido de una descripción breve de una o dos oraciones. Luego los badges de estado (CI, cobertura de tests, versión en npm) si aplica. A continuación, la sección de Instalación con el comando exacto de npm install o pip install. Luego Uso con un ejemplo mínimo de código funcional. Después Configuración para opciones avanzadas. Finalmente Contribuir, Licencia y un enlace a la documentación completa si existe. Esta estructura es tan habitual en GitHub que los desarrolladores la reconocen instantáneamente y saben dónde encontrar lo que buscan sin necesidad de leer linealmente.
Sintaxis esencial: títulos, negrita, listas y código
Los títulos en Markdown se crean con almohadillas: # para H1, ## para H2, ### para H3. La negrita usa **doble asterisco** y la cursiva *un asterisco*. Las listas con viñetas empiezan con - o * al inicio de la línea. Las listas numeradas con 1., 2., 3. (el número real no importa, Markdown lo ordena automáticamente). El código en línea va entre `backticks`. Los bloques de código usan tres backticks seguidos del nombre del lenguaje: ```javascript para JavaScript, ```python para Python, ```bash para comandos de terminal. Esta sintaxis es compatible con GitHub Flavored Markdown, el dialecto más extendido en entornos de desarrollo.
Tablas, citas y listas de tareas
Las tablas en Markdown se crean con pipes | y guiones -. La primera fila es el encabezado, la segunda es el separador de formato. Las citas de texto usan el símbolo > al inicio de la línea, creando el bloque de cita visual típico de documentación. Las listas de tareas, específicas de GitHub Flavored Markdown, usan - [ ] para tareas pendientes y - [x] para tareas completadas, muy útiles en archivos de progreso o changelogs. WikiPlus Editor de Markdown renderiza todos estos elementos correctamente en la vista previa, permitiendo verificar que la tabla tiene el número correcto de columnas o que los separadores están alineados antes de hacer commit al repositorio.
Convertir Markdown a HTML para publicación web
Cuando necesitas publicar contenido Markdown en una web que no soporta Markdown nativo —un CMS WordPress clásico, una plantilla de correo, una intranet corporativa— la función de exportación a HTML de WikiPlus Editor es la forma más rápida de hacer la conversión. El HTML resultante usa etiquetas semánticas estándar: h1-h6 para títulos, strong para negrita, em para cursiva, ul/li y ol/li para listas, blockquote para citas, pre/code para bloques de código. No incluye estilos inline ni clases CSS propietarias, por lo que se integra limpiamente con cualquier hoja de estilos existente. Puedes añadir un atributo class al bloque raíz en el CMS si necesitas encapsular los estilos del contenido importado.
Preguntas frecuentes
- ¿Markdown funciona igual en GitHub, Notion y Confluence?
- Cada plataforma implementa su propio dialecto de Markdown. GitHub usa GitHub Flavored Markdown (GFM) que añade tablas, tareas y menciones. Notion tiene su propio subconjunto con algunas diferencias en el manejo de espacios y bloques. Confluence soporta Markdown en ciertos contextos pero no en todos. La especificación CommonMark es el denominador común compatible con la mayoría de plataformas. WikiPlus Editor sigue CommonMark más las extensiones GFM más habituales.
- ¿Puedo incluir imágenes en el Markdown del editor?
- Sí, usando la sintaxis estándar: . En el editor de WikiPlus puedes escribir la sintaxis manualmente o usar el botón de imagen en la barra de herramientas. Las imágenes se referencian por URL externa; el editor no tiene sistema de subida de imágenes propio. Para documentación en GitHub, sube las imágenes al repositorio y usa rutas relativas como ./docs/imagen.png.
- ¿El editor funciona offline?
- Una vez que la página de WikiPlus Editor de Markdown está completamente cargada en tu navegador, puedes escribir, editar y exportar documentos sin conexión a internet. La lógica de renderizado Markdown se ejecuta localmente en el navegador usando JavaScript. Si recargas la página sin conexión, necesitarás volver a conectarte para cargar la aplicación nuevamente.