Saltar a contenido

Markdown para estudiantes

Markdown es un lenguaje de marcado en texto plano. Su objetivo es que sea fácil de leer y de escribir, permitiendo dar formato a un documento sin necesidad de usar el ratón o menús complicados.

A continuación, se presentan los elementos principales. Para los elementos en línea (texto), usamos una tabla comparativa. Para los bloques estructurales, utiliza las pestañas para intercalar entre el código fuente y cómo se visualiza.

1. Formato de texto básico

Aquí puedes ver cómo se escribe el código a la izquierda y cómo lo interpreta el visor a la derecha.

Elemento Código Markdown Resultado
Negritas **Texto en negrita** Texto en negrita
Cursivas *Texto en cursiva* Texto en cursiva
Negrita y cursiva ***Texto resaltado*** Texto resaltado
Tachado ~~Texto tachado~~ Texto tachado
Código en línea Usa `print("Hola mundo")` Usa print("Hola mundo")
Enlace (link) [TecNM](https://www.tecnm.mx) TecNM

2. Encabezados (títulos)

Los encabezados se crean utilizando el símbolo de numeral o almohadilla (#). La cantidad de símbolos determina el nivel y tamaño del título (de 1 a 6).

# Título principal (nivel 1)
## Subtítulo (nivel 2)
### Sección (nivel 3)
#### Subsección (nivel 4)

Título principal (nivel 1)

Subtítulo (nivel 2)

Sección (nivel 3)

Subsección (nivel 4)

3. Listas

Puedes crear listas ordenadas (con números) o desordenadas (con viñetas).

Regla de los 4 espacios

Siempre deja una línea en blanco antes de empezar una lista. Para anidar elementos (sub-listas), debes usar exactamente 4 espacios (o un tabulador completo), de lo contrario el formato de la lista se romperá.

- Primer elemento
- Segundo elemento
    - Sub-elemento (usando exactamente 4 espacios)
    - Otro sub-elemento
- Tercer elemento
  • Primer elemento
  • Segundo elemento
    • Sub-elemento (usando exactamente 4 espacios)
    • Otro sub-elemento
  • Tercer elemento
1. Investigar el tema.
2. Desarrollar el código.
3. Probar la aplicación.
  1. Investigar el tema.
  2. Desarrollar el código.
  3. Probar la aplicación.

4. Bloques de código

Para mostrar múltiples líneas de código (SQL, Python, Java), usa tres comillas invertidas (```) seguidas del nombre del lenguaje para que se aplique el color correcto.

Consejo de espaciado

Deja siempre una línea en blanco antes y después del bloque de código.

```sql
SELECT nombre, precio
FROM productos
WHERE precio > 500;
```

SELECT nombre, precio
FROM productos
WHERE precio > 500;

5. Citas (blockquotes)

Se utilizan para resaltar un bloque de texto, como una nota importante o la cita de un autor. Se usa el símbolo >. Deja una línea en blanco antes de iniciar la cita.

> "El buen código es su propia mejor documentación."
> - Steve McConnell

"El buen código es su propia mejor documentación." - Steve McConnell

6. Listas de tareas (checklists)

Son muy útiles para llevar un control de los requisitos de un proyecto.

- [x] Crear base de datos.
- [x] Configurar conexión.
- [ ] Diseñar interfaz.
- [ ] Realizar pruebas.
  • Crear base de datos.
  • Configurar conexión.
  • Diseñar interfaz.
  • Realizar pruebas.

7. Tablas

Puedes organizar información en filas y columnas usando barras verticales (|) y guiones (-). Es obligatorio dejar una línea en blanco antes de la tabla para que se renderice correctamente.

| ID | Nombre | Calificación |
| :--- | :--- | :--- |
| 1 | Ana | 95 |
| 2 | Luis | 88 |
ID Nombre Calificación
1 Ana 95
2 Luis 88

8. Imágenes

La sintaxis es casi idéntica a la de los enlaces, pero se le agrega un signo de exclamación ! al principio.

![Logo de Python](https://upload.wikimedia.org/wikipedia/commons/c/c3/Python-logo-notext.svg)

Logo de Python

9. Buenas prácticas en la industria

Markdown es el formato estándar de documentación técnica en la industria del software. Al escribir, considera estos principios:

La filosofía de su creador (John Gruber)

  • Escribir, no publicar: Gruber diseñó Markdown bajo la premisa de que HTML es un formato para publicar, mientras que Markdown es un formato exclusivo para escribir.
  • Sintaxis intuitiva: Los caracteres de puntuación fueron elegidos para que se vean como lo que significan. Por ejemplo, los asteriscos alrededor de una palabra parecen énfasis visual. El documento debe poder leerse como texto plano sin parecer lleno de etiquetas.

Recomendaciones de la comunidad (GitHub y Microsoft)

  • Saltos de línea por oración: En repositorios colaborativos se recomienda dar un salto de línea (Enter) al final de cada oración. Esto ayuda a que el historial de Git y los pull requests muestren solo la oración específica que cambió, facilitando la revisión del código.
  • Estructura lógica: Utiliza un solo encabezado principal por documento y mantén una jerarquía lógica en las secciones sin saltarte niveles.
  • Uso moderado de formato: La prioridad es la claridad. Limita el uso de formato (negritas o cursivas) para evitar que el texto parezca saturado; usarlos en exceso hace que nada destaque realmente.

Tip final para VS Code

Presiona Ctrl + K, suelta las teclas y luego presiona V. Esto abrirá una pantalla dividida donde verás tu código a la izquierda y la vista previa renderizada a la derecha.