Guía completa de Markdown en GitHub

Aprende a usar Markdown en GitHub para crear READMEs profesionales, issues, pull requests, wikis, GitHub Pages y GitHub Actions con ejemplos prácticos.

GitHub es la plataforma donde más se usa Markdown en el mundo. Desde el README de un repositorio hasta los comentarios en un pull request, prácticamente todo lo que escribes en GitHub pasa por su motor de Markdown. Dominar Markdown en GitHub te permite crear documentación profesional, gestionar proyectos y comunicarte de forma clara con tu equipo.

En esta guía vamos a recorrer todas las funcionalidades de Markdown específicas de GitHub, con ejemplos prácticos que puedes copiar y usar directamente en tus repositorios.

GitHub Flavored Markdown (GFM)

GitHub usa su propia variante de Markdown llamada GitHub Flavored Markdown (GFM). Extiende la sintaxis básica de Markdown con funcionalidades adicionales que solo funcionan en GitHub. Esto significa que algunas cosas que escribes en GitHub no se verán igual en otros editores de Markdown, y viceversa. Veamos qué características extra te ofrece GFM.

Tablas

Las tablas son una de las adiciones más útiles de GFM. En Markdown estándar no existen, pero en GitHub puedes crearlas usando el carácter | para separar columnas y - para definir la fila de encabezado. No necesitas que las columnas estén perfectamente alineadas en el código fuente; GitHub se encarga de renderizarlas correctamente.

A continuación, un ejemplo de tabla sencilla que lista comandos de Git con su descripción:

| Comando | Descripcion |
|---------|------------|
| `git status` | Ver cambios pendientes |
| `git add .` | Preparar todos los cambios |
| `git commit` | Crear un commit |

Al previsualizarlo en GitHub, verás una tabla con bordes y buen espaciado. Puedes alinear columnas con : en la fila separadora (por ejemplo, :---: para centrar o ---: para alinear a la derecha). Consulta nuestra guía de tablas en Markdown para más detalles sobre alineación y formato avanzado.

Listas de tareas

Las listas de tareas (o task lists) son una de las funcionalidades más populares de GitHub. Se usan constantemente en issues para desglosar el trabajo pendiente y en pull requests para crear checklists de revisión. La sintaxis es simple: una lista normal con - [ ] para tareas pendientes y - [x] para tareas completadas.

Aquí tienes un ejemplo típico de un issue donde se está planificando una nueva funcionalidad:

- [x] Disenar la base de datos
- [x] Crear los endpoints de la API
- [ ] Escribir tests de integracion
- [ ] Documentar la API

Lo interesante es que GitHub renderiza estas listas con checkboxes interactivos. Esto quiere decir que cualquier colaborador con permisos puede hacer clic directamente en el checkbox para marcarlo como completado, sin necesidad de editar el texto del issue. Además, GitHub muestra una barra de progreso en la vista previa del issue (por ejemplo, "2 de 4 tareas completadas").

Tachado

El tachado es otra extensión de GFM que no existe en Markdown estándar. Se usa envolviendo el texto con doble virgulilla (~~). Es especialmente útil en discusiones e issues cuando quieres indicar que algo ya no es relevante sin borrarlo del todo.

~~Este texto esta tachado~~

GitHub mostrará el texto con una línea horizontal atravesándolo. En la práctica, lo verás mucho en comentarios de issues donde alguien corrige o actualiza una decisión anterior, dejando el contexto original visible.

Alertas

Desde 2023, GitHub incorporó bloques de alerta como parte oficial de GFM. Son una evolución de las citas normales (>) pero con un propósito específico: destacar información importante de forma visual. Cada tipo de alerta tiene su propio color e icono, lo que permite al lector identificar rápidamente si se trata de una nota informativa, una advertencia o un error potencial.

La sintaxis es una cita normal con un marcador especial en la primera línea. Existen cinco tipos disponibles:

> [!NOTE]
> Informacion relevante que el usuario debe conocer.

> [!TIP]
> Consejo opcional para mejorar la experiencia.

> [!IMPORTANT]
> Informacion crucial para que todo funcione correctamente.

> [!WARNING]
> Contenido que requiere atencion para evitar problemas.

> [!CAUTION]
> Consecuencias potenciales de una accion.

En la práctica, NOTE y TIP se muestran en tonos azules y verdes (informativos), mientras que WARNING y CAUTION aparecen en amarillo y rojo respectivamente. Úsalos con moderación: si todo es una alerta, nada destaca. Consulta nuestra guía de alertas y advertencias para ver cómo se renderizan.

Bloques de código con resaltado

Si trabajas con código en GitHub (que probablemente es el caso), esta es una de las funcionalidades que más vas a usar. GitHub soporta resaltado de sintaxis para cientos de lenguajes. Solo tienes que indicar el nombre del lenguaje justo después de las tres comillas invertidas que abren el bloque.

Por ejemplo, para mostrar código Python con colores de sintaxis:

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
```

GitHub coloreará las palabras clave, los strings y los números automáticamente según el lenguaje que hayas indicado. Funciona con javascript, bash, json, yaml, sql y prácticamente cualquier lenguaje que se te ocurra. Si no indicas el lenguaje, el bloque se renderizará como texto plano sin colores.

También puedes hacer referencia a código en comentarios usando `codigo` inline, que se muestra con fondo gris para distinguirlo del texto normal.

Diagramas Mermaid

Una de las funcionalidades más potentes de GitHub es la capacidad de renderizar diagramas directamente desde código, sin necesidad de herramientas externas ni imágenes. GitHub usa la librería Mermaid para esto. Solo tienes que crear un bloque de código con el lenguaje mermaid y escribir la definición del diagrama.

El siguiente ejemplo crea un diagrama de flujo que representa un pipeline de CI/CD típico:

```mermaid
graph LR
    A[Commit] --> B[CI/CD]
    B --> C{Tests}
    C -->|Pass| D[Deploy]
    C -->|Fail| E[Fix]
```

Al previsualizarlo en GitHub, verás un diagrama visual con cajas y flechas en lugar del código fuente. Mermaid soporta diagramas de flujo, de secuencia, de Gantt, diagramas de entidad-relación y muchos más. Es una forma excelente de documentar arquitecturas y procesos sin salir de Markdown.

Fórmulas matemáticas

Si tu proyecto involucra matemáticas, ciencia de datos o cualquier disciplina técnica, te alegrará saber que GitHub soporta fórmulas LaTeX. Puedes escribir fórmulas en línea dentro del texto usando $E = mc^2$, o crear bloques de fórmulas centradas para expresiones más complejas.

Este ejemplo muestra una sumatoria en un bloque de fórmula independiente:

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

GitHub renderizará la fórmula con la tipografía matemática adecuada, incluyendo subíndices, superíndices, fracciones y símbolos especiales. Es la misma sintaxis que se usa en LaTeX, así que si ya conoces ese sistema, puedes aprovechar todo tu conocimiento aquí.

Esta es una de esas funcionalidades que hacen que GitHub se sienta tan cómodo para trabajar en equipo. No necesitas crear enlaces manualmente para referenciar issues, commits o usuarios: GitHub los detecta automáticamente y los convierte en enlaces clicables.

Aquí tienes los patrones más comunes que GitHub reconoce:

https://github.com/usuario/repo    --> enlace automatico
#123                                --> enlace al issue 123
@usuario                            --> mencion al usuario
abc1234                             --> enlace al commit (si existe)
usuario/repo#123                    --> issue de otro repositorio

Esto funciona en cualquier lugar donde se renderice Markdown: issues, PRs, comentarios, wikis e incluso mensajes de commit. Es especialmente útil cuando necesitas referenciar conversaciones o cambios relacionados sin interrumpir el flujo de tu texto.

Notas al pie

Las notas al pie te permiten añadir información adicional sin interrumpir el flujo del texto principal. Son ideales para aclaraciones, referencias bibliográficas o detalles técnicos que no todos los lectores necesitan. La sintaxis usa corchetes con un acento circunflejo y un identificador.

Este texto tiene una referencia[^1].

[^1]: Aqui esta la explicacion detallada.

GitHub renderiza las notas al pie como números superíndice clicables. Al hacer clic, el lector salta directamente a la nota correspondiente al final del documento, donde también encontrará un enlace para volver al punto original del texto.

README.md

Ahora que conoces las funcionalidades de GFM, veamos dónde aplicarlas. El primer lugar es el archivo README.md, que es la carta de presentación de tu repositorio. GitHub lo renderiza automáticamente en la página principal del repo, así que es literalmente lo primero que ven los visitantes.

Un buen README marca la diferencia entre un proyecto que la gente entiende y quiere usar, y uno que ignoran porque no saben ni para qué sirve. No necesitas escribir una novela, pero sí cubrir los puntos esenciales.

Estructura recomendada

La siguiente plantilla cubre las secciones que todo buen README debería tener. Puedes copiarla y adaptarla a tu proyecto. Fíjate en cómo se combinan encabezados, bloques de código y texto descriptivo:

# Nombre del proyecto

Descripcion breve de que hace el proyecto y por que es util.

## Instalacion

` ` `bash
npm install mi-proyecto
` ` `

## Uso

` ` `javascript
import { miFuncion } from 'mi-proyecto'
miFuncion()
` ` `

## Documentacion

Enlace a la documentacion completa si existe.

## Contribuir

Instrucciones para contribuir al proyecto.

## Licencia

MIT

Lo importante es que cada sección sea breve y vaya al grano. Un visitante debería poder entender qué hace tu proyecto y cómo instalarlo en menos de un minuto.

Badges

Los badges (o insignias) son esas pequeñas imágenes que ves en la parte superior de muchos READMEs populares. Muestran de un vistazo el estado del build, la versión publicada, la licencia y otros datos relevantes. Se implementan como imágenes de Markdown que apuntan a servicios externos que generan la imagen dinámicamente.

Estos son los tres badges más comunes:

![Build Status](https://github.com/usuario/repo/actions/workflows/ci.yml/badge.svg)
![npm version](https://img.shields.io/npm/v/mi-paquete)
![License](https://img.shields.io/badge/license-MIT-blue)

El primero muestra si tu CI está pasando (verde) o fallando (rojo), el segundo la versión actual en npm, y el tercero la licencia del proyecto. Servicios como shields.io te permiten crear badges personalizados con los colores y textos que quieras.

Para una guía más detallada sobre READMEs, consulta nuestro tutorial de cómo escribir un README.

Issues y pull requests

Además del README, los otros lugares donde más escribirás Markdown en GitHub son los issues y los pull requests. Aquí es donde ocurre la colaboración real: reportar bugs, proponer funcionalidades, revisar código y discutir cambios. GitHub te permite usar plantillas para estandarizar estos procesos, y están escritas en Markdown.

Plantillas de issues

Las plantillas de issues son archivos Markdown que viven en la carpeta .github/ISSUE_TEMPLATE/ de tu repositorio. Cuando alguien crea un nuevo issue, GitHub le ofrece elegir una plantilla y rellena automáticamente el cuerpo del issue con la estructura que hayas definido. Esto ahorra mucho tiempo porque no tienes que pedir la misma información una y otra vez.

Este es un ejemplo de plantilla para reportar bugs:

---
name: Bug report
about: Reportar un error
---

## Descripcion del bug
Descripcion clara y concisa del problema.

## Pasos para reproducir
1. Ir a '...'
2. Hacer clic en '...'
3. Ver el error

## Comportamiento esperado
Que deberia ocurrir.

## Capturas de pantalla
Si aplica, anade capturas.

## Entorno
- OS: [ej. Windows 11]
- Navegador: [ej. Chrome 120]
- Version: [ej. 1.2.3]

Fíjate en el frontmatter YAML al inicio (entre ---): define el nombre de la plantilla y una descripción corta que GitHub mostrará en el selector de plantillas. Las secciones con encabezados ## guían al usuario para que proporcione toda la información necesaria.

Plantillas de PR

De forma similar a los issues, puedes crear una plantilla para pull requests. A diferencia de las plantillas de issues, solo existe una plantilla de PR por repositorio y se guarda en .github/pull_request_template.md. Cada vez que alguien abra un PR, el campo de descripción se rellenará automáticamente con esta plantilla.

## Que cambia este PR

Descripcion de los cambios.

## Tipo de cambio

- [ ] Bug fix
- [ ] Nueva funcionalidad
- [ ] Breaking change
- [ ] Documentacion

## Como testear

Instrucciones para probar los cambios.

## Checklist

- [ ] Tests anadidos/actualizados
- [ ] Documentacion actualizada
- [ ] Sin breaking changes

Las listas de tareas en la plantilla de PR son especialmente útiles. Los revisores pueden ir marcando cada punto a medida que verifican el código, lo que da visibilidad sobre el estado de la revisión.

Referencias cruzadas

Una de las mayores ventajas de usar Markdown en GitHub es la capacidad de conectar issues, PRs y commits entre sí. Cuando escribes una referencia en un comentario o en la descripción de un PR, GitHub crea automáticamente un enlace bidireccional: tanto en el PR como en el issue referenciado aparecerá la conexión.

Estas son las palabras clave más utilizadas:

Fixes #42
Closes #15
Related to #100
See commit abc1234

La magia aquí está en las palabras clave Fixes y Closes. Cuando un PR que contiene Fixes #42 se mergea a la rama principal, GitHub cierra automáticamente el issue #42. Esto mantiene tu backlog limpio sin esfuerzo manual. La palabra Related to solo crea la referencia cruzada sin cerrar nada, lo cual es útil cuando quieres enlazar contexto relacionado.

GitHub Wikis

Cuando tu proyecto crece y el README se queda corto, las wikis de GitHub son el siguiente paso natural. Cada repositorio puede tener una wiki escrita en Markdown, y funciona como un mini sitio de documentación con múltiples páginas interconectadas. A diferencia del README, las wikis tienen su propio repositorio Git, lo que permite colaboración independiente.

Estructura de una wiki

Las wikis se organizan como archivos Markdown individuales donde el nombre del archivo se convierte en el título de la página. Hay algunos nombres especiales que GitHub reconoce automáticamente:

Home.md              --> Pagina principal
Getting-Started.md   --> Primeros pasos
API-Reference.md     --> Referencia de la API
FAQ.md               --> Preguntas frecuentes
_Sidebar.md          --> Barra lateral personalizada
_Footer.md           --> Pie de pagina personalizado

Home.md es la página de inicio, y los archivos que empiezan con guion bajo (_Sidebar.md, _Footer.md) son elementos de diseño que aparecen en todas las páginas. El resto son páginas normales que puedes nombrar como quieras.

Por defecto, la wiki muestra una lista automática de todas las páginas en la barra lateral. Pero si quieres controlar el orden y la estructura de la navegación, puedes crear un archivo _Sidebar.md con enlaces organizados como prefieras:

**Inicio**
* [Home](Home)

**Guias**
* [Primeros pasos](Getting-Started)
* [Configuracion](Configuration)

**Referencia**
* [API](API-Reference)
* [FAQ](FAQ)

Una vez creado el _Sidebar.md, esta barra lateral aparecerá en todas las páginas de tu wiki, proporcionando una navegación consistente.

GitHub Pages

Si necesitas algo más que una wiki, GitHub Pages te permite crear un sitio web completo y gratuito a partir de archivos Markdown en tu repositorio. Usa Jekyll por defecto como generador de sitios estáticos, lo que significa que puedes escribir tus páginas en Markdown y GitHub se encarga de convertirlas en HTML con un diseño profesional.

Configuración básica

El proceso para poner en marcha tu sitio es sorprendentemente sencillo:

  1. Crea un repositorio llamado usuario.github.io
  2. Añade un archivo index.md con tu contenido
  3. Activa GitHub Pages en Settings > Pages
  4. Tu sitio estará disponible en https://usuario.github.io

Frontmatter

Cada página de tu sitio en GitHub Pages puede tener un bloque de frontmatter YAML al inicio del archivo. Este bloque, delimitado por ---, define metadatos como el título de la página, el layout que quieres usar y cualquier variable personalizada que necesites.

Aquí tienes un ejemplo mínimo de una página con frontmatter:

---
title: Mi pagina
layout: default
---

# Bienvenido a mi sitio

Este contenido se renderiza como HTML.

Jekyll procesa este archivo, aplica el layout default (que incluye cabecera, menú de navegación y pie de página), y genera una página HTML completa. Todo el contenido Markdown debajo del frontmatter se convierte automáticamente en HTML.

Para más detalles sobre GitHub Pages, consulta nuestra guía de GitHub Pages.

GitHub Actions y Markdown

Para cerrar esta guía, veamos cómo puedes automatizar tareas relacionadas con tu documentación en Markdown. GitHub Actions te permite ejecutar flujos de trabajo automáticos cada vez que haces un push, abres un PR o según cualquier otro evento. Hay acciones de la comunidad diseñadas específicamente para mantener tus archivos Markdown en buen estado.

Con el tiempo, los enlaces en tu documentación pueden romperse: una página externa cambia de URL, renombras un archivo o borras una sección. Este workflow revisa automáticamente todos los enlaces de tus archivos Markdown cada vez que haces push, y falla si encuentra alguno roto.

name: Check Markdown Links
on: push
jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: gaurav-nelson/github-action-markdown-link-check@v1

Si algún enlace está roto, verás el error directamente en la pestaña Actions de tu repositorio, con el detalle de qué archivo y qué enlace falló. Es una forma sencilla de mantener tu documentación siempre actualizada.

Generar tabla de contenidos

Cuando tus archivos Markdown son largos, una tabla de contenidos al inicio ayuda mucho a la navegación. En lugar de mantenerla manualmente (lo cual es tedioso y propenso a errores), puedes automatizarla con esta acción que genera y actualiza la tabla de contenidos automáticamente:

name: Generate TOC
on: push
jobs:
  toc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: technote-space/toc-generator@v4

Esta acción analiza los encabezados de tu archivo, genera la tabla de contenidos y crea un commit automático con el cambio. Solo necesitas indicar en tu archivo dónde quieres que aparezca la tabla con un comentario especial.

Consejos para Markdown en GitHub

Para terminar, aquí tienes una serie de buenas prácticas que te ayudarán a sacar el máximo provecho de Markdown en GitHub. Son pequeños hábitos que marcan una gran diferencia en la calidad de tu documentación:

  1. Usa encabezados descriptivos: GitHub genera automáticamente una tabla de contenidos para archivos largos.
  2. Añade alt text a imágenes: ![descripcion](url) mejora la accesibilidad.
  3. Usa bloques de código con lenguaje: python` en vez de solo ``` ```` para resaltado de sintaxis.
  4. Referencia issues en commits: git commit -m "Fix login bug (#42)" crea enlaces automáticos.
  5. Usa alertas para destacar información: Los bloques [!NOTE], [!WARNING], etc. son más visibles que las citas normales.
  6. Aprovecha las listas de tareas: Son interactivas y perfectas para seguir el progreso.
  7. Mantén el README corto: Si necesitas documentación extensa, usa la wiki o un generador de sitios como 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.

para estar al día con mi contenido. 😊