GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) es la versión mejorada de Markdown de GitHub con características adicionales diseñadas específicamente para el desarrollo de software y la colaboración. Esta guía cubre todas las extensiones de sintaxis especiales disponibles en GitHub.

¿Qué es GitHub Flavored Markdown (GFM)?

GitHub Flavored Markdown extiende la sintaxis básica de Markdown con características que lo hacen más útil para:

• Documentación (READMEs, wikis)
• Seguimiento de issues
• Pull requests
• Revisión de código
• Gestión de proyectos

Características Principales de GFM

1. Bloques de Código Delimitados

GFM admite bloques de código delimitados con resaltado de sintaxis específico del lenguaje:

```javascript
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15

2. Resaltado de Sintaxis

GitHub admite resaltado de sintaxis para cientos de lenguajes. Algunos comunes incluyen:

# Script Bash
echo "Hello GitHub!"

# Script Python
def greet(name):
    return f"Hello, {name}!"

// Código Java
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello GitHub!");
    }
}

3. Listas de Tareas

Cree listas de tareas interactivas con casillas de verificación:

- [x] Completar autenticación de usuario
- [x] Implementar endpoints de API
- [ ] Escribir pruebas unitarias
  - [ ] Pruebas de backend
  - [ ] Pruebas de frontend
- [ ] Desplegar a producción

• [x] Completar autenticación de usuario
• [x] Implementar endpoints de API
• [ ] Escribir pruebas unitarias
  • [ ] Pruebas de backend
  • [ ] Pruebas de frontend
• [ ] Desplegar a producción

4. Tablas

GFM proporciona una sintaxis simple para crear tablas:

| Característica    | Soportada | Descripción                     |
|-------------------|-----------|---------------------------------|
| Fenced Code       | ✅        | Resaltado específico del lenguaje|
| Task Lists        | ✅        | Casillas de verificación interactivas|
| Tables            | ✅        | Visualización de datos estructurados|
| Mentions          | ✅        | Notificaciones de usuario y equipo|
| Emoji             | ✅        | Expresiones visuales            |

Característica	Soportada	Descripción
Fenced Code	✅	Resaltado específico del lenguaje
Task Lists	✅	Casillas de verificación interactivas
Tables	✅	Visualización de datos estructurados
Mentions	✅	Notificaciones de usuario y equipo
Emoji	✅	Expresiones visuales

5. Menciones

Mencione usuarios o equipos para notificarlos:

@username - Mencionar a un usuario específico
@team-name - Mencionar a un equipo

6. Emoji

Agregue emoji usando códigos cortos:

:smile: - 😊
:thumbsup: - 👍
:heart: - ❤️
:rocket: - 🚀
:warning: - ⚠️

😄 - 😊 👍 - 👍 ❤️ - ❤️ 🚀 - 🚀 ⚠️ - ⚠️

7. Enlace Automático

GFM enlaza automáticamente ciertos tipos de contenido:

Números de Issue y Pull Request

#123 - Enlaza al issue 123
PR #456 - Enlaza al pull request 456

Hashes SHA

a1b2c3d - Enlaza al commit con este SHA

Menciones de Usuario en Issues/PRs

@username - Enlaza automáticamente al perfil del usuario

URLs

https://github.com - Automáticamente se convierte en un enlace

8. Texto Tachado

GFM admite texto tachado:

~~Este texto está tachado~~

Este texto está tachado

9. Referencias de Enlace Automático

GFM crea automáticamente enlaces para:

• URLs HTTP/HTTPS
• Direcciones de correo electrónico
• Números de issue/PR de GitHub
• SHAs de commits

https://github.com/markdownlang/markdownlang.com
user@example.com
#123
PR #456
a1b2c3d4e5f6

10. Resaltado de Líneas en Bloques de Código

Resalte líneas específicas en bloques de código:

```javascript{2,4}
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);

11. Resaltado de Sintaxis Diff

Resalte cambios en el código con sintaxis diff:

```diff
- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };
```

- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };

12. Markup Específico de GitHub

Alertas

Use sintaxis especial para alertas en la documentación de GitHub:

> [!NOTE]
> Esta es una alerta de nota.

> [!TIP]
> Esta es una alerta de consejo.

> [!IMPORTANT]
> Esta es una alerta importante.

> [!WARNING]
> Esta es una alerta de advertencia.

> [!CAUTION]
> Esta es una alerta de precaución.

NOTE

Esta es una alerta de nota.

TIP

Esta es una alerta de consejo.

IMPORTANT

Esta es una alerta importante.

WARNING

Esta es una alerta de advertencia.

CAUTION

Esta es una alerta de precaución.

Enlaces Relativos

Use enlaces relativos para navegar entre archivos en el mismo repositorio:

[README](/es/README.md)
[Directrices de Contribución](/es/CONTRIBUTING.md)
[Documentación de API](/es/docs/api.md)

Enlaces de Imagen con Texto al Pasar el Mouse

![GitHub Logo](/es/images/github-logo.png "GitHub Logo - Texto al Pasar el Mouse")

Uso Avanzado de GFM

1. Listas Anidadas con Listas de Tareas

Combine listas anidadas con listas de tareas:

## Hoja de Ruta del Proyecto

### Fase 1: Planificación
- [x] Definir el alcance del proyecto
- [x] Identificar requisitos
  - [x] Requisitos funcionales
  - [x] Requisitos no funcionales
- [x] Crear cronograma

### Fase 2: Desarrollo
- [x] Configurar la estructura del proyecto
- [ ] Implementar características principales
  - [x] Autenticación
  - [ ] Panel de control
  - [ ] Integración de API

2. Tablas con Emoji y Enlaces

Mejore las tablas con emoji y enlaces:

| Componente     | Estado              | Mantenedor   |
|----------------|---------------------|--------------|
| Autenticación  | ✅ Estable          | @johndoe     |
| Base de datos  | ⚠️ Necesita actualización | @janedoe |
| API            | 🚧 En Progreso      | @bobsmith    |
| UI             | ✅ Estable          | @alicesmith  |

Componente	Estado	Mantenedor
Autenticación	✅ Estable	@johndoe
Base de datos	⚠️ Necesita actualización	@janedoe
API	🚧 En Progreso	@bobsmith
UI	✅ Estable	@alicesmith

3. Bloques de Código en Listas

Incluya bloques de código dentro de listas:

1. Instalar dependencias:

   ```bash
   npm install

2. Ejecutar el servidor de desarrollo:

   npm run dev

3. Compilar para producción:

   npm run build

### 4. Bloques de Cita con Código

Combine citas con bloques de código:

```markdown
> **Consejo Pro:** Use el siguiente comando para verificar rápidamente el estado de Git:
>
> ```bash
> git status
> ```

Consejo Pro: Use el siguiente comando para verificar rápidamente el estado de Git:

git status

GFM en Diferentes Contextos de GitHub

Archivos README

Los archivos README admiten todas las características de GFM y se muestran automáticamente en las páginas del repositorio.

Issues y Pull Requests

• Use listas de tareas para seguir el progreso
• Mencione miembros del equipo para colaboración
• Incluya fragmentos de código con resaltado de sintaxis
• Referencie issues/PRs relacionados usando la sintaxis #123

Comentarios

• Use emoji para reacciones rápidas
• Referencie líneas en el código con comentarios de línea
• Use bloques de cita para responder a puntos específicos

Wikis

• Organice el contenido con páginas anidadas
• Use tablas para datos estructurados
• Incluya ejemplos de código con resaltado de sintaxis

Mejores Prácticas

1. Estilo de Código

<!-- ✅ Bueno -->
```javascript
// Use nombres de función descriptivos
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

function f(i){return i.reduce((a,b)=>a+b.p,0)}```

2. Diseño de Tablas

<!-- ✅ Bueno -->
| Característica | Descripción | Estado |
|----------------|-------------|--------|
| Característica 1 | Breve descripción | ✅ |
| Característica 2 | Otra descripción | 🚧 |

<!-- ❌ Evitar -->
| Característica | Descripción | Estado | | | |
|----------------|-------------|--------|---|---|---|
| Característica 1 | Esta descripción es demasiado larga y hace que la tabla sea difícil de leer en dispositivos móviles | ✅ | | | |

3. Uso de Listas de Tareas

<!-- ✅ Bueno -->
## Sprint Backlog
- [x] Completar página de perfil de usuario
- [ ] Implementar funcionalidad de búsqueda
  - [x] API de backend
  - [ ] Componente de frontend
- [ ] Escribir documentación

<!-- ❌ Evitar -->
- [ ] Tarea 1
- [ ] Tarea 2
- [ ] Tarea 3
- [ ] Tarea 4
- [ ] Tarea 5
(Demasiadas tareas sin organización)

GFM vs Markdown Estándar

Característica	Markdown Estándar	GitHub Flavored Markdown
Bloques de Código Delimitados	❌	✅
Resaltado de Sintaxis	❌	✅
Listas de Tareas	❌	✅
Tablas	❌	✅
Texto Tachado	❌	✅
Emoji	❌	✅
Menciones	❌	✅
Enlace Automático	Limitado	Extenso

Herramientas para Trabajar con GFM

Editores Locales

• Visual Studio Code - Vista previa de GFM y extensiones
• Typora - Renderizado de GFM en tiempo real
• Mark Text - Soporte de GFM

Herramientas en Línea

• GitHub Gist - Cree y comparta fragmentos de GFM
• Dillinger - Editor de GFM en línea
• StackEdit - Soporte de GFM con sincronización en la nube

Herramientas de Línea de Comandos

• glow - Renderizador de GFM para terminal
• pandoc - Convierta GFM a otros formatos
• marked - Analizador de GFM para Node.js

Problemas Comunes y Soluciones

1. Bloque de Código Sin Resaltado

Problema: El bloque de código no muestra resaltado de sintaxis

Solución: Asegúrese de especificar el lenguaje correcto:

<!-- ✅ Correcto -->
```javascript
console.log("Hello");

console.log("Hello"); // Usando jsx en lugar de javascript para código no-JSX

### 2. Casillas de Verificación de Lista de Tareas No Funcionales

**Problema:** Las casillas de verificación de la lista de tareas no son interactivas

**Solución:** Asegúrese de usar la sintaxis correcta (espacio entre `-` y `[ ]`):

```markdown
<!-- ✅ Correcto -->
- [ ] Tarea

<!-- ❌ Incorrecto -->
-[ ] Tarea (sin espacio)
-[x] Tarea (sin espacio)

3. Tabla No Se Renderiza Correctamente

Problema: Las columnas de la tabla están desalineadas

Solución: Asegúrese de que las barras verticales estén alineadas correctamente:

<!-- ✅ Correcto -->
| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

<!-- ❌ Incorrecto -->
|Column 1|Column 2|
|--|--|
|Data 1|Data 2|

Próximos Pasos

• Aprender sintaxis básica de Markdown
• Ver la hoja de trucos de sintaxis
• Practicar con GitHub Gist
• Leer la documentación oficial de GitHub GFM

---

GitHub Flavored Markdown es una herramienta poderosa para la comunicación y la colaboración en el desarrollo de software. Al dominar estas características, puede crear documentación más efectiva, realizar un mejor seguimiento de los issues y colaborar de manera más eficiente con su equipo.