Markdown es simple y flexible, pero esa misma libertad puede llevar a documentos inconsistentes o difíciles de leer si no se aplican reglas claras de estilo. Las buenas prácticas aseguran que el texto sea legible en texto plano y consistente cuando se renderiza en distintas plataformas (GitHub, GitLab, CMS, editores de notas, etc.).
La legibilidad es la capacidad de un documento para ser comprendido de manera rápida, tanto en texto plano como en su versión renderizada.
Reglas clave
Usar encabezados claros y jerárquicos
Evitar títulos genéricos como “Tema 1”; mejor “1. Introducción a Markdown”.
# Curso de Markdown
## Tema 1: Introducción
### Subtema: Historia
Separar secciones con líneas en blanco — Aumenta la claridad del texto en bruto.
Incorrecto:
## Instalación
Paso 1: descargar.
Paso 2: instalar.
Correcto:
## Instalación
Paso 1: descargar.
Paso 2: instalar.
Evitar párrafos muy largos — Mejor dividir en bloques cortos.
Usar listas para enumerar ideas — Más claras que párrafos corridos.
- Fácil de usar
- Portable
- Compatible con múltiples plataformas
Mantener texto alternativo en imágenes — Facilita accesibilidad.
La consistencia hace que el documento luzca profesional y homogéneo.
Reglas clave
Escoger un estilo de listas y mantenerlo
Incorrecto (mezcla de - y *):
- Manzana
* Banana
- Naranja
Correcto:
- Manzana
- Banana
- Naranja
Usar el mismo estilo para énfasis — Markdown admite *cursiva* y _cursiva_, pero no conviene mezclarlos. Recomendación: elegir * para cursiva y ** para negrita.
Encabezados: un solo # por nivel — No duplicar ## y ### en el mismo título.
Incorrecto:
### ### Instalación
Correcto:
## Instalación
Nombrar enlaces de manera descriptiva — Evitar “clic aquí”.
[Documentación oficial de Python](https://www.python.org)
Formatear bloques de código correctamente — Usar triple backticks y especificar lenguaje.
def saludo():
print("Hola, Markdown!")
Mantener consistencia en tablas — Alinear pipes para legibilidad.
| Lenguaje | Popularidad |
|------------|-------------|
| Python | Alta |
| JavaScript | Muy alta |
# Guía de Markdown
Markdown es un lenguaje de marcado ligero para crear documentos.
## Características principales
- Legible en texto plano
- Fácil de convertir a otros formatos
- Compatible con múltiples plataformas
## Ejemplo de código
```javascript
function sumar(a, b) {
return a + b;
}
console.log(sumar(3, 4));
```
## Recursos adicionales
- [Guía oficial](https://daringfireball.net/projects/markdown/)
- [GitHub Flavored Markdown](https://github.github.com/gfm/)
👉 Este ejemplo cumple con: encabezados jerárquicos, listas consistentes, código con resaltado y enlaces descriptivos.
La legibilidad se logra con párrafos cortos, listas claras, imágenes con texto alternativo y buena separación visual. La consistencia en estilos mantiene profesional el documento: mismo estilo de listas, negritas/cursivas coherentes, enlaces descriptivos y encabezados bien jerarquizados. Un documento Markdown con buenas prácticas es más fácil de mantener, compartir y convertir a otros formatos.