Guía de Markdown (GitHub Flavored)

1
2
3
4
5
6
# Encabezado de nivel 1
## Encabezado de nivel 2
### Encabezado de nivel 3
#### Encabezado de nivel 4
##### Encabezado de nivel 5
###### Encabezado de nivel 6

*Texto en cursiva* o _también en cursiva_

**Texto en negrita** o __también en negrita__

***Texto en negrita y cursiva*** o ___también en negrita y cursiva___

~~Texto tachado~~

* Primer elemento
* Segundo elemento
* Tercer elemento
  * Sub-elemento
  * Otro sub-elemento

1. Primer elemento
2. Segundo elemento
3. Tercer elemento
   1. Sub-elemento
   2. Otro sub-elemento

[Texto del enlace](https://ejemplo.com)

[Enlace con título](https://ejemplo.com "Título opcional")

[Enlace a archivo local](./archivo.md)

<https://ejemplo.com>

![Texto alternativo](ruta/a/imagen.png)

![Texto alternativo](ruta/a/imagen.png "Título opcional")

Usá la función `printf()` para imprimir.

1
2
3
4
5
6
7
````` c
#include <stdio.h>

int main() {
    printf("Hola Mundo\n");
    return 0;
}

<!-- {code-block} markdown -->

Lenguajes comunes: `c`, `python`, `java`, `javascript`, `bash`, `sql`, `html`,
`css`, etc.

**Casos de uso:**
- Ejemplos de código completos y ejecutables
- Snippets de configuración
- Comandos de terminal (usando `bash` o `sh`)
- Salida de programas (usando `text` o sin especificar)

## Citas

Las citas destacan fragmentos de texto importantes, referencias textuales de
documentación oficial, o notas importantes que deben diferenciarse del texto
principal.

Usá el símbolo `>` para crear citas.

``` markdown
> Esta es una cita.
> Puede tener múltiples líneas.
>
> Y múltiples párrafos.
```
<!-- markdown -->

**Resultado:**

> Esta es una cita.
> Puede tener múltiples líneas.
>
> Y múltiples párrafos.

**Casos de uso:**
- Citar especificaciones o estándares oficiales
- Destacar advertencias o notas importantes
- Referencias textuales de documentación
- Resaltar mensajes de error o salidas importantes

## Líneas horizontales

Las líneas horizontales separan secciones temáticas diferentes dentro del
documento. Usálas con moderación para indicar cambios de tema importantes, no
entre cada sección.

``` markdown
---

***

___
```
<!-- markdown -->

**Casos de uso:**
- Separar secciones conceptualmente diferentes
- Delimitar ejemplos largos del texto principal
- Separar contenido principal de apéndices o notas finales

## Tablas

Las tablas organizan información estructurada de forma comparativa. Son ideales
para mostrar opciones, comparar características, listar parámetros de funciones,
o presentar datos relacionados.

Las tablas se crean con barras verticales `|` y guiones `-`.

``` markdown
| Encabezado 1 | Encabezado 2 | Encabezado 3 |
| ------------ | ------------ | ------------ |
| Celda 1      | Celda 2      | Celda 3      |
| Celda 4      | Celda 5      | Celda 6      |
```
<!-- markdown -->

### Alineación en tablas

Controlá la alineación del contenido usando `:` en la línea separadora.

``` markdown
| Izquierda | Centro | Derecha |
| :-------- | :----: | ------: |
| Texto     | Texto  | Texto   |
| Más texto | Más    | Más     |
```
<!-- markdown -->

**Casos de uso:**
- Comparar características entre opciones
- Documentar parámetros de funciones (nombre, tipo, descripción)
- Mostrar resultados de benchmarks o mediciones
- Listar tipos de datos y sus rangos
- Comparar operadores o modificadores

**Resultado:**

| Izquierda | Centro | Derecha |
| :-------- | :----: | ------: |
| Texto     | Texto  | Texto   |
| Más texto | Más    | Más     |

## Listas de tareas

Las listas de tareas permiten trackear progreso en documentos de planificación,
guías de ejercicios, o checklists de verificación. Son especialmente útiles en
issues de GitHub y documentos colaborativos.

``` markdown
- [x] Tarea completada
- [ ] Tarea pendiente
- [ ] Otra tarea pendiente
```
<!-- markdown -->

**Resultado:**

- [x] Tarea completada
- [ ] Tarea pendiente
- [ ] Otra tarea pendiente

**Casos de uso:**
- Checklists de instalación o configuración
- Seguimiento de ejercicios completados
- Lista de requisitos o criterios de aceptación
- Planificación de tareas en issues de GitHub

## Escapar caracteres especiales

Para mostrar literalmente caracteres que Markdown interpreta, usá la barra
invertida `\`.

``` markdown
\* No será una viñeta
\# No será un encabezado
\[No será un enlace](https://ejemplo.com)
```
<!-- markdown -->

## HTML en Markdown

GitHub Flavored Markdown permite HTML limitado para casos donde la sintaxis
Markdown no es suficiente. Usá HTML con moderación y solo cuando sea necesario.

``` markdown
<details>
<summary>Haz clic para expandir</summary>

Contenido oculto que se muestra al expandir.

</details>
```
<!-- markdown -->

**Resultado:**

<details>
<summary>Haz clic para expandir</summary>

Contenido oculto que se muestra al expandir.

</details>

**Casos de uso:**
- Secciones colapsables para contenido opcional o avanzado
- Soluciones de ejercicios que querés ocultar inicialmente
- Contenido complementario que no querés que interrumpa el flujo
- Detalles técnicos adicionales para lectores interesados

## Comentarios

Los comentarios son invisibles en el documento renderizado. Usálos para notas
internas, recordatorios para revisiones futuras, o para desactivar temporalmente
contenido sin borrarlo.

```{code-block} markdown
:linenos:
<!-- Este es un comentario que no se verá -->
<!-- TODO: Agregar más ejemplos aquí -->
<!-- Sección desactivada temporalmente:
## Contenido en desarrollo
...
-->

```
<!-- {code-block} markdown -->

**Casos de uso:**
- Notas para otros colaboradores
- TODOs y recordatorios de contenido pendiente
- Desactivar secciones temporalmente sin perder el contenido
- Metadatos o anotaciones que no deben publicarse

## Emojis

En GitHub Flavored Markdown, podés usar códigos de emoji.

``` markdown
:smile: :heart: :thumbsup: :rocket:
```
<!-- markdown -->

Podés encontrar una lista de estos códigos en
[rxaviers/emoji-markup](https://gist.github.com/rxaviers/7360908)

## Referencias

Para más información sobre Markdown:

- [Guía oficial de GitHub Flavored Markdown](https://github.github.com/gfm/)
- [Markdown Guide](https://www.markdownguide.org/)

## Consejos prácticos

1. **Legibilidad**: Escribí Markdown pensando en que sea legible incluso en su
   forma sin procesar.
2. **Consistencia**: Mantené un estilo consistente en todo el documento.
3. **Espaciado**: Dejá líneas en blanco entre bloques para mejor legibilidad.
4. **Anidación**: Usá espacios o tabs para anidar listas correctamente (4
   espacios o 1 tab).
5. **Previsualización**: Siempre previsualizá el documento antes de compartirlo.