Por qué escribir en Markdown
Markdown es un lenguaje de marcado ligero que usa símbolos sencillos para representar el formato. Quien escribe no necesita tocar el ratón, se concentra en el contenido y el formato se genera automáticamente.
Ventajas:
- Texto plano, cualquier editor puede abrirlo
- Compatible con control de versiones (Git puede hacer diff)
- Convertible a HTML, PDF, Word y otros formatos
- Baja curva de aprendizaje, 10 minutos para empezar
Sintaxis básica
Encabezados
# Encabezado de nivel 1
## Encabezado de nivel 2
### Encabezado de nivel 3
#### Encabezado de nivel 4
Se recomienda un solo encabezado de nivel 1 por artículo.
Párrafos
Las líneas en blanco separan los párrafos. El contenido sin línea en blanco se considera del mismo párrafo.
Énfasis
**Negrita**
*Cursiva*
~~Tachado~~
Listas
Lista no ordenada:
- Elemento
- Elemento
- Subelemento (sangría)
Lista ordenada:
1. Primer elemento
2. Segundo elemento
Enlaces e imágenes
[Texto del enlace](https://example.com)
Código
En línea: code
Bloque de código:
```javascript
const x = 1;
### Citas
Contenido de la cita Segunda línea
### Línea divisoria
## Sintaxis extendida
### Tablas
| Nombre | Edad |
|---|---|
| Tom | 25 |
### Lista de tareas
- Completado
- No completado
### Notas al pie
Texto del cuerpo[^1]
[^1]: Contenido de la nota
### Tachado
Eliminar
### Enlaces automáticos
Las URL se convierten automáticamente en enlaces.
## Consejos de escritura
### Jerarquía de encabezados clara
- Encabezado de nivel 1: título del artículo
- Encabezado de nivel 2: secciones principales
- Encabezado de nivel 3: subsecciones
- No saltes niveles (de 1 directamente a 3)
### Párrafos concisos
- Un párrafo, una idea
- No demasiado largo (3-5 líneas ideal)
- Usa listas en lugar de párrafos largos
### Aprovecha las listas
El contenido paralelo es más claro en listas que en párrafos:
- Pasos: lista ordenada
- Elementos paralelos: lista no ordenada
- Comparaciones: tabla
### Indica el lenguaje en el código
Al marcar el lenguaje en el bloque de código se activa el resaltado de sintaxis:
Añade descripciones a las imágenes
La descripción en  es importante:
- Se muestra si la imagen no carga
- Los lectores de pantalla leen la descripción a usuarios con discapacidad visual
- Beneficia el SEO
Enlaces claros
- El texto del enlace describe el destino, evita "haz clic aquí"
- Enlaces externos: URL completa
- Enlaces internos: ruta relativa
Organización del documento
Índice al inicio
En documentos largos, coloca un índice al principio que enlace a cada sección. Facilita la navegación.
Separa secciones con encabezados
Separa las secciones con encabezados, no con líneas divisorias. Los encabezados tienen jerarquía, las líneas divisorias no.
Separa el código del texto
Deja líneas en blanco antes y después de los bloques de código para separarlos del cuerpo. La lectura es más clara.
Imágenes en el lugar adecuado
Coloca las imágenes junto al texto relacionado, no todas al final. El lector puede verlas a tiempo al leer en orden.
Elección de editor
VS Code
- Gratuito, potente
- Instala plugins de Markdown (p. ej. Markdown All in One)
- Vista previa en tiempo real
- Adecuado para desarrolladores
Typora
- WYSIWYG (lo que ves es lo que editas)
- Sin ventana de vista previa, editas directamente el resultado renderizado
- De pago pero económico
- Ideal para escritura concentrada
Obsidian
- Base de conocimiento local
- Enlaces bidireccionales
- Plugins abundantes
- Adecuado para notas y gestión de conocimiento
Editores en línea
- StackEdit: editor Markdown en línea
- Jianshu: plataforma de escritura en chino
- Adecuado para escritura temporal
Convertir Markdown a HTML
Tras escribir en Markdown, para mostrarlo en la web conviértelo a HTML. Usa la herramienta Markdown a HTML para convertir en un clic.
Errores comunes
Sin espacio después del encabezado
#Encabezado no se reconoce. Escribe # Encabezado (espacio después de #).
Sangría de lista incorrecta
Las sublistas necesitan sangría de 2 o 4 espacios (según el parser). Si la sangría es incorrecta, la sublista no se muestra.
Bloque de código sin cerrar
Marca el inicio y el final con ```. Si falta el cierre, todo el código posterior se convierte en bloque de código.
Caracteres especiales sin escapar
Para mostrar símbolos como * # añade \ delante para escapar: \* muestra *.
Error de sintaxis en tablas
Las tablas necesitan una fila separadora de encabezado (| --- |). Sin ella no se reconoce como tabla.
Paréntesis de enlace sin coincidir
Si falta el paréntesis de cierre en [enlace](url, el enlace no se reconoce.
Mejores prácticas
Un documento, un tema
Un artículo trata un tema. Divide varios temas en varios artículos y conéctalos con enlaces.
Contenido primero, formato después
Escribe primero el texto puro y añade después el marcado Markdown. Ajustar el formato mientras escribes interrumpe el flujo.
Unifica el estilo
Al escribir en equipo, unifica el estilo:
- Cuántos niveles de encabezado
- Listas con - o *
- Indicación de lenguaje en bloques de código
- Niveles máximos de anidamiento de listas
Conserva el archivo fuente
Markdown es el archivo fuente, HTML/PDF son productos generados. Conservar Markdown facilita la edición y el formato de salida se regenera cada vez.
Resumen
Lo esencial de escribir en Markdown: jerarquía de encabezados clara, párrafos concisos, aprovechar las listas, indicar el lenguaje del código, añadir descripciones a las imágenes. Elige un editor adecuado, unifica el estilo y conserva el archivo fuente. Para mostrarlo usa la herramienta Markdown a HTML de DocsAll, que se ejecuta en el navegador.