Markdown para desarrolladores

Para los desarrolladores, Markdown es una herramienta fundamental. Está presente en la documentación, los README de proyectos, los issues y pull requests de GitHub, las wikis, los comentarios de código y mucho más.

Dónde usan Markdown los desarrolladores

GitHub y GitLab

Los principales usos de Markdown en GitHub y GitLab son:

README.md: La carta de presentación de cada repositorio.
Issues: Para reportar bugs y proponer mejoras.
Pull Requests: Descripción de los cambios propuestos.
Wikis: Documentación extendida del proyecto.
GitHub Pages: Sitios web generados desde Markdown.

Documentación de código

Markdown se utiliza en la documentación de código de las siguientes formas:

Docstrings: Algunos lenguajes soportan Markdown en sus docstrings.
API docs: Herramientas como Swagger permiten descripciones en Markdown.
CHANGELOG.md: Registro de cambios entre versiones.
CONTRIBUTING.md: Guía para contribuidores.

Comunicación

Markdown se usa en las siguientes plataformas de comunicación:

Slack: Soporta un subconjunto de Markdown.
Discord: Soporta Markdown para formatear mensajes.
Stack Overflow: Preguntas y respuestas en Markdown.

Sintaxis esencial para desarrolladores

Bloques de código con resaltado de sintaxis

```javascript
function saludar(nombre) {
  return `Hola, ${nombre}!`;
}
```

Diff para mostrar cambios

```diff
- const nombre = "antiguo";
+ const nombre = "nuevo";
```

Tablas para documentar APIs

| Método | Endpoint | Descripción |
|---|---|---|
| GET | /api/users | Listar usuarios |
| POST | /api/users | Crear usuario |
| PUT | /api/users/:id | Actualizar usuario |
| DELETE | /api/users/:id | Eliminar usuario |

Listas de tareas

- [x] Implementar autenticación
- [x] Crear endpoints de la API
- [ ] Escribir tests unitarios
- [ ] Configurar CI/CD

Markdown en GitHub

GitHub usa su propio dialecto de Markdown llamado GitHub Flavored Markdown (GFM), que incluye varias funcionalidades exclusivas muy útiles para desarrolladores.

Referencias automáticas (Autolinked references)

GitHub convierte automáticamente ciertas referencias en enlaces clicables dentro de issues, pull requests y comentarios:

- Referencia a un issue: #123
- Referencia a un usuario: @octocat
- Referencia a un commit: a1b2c3d (o el SHA completo)
- Referencia cruzada a otro repo: usuario/repositorio#456
- Referencia a un pull request: #789 (misma sintaxis que issues)

Esto facilita la trazabilidad entre código, issues y discusiones sin necesidad de copiar URLs.

Alertas (Alerts)

GitHub soporta bloques de alerta especiales dentro de Markdown para resaltar información importante:

> [!NOTE]
> Información útil que los usuarios deberían conocer, incluso si solo están leyendo por encima.

> [!TIP]
> Consejos opcionales para ayudar al usuario a tener más éxito.

> [!IMPORTANT]
> Información clave que los usuarios necesitan saber para lograr su objetivo.

> [!WARNING]
> Información urgente que necesita atención inmediata del usuario para evitar problemas.

> [!CAUTION]
> Advierte sobre riesgos o resultados negativos de ciertas acciones.

Cada tipo de alerta se renderiza con un color e icono diferente en GitHub, lo que las hace muy visibles en la documentación.

Diagramas con Mermaid

GitHub renderiza automáticamente diagramas escritos en bloques de código con el lenguaje mermaid:

```mermaid
graph TD
    A[Inicio] --> B{¿Es un bug?}
    B -->|Sí| C[Crear issue]
    B -->|No| D[Crear feature request]
    C --> E[Asignar prioridad]
    D --> E
    E --> F[Implementar]
    F --> G[Pull Request]
    G --> H[Code Review]
    H --> I[Merge]
```

Esto genera un diagrama de flujo visual directamente en el README o en cualquier archivo Markdown del repositorio. Mermaid soporta diagramas de flujo, diagramas de secuencia, diagramas de Gantt, diagramas ER y más.

Ejemplo de diagrama de secuencia

```mermaid
sequenceDiagram
    participant Cliente
    participant API
    participant BD

    Cliente->>API: GET /api/usuarios
    API->>BD: SELECT * FROM usuarios
    BD-->>API: Resultados
    API-->>Cliente: JSON con usuarios
```

Otros trucos de GitHub Markdown

GitHub Markdown ofrece estos trucos adicionales:

Tablas de contenidos automáticas: GitHub genera automáticamente una tabla de contenidos en los archivos README cuando hay múltiples encabezados (icono de lista en la esquina superior izquierda del archivo).
Colapsables: Usa <details> y <summary> para crear secciones expandibles:

<details>
<summary>Haz clic para ver más detalles</summary>

Aquí va el contenido oculto con **formato Markdown**.

- Punto 1
- Punto 2

</details>

Matemáticas: GitHub soporta LaTeX para fórmulas matemáticas con $ para inline y $$ para bloques.

Herramientas de linting para Markdown

Igual que los linters de código ayudan a mantener un estilo consistente en JavaScript o Python, existen herramientas de linting específicas para Markdown:

markdownlint

markdownlint es el linter más popular para Markdown. Detecta problemas de estilo y consistencia como:

Niveles de encabezado saltados (h1 directo a h3).
Espacios en blanco innecesarios al final de las líneas.
Líneas demasiado largas.
Listas sin espaciado consistente.
Múltiples encabezados h1 en el mismo documento.

Se instala como extensión de VS Code (davidanson.vscode-markdownlint) o como herramienta de línea de comandos:

npm install -g markdownlint-cli
markdownlint "**/*.md"

Puedes configurar las reglas con un archivo .markdownlint.json en la raíz del proyecto:

{
  "MD013": { "line_length": 120 },
  "MD033": false,
  "MD041": false
}

remark-lint

remark-lint forma parte del ecosistema unified (remark). Es más modular y extensible que markdownlint. Cada regla es un plugin independiente:

npm install remark-cli remark-preset-lint-recommended

Configúralo en package.json o .remarkrc:

{
  "plugins": [
    "remark-preset-lint-recommended",
    ["remark-lint-maximum-line-length", 120],
    "remark-lint-no-dead-urls"
  ]
}

Prettier

Prettier es un formateador de código que también soporta Markdown. No detecta errores de estilo, sino que reformatea automáticamente el archivo para que sea consistente:

npx prettier --write "**/*.md"

Prettier normaliza los saltos de línea, la indentación de listas, los separadores de tablas y más. Es ideal para mantener la consistencia en repositorios con varios contribuidores.

Integrar linting en CI/CD

Puedes añadir el linting de Markdown a tu pipeline de integración continua. Ejemplo con GitHub Actions:

# .github/workflows/lint-markdown.yml
name: Lint Markdown
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DavidAnson/markdownlint-cli2-action@v18
        with:
          globs: "**/*.md"

Más ejemplos de bloques de código

Markdown con resaltado de sintaxis soporta una gran variedad de lenguajes. Aquí van ejemplos prácticos para los lenguajes más populares:

Python

```python
from dataclasses import dataclass
from typing import Optional

@dataclass
class Usuario:
    nombre: str
    email: str
    edad: Optional[int] = None

    def saludar(self) -> str:
        return f"Hola, soy {self.nombre}"

# Uso
usuario = Usuario(nombre="Ana", email="ana@ejemplo.com", edad=28)
print(usuario.saludar())
```

Go

```go
package main

import (
    "fmt"
    "net/http"
    "encoding/json"
)

type Usuario struct {
    Nombre string `json:"nombre"`
    Email  string `json:"email"`
}

func main() {
    http.HandleFunc("/api/usuario", func(w http.ResponseWriter, r *http.Request) {
        usuario := Usuario{Nombre: "Ana", Email: "ana@ejemplo.com"}
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(usuario)
    })

    fmt.Println("Servidor en :8080")
    http.ListenAndServe(":8080", nil)
}
```

Rust

```rust
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Usuario {
    nombre: String,
    email: String,
    edad: Option<u32>,
}

impl Usuario {
    fn nuevo(nombre: &str, email: &str) -> Self {
        Usuario {
            nombre: nombre.to_string(),
            email: email.to_string(),
            edad: None,
        }
    }

    fn saludar(&self) -> String {
        format!("Hola, soy {}", self.nombre)
    }
}

fn main() {
    let usuario = Usuario::nuevo("Ana", "ana@ejemplo.com");
    println!("{}", usuario.saludar());
    println!("{:#?}", usuario);
}
```

TypeScript

```typescript
interface Usuario {
  nombre: string;
  email: string;
  edad?: number;
}

async function obtenerUsuarios(): Promise<Usuario[]> {
  const respuesta = await fetch('/api/usuarios');
  if (!respuesta.ok) {
    throw new Error(`Error HTTP: ${respuesta.status}`);
  }
  return respuesta.json();
}

// Uso con async/await
const usuarios = await obtenerUsuarios();
usuarios.forEach(u => console.log(`${u.nombre} (${u.email})`));
```

SQL

```sql
-- Crear tabla de usuarios
CREATE TABLE usuarios (
    id SERIAL PRIMARY KEY,
    nombre VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    creado_en TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Consulta con JOIN
SELECT u.nombre, COUNT(p.id) as total_posts
FROM usuarios u
LEFT JOIN posts p ON u.id = p.autor_id
GROUP BY u.nombre
ORDER BY total_posts DESC
LIMIT 10;
```

Herramientas recomendadas

Estas son las herramientas más recomendadas para desarrolladores que usan Markdown:

VS Code: Editor con vista previa de Markdown integrada.
Obsidian: Para notas de desarrollo y documentación personal.
Docusaurus: Para documentación de proyectos.
MkDocs: Documentación con Python.
Pandoc: Conversión entre formatos.