Problemas al convertir Markdown: tablas, código e imágenes

Escribiste tu Markdown con cuidado. Le diste a "Convertir". Y el resultado no tiene nada que ver con lo que esperabas: las tablas están destrozadas, los bloques de código aparecen como texto plano, las imágenes no se ven y tus fórmulas LaTeX se convirtieron en texto sin sentido.

Después de ayudar a miles de usuarios a convertir Markdown a Word, PDF y HTML con MarkFlow, hemos recopilado los fallos de conversión más habituales y sus soluciones. Esta guía cubre 15 problemas reales con soluciones concretas, sin rodeos.

Referencia rápida: problema y solución

---

Problemas con tablas

Problema 1: Las columnas de la tabla se desalinean o fusionan en Word

Lo que ves: Tu tabla Markdown, que se veía perfecta en el editor, se convierte en un desastre en Word: columnas fusionadas, contenido que se desborda o la estructura de la tabla desaparece por completo.

Por qué ocurre:

La causa más común es una sintaxis de tabla inválida. Las tablas Markdown son sorprendentemente estrictas. Un solo carácter de pipe faltante o una fila de separadores desalineada rompe toda la tabla.

Esto es lo que suele salir mal:

<!-- MAL: Falta el pipe inicial -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2

<!-- MAL: La fila de separadores no coincide con el número de columnas -->
| Header 1 | Header 2 | Header 3 |
| --- | --- |
| Cell 1 | Cell 2 | Cell 3 |

Cómo solucionarlo:

Usa siempre una sintaxis de pipes consistente con el mismo número de columnas:

| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|----------:|
| Left     | Center   | Right     |
| Cell 1   | Cell 2   | Cell 3    |

Reglas clave:

• Empieza y termina cada fila con un pipe |
• La fila de separadores debe tener el mismo número de columnas que la cabecera
• Usa los dos puntos para alinear — :--- izquierda, :---: centro, ---: derecha
• No uses celdas combinadas — Markdown estándar no las soporta. Si necesitas combinar celdas, edita el documento Word manualmente después de la conversión

Consejo: Antes de convertir, pega tu tabla en un linter de Markdown o en una herramienta de vista previa. La mayoría de editores (VS Code, Typora, Obsidian) te muestran inmediatamente si la tabla tiene errores.

---

Problema 2: El ancho de las columnas es desigual en el Word generado

Lo que ves: La tabla se renderiza bien en tu editor Markdown, pero después de convertirla a Word, una columna ocupa el 80% del ancho de página mientras las demás quedan apretadas.

Por qué ocurre:

La mayoría de conversores de Markdown a Word calculan el ancho de columna según la longitud del contenido. Si una celda contiene una frase larga o una URL mientras las demás tienen valores cortos, la distribución queda desbalanceada. A diferencia de HTML, Markdown no tiene sintaxis para especificar anchos de columna.

Cómo solucionarlo:

• Mantén el contenido de las celdas breve. Mueve descripciones largas a notas al pie o párrafos separados debajo de la tabla
• Acorta las URLs largas con texto de enlace: Usa [Texto del enlace](url) en vez de pegar URLs directamente en las celdas
• Usa MarkFlow para la conversión — aplica distribución equilibrada de columnas por defecto, generando tablas en Word más legibles que la mayoría de conversores

Si necesitas anchos de columna precisos, edita la tabla en Word después de la conversión: selecciona la tabla, ve a Propiedades de tabla, pestaña Columna, y establece el ancho deseado.

---

Problema 3: Contenido con caracteres especiales rompe el renderizado de la tabla

Lo que ves: Los caracteres de pipe | dentro de las celdas rompen la estructura de columnas, o las entidades HTML se renderizan como texto sin procesar.

Por qué ocurre:

El carácter pipe | es el delimitador de columnas en las tablas Markdown. Cuando el contenido de tu celda contiene un pipe literal, el parser lo interpreta como un límite de columna.

Cómo solucionarlo:

Escapa el carácter pipe con una barra invertida:

| Comando | Descripción |
|:--------|:------------|
| `echo "a \| b"` | Redirige la salida a través del filtro |
| `status: pass\|fail` | Muestra estado de éxito o fallo |

Para otros caracteres especiales en celdas de tabla:

• Usa \| para caracteres pipe literales
• Usa entidades HTML como & para ampersands si es necesario
• Envuelve el contenido con backticks de código en línea para evitar la interpretación de Markdown

---

Problemas con bloques de código

Problema 4: Los bloques de código pierden el resaltado de sintaxis tras la conversión

Lo que ves: Tu código Python o JavaScript, que se veía perfecto con colores, se convierte en texto plano monocromático en el documento Word.

Por qué ocurre:

Dos causas frecuentes:

1. No especificaste el lenguaje — Usaste triple backtick sin indicar el lenguaje
2. El conversor no soporta resaltado — Muchos conversores básicos eliminan el resaltado de sintaxis durante la exportación a Word/PDF

La diferencia es clara:

<!-- SIN resaltado — falta la etiqueta de lenguaje -->
```
function hello() {
  console.log("Hello");
}
```

<!-- CON resaltado — lenguaje especificado -->
```javascript
function hello() {
  console.log("Hello");
}
```

Cómo solucionarlo:

Especifica siempre el lenguaje después de los triple backticks de apertura. Identificadores comunes:

Si tu conversor sigue sin producir código con resaltado, MarkFlow conserva el resaltado de sintaxis tanto en Word como en PDF — el código aparece con colores, tipografía y sangría correctos.

---

Problema 5: El formato de código en línea desaparece

Lo que ves: El texto envuelto en backticks simples como config.yaml o npm install aparece como texto normal en el documento convertido, sin ninguna distinción visual.

Por qué ocurre:

Algunos conversores tratan el código en línea como texto plano y no aplican ningún estilo. La sintaxis de backtick se reconoce, pero el formato de salida no incluye fuente monoespaciada ni color de fondo.

Cómo solucionarlo:

• Usa un conversor que respete el estilo de código en línea. MarkFlow renderiza el código en línea con fuente monoespaciada y un fondo sutil en la salida Word
• Evita backticks anidados en código en línea. Si tu código contiene backticks, usa backticks dobles: `code with `backtick` se escribe como ``code with `backtick` ``
• No abuses del código en línea para dar énfasis — usa negrita o cursiva en su lugar. Reserva los backticks para código real, comandos, nombres de archivo e identificadores técnicos

---

Problema 6: La indentación y los espacios en blanco del código son incorrectos

Lo que ves: Los bloques de código en la salida Word tienen indentación incorrecta: o todo está alineado a la izquierda, o las tabulaciones se convirtieron en espaciado inconsistente.

Por qué ocurre:

La conversión de tabulaciones a espacios difiere entre los parsers de Markdown y el motor de renderizado de Word. Algunos conversores también eliminan los espacios iniciales o colapsan múltiples espacios en uno solo.

Cómo solucionarlo:

• Usa espacios, no tabulaciones, en tus bloques de código Markdown. La mayoría de guías de estilo recomiendan 2 o 4 espacios. Las tabulaciones se interpretan de forma inconsistente entre conversores
• Usa bloques de código delimitados (triple backtick) en vez de bloques de código indentados (4 espacios). Los bloques delimitados se parsean de forma más fiable:

<!-- PREFERIDO: Bloque de código delimitado -->
```python
def nested():
    if True:
        for i in range(10):
            print(i)
```

<!-- EVITAR: Bloque de código indentado (4 espacios) -->
    def nested():
        if True:
            for i in range(10):
                print(i)

• Revisa la salida inmediatamente después de convertir. Si los espacios están mal, el problema está en el conversor, no en tu Markdown. Prueba con otra herramienta o reporta el bug

---

Problemas con imágenes

Problema 7: Las imágenes no se muestran tras la conversión

Lo que ves: El documento Word o PDF convertido muestra iconos de imagen rota, espacios vacíos o el texto alternativo en lugar de la imagen real.

Por qué ocurre:

Este es el problema de conversión número uno, y casi siempre se reduce a las rutas de imagen:

1. Rutas relativas que el conversor no puede resolver — ![Alt](./images/foto.png) funciona en tu editor porque sabe dónde está el archivo. El conversor puede que no
2. URLs remotas que requieren autenticación — Las imágenes en repos privados de GitHub, Google Drive o Notion no se descargan durante la conversión
3. Problemas de protocolo — Algunos conversores no manejan rutas file:// o rutas absolutas locales
4. Formato de archivo no soportado — Ciertos conversores tienen problemas con SVG, WebP o TIFF

Cómo solucionarlo:

Para un enfoque fiable, usa URLs de imagen accesibles públicamente:

<!-- Más fiable: URL absoluta -->
![Diagrama de arquitectura](https://tu-dominio.com/images/diagrama.png)

<!-- También fiable: embedding base64 (para imágenes pequeñas) -->
![Icono](data:image/png;base64,iVBORw0KGgo...)

Con MarkFlow: Arrastra y suelta tu archivo .md junto con su carpeta de imágenes — las rutas relativas se resuelven automáticamente. También puedes pegar Markdown con URLs de imágenes y se incrustarán en la salida Word.

---

Problema 8: Las imágenes son demasiado grandes o demasiado pequeñas en Word

Lo que ves: Una imagen que se ve perfecta en la vista previa de Markdown aparece diminuta o enorme en el documento Word convertido, rompiendo el diseño de la página.

Por qué ocurre:

Markdown no tiene sintaxis nativa para dimensionar imágenes. El formato ![alt](url) no acepta parámetros de ancho o alto. La mayoría de conversores insertan las imágenes en sus dimensiones originales de píxeles, que pueden no coincidir con el ancho de página de Word.

Cómo solucionarlo:

Algunos sabores de Markdown soportan el dimensionado de imágenes a través de HTML:

<!-- Controla el tamaño con HTML -->
<img src="./diagrama.png" alt="Diagrama de arquitectura del sistema" width="600" />

Sin embargo, no todos los conversores de Markdown a Word procesan etiquetas HTML. Tus opciones:

• Redimensiona la imagen original a aproximadamente 600-800px de ancho antes de añadirla a tu Markdown — esto se ajusta a la mayoría de diseños de página en Word
• Usa etiquetas HTML img con width si tu conversor soporta HTML en línea
• Redimensiona después de la conversión en Word: haz clic derecho en la imagen, selecciona Tamaño y posición, y establece el ancho deseado

Dimensiones recomendadas para salida Word:

• Imágenes a ancho completo: 600-800px de ancho
• Diagramas en línea: 400-500px de ancho
• Iconos o insignias: 100-200px de ancho

---

Problema 9: Las imágenes embebidas en base64 no se convierten

Lo que ves: Las imágenes codificadas como data URIs base64 en tu Markdown funcionan en la vista previa pero aparecen rotas o se eliminan por completo en el documento convertido.

Por qué ocurre:

Las imágenes codificadas en base64 aumentan significativamente el tamaño del archivo (aproximadamente un 33% más que el binario). Algunos conversores tienen límites de tamaño para data URIs inline, o simplemente no parsean el formato data:image/...;base64,....

Cómo solucionarlo:

• Mantén las imágenes base64 pequeñas — menos de 100KB codificadas (unos 75KB en binario original). Iconos y logos pequeños funcionan bien; capturas de pantalla y fotos normalmente no
• Usa archivos de imagen reales para contenido grande. Alójalos o inclúyelos junto a tu archivo .md
• Revisa la documentación de tu conversor sobre soporte de data URIs. MarkFlow maneja imágenes embebidas en base64 tanto en Word como en PDF, pero hay un límite práctico de unos 2MB por imagen

---

Problemas con fórmulas LaTeX y diagramas Mermaid

Problema 10: Las fórmulas LaTeX se muestran como texto plano

Lo que ves: En lugar de una ecuación correctamente renderizada, el documento Word muestra el código fuente LaTeX tal cual: $E = mc^2$ o $$\int_{0}^{1} x^2 dx$$ como texto literal.

Por qué ocurre:

El soporte de fórmulas LaTeX no forma parte del Markdown estándar ni de GFM. Es una extensión que requiere motores de renderizado específicos (KaTeX o MathJax). La mayoría de conversores Markdown básicos — incluyendo Pandoc sin los flags adecuados, VS Code sin extensiones y Dillinger — no procesan la sintaxis LaTeX.

Cómo solucionarlo:

Primero, verifica que tu sintaxis sea correcta:

<!-- Fórmula en línea: signos de dólar simples -->
La fórmula $E = mc^2$ describe la equivalencia masa-energía.

<!-- Fórmula en bloque: signos de dólar dobles -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Luego, usa un conversor que soporte LaTeX:

Errores comunes de LaTeX que causan fallos de renderizado:

<!-- MAL: Espacio después del $ de apertura -->
$ E = mc^2 $

<!-- BIEN: Sin espacio después del $ de apertura -->
$E = mc^2$

<!-- MAL: Falta el delimitador de cierre -->
$$\int_{0}^{1} x^2 dx

<!-- BIEN: Delimitadores coincidentes -->
$$\int_{0}^{1} x^2 dx$$

---

Problema 11: Los diagramas Mermaid no aparecen en la salida

Lo que ves: En lugar de un diagrama de flujo o secuencia renderizado, la salida Word/PDF muestra el código Mermaid como un bloque de código normal.

Por qué ocurre:

Mermaid es un motor de renderizado basado en JavaScript. Necesita un navegador o un entorno Node.js para generar el diagrama visual. La mayoría de conversores de Markdown a Word procesan el Markdown como texto puro y no ejecutan JavaScript, así que tratan los bloques Mermaid como código ordinario.

Cómo solucionarlo:

Verifica primero tu sintaxis Mermaid:

```mermaid
graph TD
    A[Inicio] --> B{Decisión}
    B -->|Sí| C[Acción 1]
    B -->|No| D[Acción 2]
    C --> E[Fin]
    D --> E
```

Herramientas que renderizan Mermaid a Word/PDF:

• MarkFlow — Renderiza diagramas Mermaid como imágenes incrustadas en la salida Word
• Typora — Renderiza Mermaid en vista previa y exporta a PDF
• Pandoc — Requiere el plugin mermaid-filter (npm install -g mermaid-filter)

Alternativa para conversores sin soporte Mermaid:

1. Usa el Editor en Vivo de Mermaid para renderizar tu diagrama
2. Expórtalo como PNG o SVG
3. Reemplaza el bloque de código Mermaid por una referencia a la imagen en tu Markdown
4. Convierte como de costumbre

Esto añade un paso manual, pero garantiza que el diagrama aparezca con cualquier conversor.

---

Problemas de formato y estructura

Problema 12: Los niveles de encabezado son incorrectos en Word

Lo que ves: La jerarquía de encabezados en Word no coincide con tu Markdown. Los H2 aparecen como H1, o todos los encabezados se renderizan al mismo tamaño.

Por qué ocurre:

Dos causas habituales:

1. Múltiples encabezados H1 en tu Markdown. Un documento debería tener un solo H1 (el título). Algunos conversores fusionan o remapean encabezados cuando detectan múltiples H1
2. El conversor mapea los encabezados Markdown a estilos de Word de forma diferente. Algunas herramientas tratan el primer encabezado como título del documento independientemente de su nivel

Cómo solucionarlo:

Sigue una jerarquía de encabezados correcta:

# Título del documento (H1 — usa exactamente una vez)

## Título de sección (H2 — secciones principales)

### Subsección (H3 — dentro de secciones)

#### Detalle (H4 — rara vez necesario)

• Nunca te saltes niveles — no vayas de H2 directamente a H4
• Usa H1 solo una vez al inicio de tu documento, o deja que el conversor lo añada desde los metadatos del título
• Revisa el panel de Estilos de Word — los encabezados deberían aparecer como "Título 1", "Título 2", etc. Si muestran "Normal", el conversor no los mapeó correctamente

---

Problema 13: Las listas anidadas pierden su indentación

Lo que ves: Tu lista con viñetas o numerada cuidadosamente anidada aparece completamente plana en la salida Word — todos los elementos al mismo nivel.

Por qué ocurre:

La indentación inconsistente es la culpable. Markdown requiere espaciado consistente para detectar niveles de anidamiento. Mezclar tabulaciones y espacios, o usar 2 espacios en un lugar y 3 en otro, confunde al parser.

Cómo solucionarlo:

Usa 4 espacios (o 1 tabulación) por nivel de anidamiento, de forma consistente:

- Elemento de primer nivel
    - Elemento de segundo nivel
        - Elemento de tercer nivel
    - Vuelve al segundo nivel
- Vuelve al primer nivel

1. Primer elemento
    1. Sub-elemento uno
    2. Sub-elemento dos
2. Segundo elemento
    - Viñeta mixta bajo número

Errores comunes:

<!-- MAL: Indentación inconsistente (2 espacios y luego 3) -->
- Elemento A
  - Sub A (2 espacios)
   - Sub B (3 espacios — el parser se confunde)

<!-- BIEN: Indentación consistente de 4 espacios -->
- Elemento A
    - Sub A
    - Sub B

Si tu conversor sigue aplanando las listas, prueba cambiando de herramienta. MarkFlow conserva la indentación de listas anidadas en la salida Word, incluyendo listas mixtas ordenadas/desordenadas.

---

Problema 14: Las notas al pie desaparecen o se rompen

Lo que ves: Las referencias de notas al pie como [^1] aparecen como texto literal en el documento convertido, y el contenido de la nota al final de tu Markdown falta o se renderiza como un párrafo normal.

Por qué ocurre:

Las notas al pie son una extensión de GFM, no forman parte de la especificación original de Markdown. Los conversores que solo soportan Markdown básico no procesarán la sintaxis de footnotes.

Cómo solucionarlo:

Sintaxis correcta de notas al pie:

Esta afirmación necesita una fuente[^1]. Otro punto aquí[^nota].

[^1]: García, J. (2025). "Título del artículo de investigación." Nombre de la revista.
[^nota]: Esta es una nota al pie más larga con varias frases.
    Indenta las líneas de continuación con 4 espacios.

Verifica que:

• La referencia [^id] y la definición [^id]: usen el mismo identificador
• Las definiciones de notas al pie estén al final del documento (o al menos después de todas las referencias)
• Tu conversor soporte notas al pie de GFM — MarkFlow, Pandoc y Typora las manejan correctamente

---

Problema 15: Los caracteres emoji se ven como cuadrados vacíos

Lo que ves: Los emoji como marcas de verificación, cohetes o señales de advertencia aparecen como rectángulos vacíos o signos de interrogación en la salida Word.

Por qué ocurre:

El documento Word usa una fuente que no incluye glifos emoji. Cuando el conversor mapea el texto Markdown a Word, aplica una fuente estándar (como Calibri o Times New Roman) que puede no contener caracteres emoji Unicode.

Cómo solucionarlo:

• Después de la conversión: Selecciona los caracteres emoji en Word, cambia su fuente a "Segoe UI Emoji" (Windows) o "Apple Color Emoji" (macOS)
• Antes de la conversión: Si el renderizado de emoji es crítico, considera reemplazarlos con equivalentes de texto o imágenes
• Usa un conversor que maneje fuentes emoji: MarkFlow mapea los caracteres emoji a la fuente del sistema apropiada en la salida Word

---

Prevención: cómo evitar problemas de conversión

La mayoría de problemas de conversión son evitables. Incorpora estos hábitos a tu flujo de trabajo con Markdown.

Valida antes de convertir

Usa un linter de Markdown para detectar errores de sintaxis antes de que se conviertan en problemas de conversión:

# Instala markdownlint CLI
npm install -g markdownlint-cli

# Analiza tu archivo
markdownlint documento.md

Si usas VS Code: instala la extensión "markdownlint" para validación en tiempo real.

Usa una vista previa que coincida con tu formato de salida

La vista previa de tu editor y la salida del conversor usan motores de renderizado diferentes. Lo que se ve bien en VS Code puede romperse en Word. Haz siempre una conversión de prueba antes de la exportación final.

Estandariza tu estilo Markdown

Elige convenciones y mantenlas:

• Indentación: 4 espacios para anidar
• Saltos de línea: Una línea en blanco entre bloques
• Bloques de código: Siempre delimitados (no indentados), siempre con etiqueta de lenguaje
• Imágenes: Formato de ruta consistente (todas relativas o todas absolutas)
• Tablas: Pipes al inicio y al final en cada fila

Si eres nuevo con las convenciones de Markdown, nuestra guía de sintaxis básica de Markdown cubre cada elemento en detalle. Para funcionalidades avanzadas como notas al pie y listas de tareas, consulta la guía de sintaxis extendida.

Mantén un documento de prueba

Ten un archivo Markdown con un ejemplo de cada elemento que uses — tablas, bloques de código, fórmulas, diagramas, listas anidadas, notas al pie, emoji. Pásalo por tu conversor cada vez que actualices herramientas. Esto detecta regresiones antes de que afecten documentos reales.

---

Cuándo usar cada conversor

Diferentes herramientas resuelven diferentes problemas:

---

Preguntas frecuentes

P: ¿Por qué mi tabla Markdown se rompe al convertir a Word? R: La causa más común es una sintaxis de pipes inconsistente — pipes iniciales/finales faltantes o una fila de separadores que no coincide con el número de columnas. Valida la sintaxis de tu tabla en una vista previa de Markdown antes de convertir.

P: ¿Cómo mantengo el resaltado de sintaxis en bloques de código al convertir a Word? R: Especifica siempre el lenguaje después de los triple backticks de apertura (por ejemplo, ```python). Luego usa un conversor como MarkFlow que conserve el resaltado en la salida Word.

P: ¿Por qué faltan mis imágenes después de convertir Markdown a Word? R: El conversor no puede resolver las rutas de tus imágenes. Usa URLs absolutas para imágenes remotas, o usa una herramienta como MarkFlow que maneja rutas relativas cuando subes tu archivo .md con su carpeta de imágenes.

P: ¿Puedo convertir fórmulas LaTeX a Word sin perder el formato? R: Sí, pero necesitas un conversor con soporte LaTeX. MarkFlow, Pandoc (con flags de matemáticas) y Typora renderizan LaTeX correctamente. Los conversores básicos mostrarán el código fuente LaTeX como texto plano.

P: ¿Por qué los diagramas Mermaid aparecen como código en mi documento convertido? R: La mayoría de conversores no ejecutan JavaScript, que es lo que Mermaid necesita. Usa MarkFlow para renderizado automático de Mermaid, o pre-renderiza los diagramas como imágenes usando el Editor en Vivo de Mermaid.

P: ¿Cómo corrijo la indentación de listas anidadas en la salida Word? R: Usa exactamente 4 espacios por nivel de anidamiento en tu Markdown. Evita mezclar tabulaciones y espacios. Si el problema persiste, prueba con otro conversor — algunos manejan las listas anidadas mejor que otros.

---

Recursos relacionados

• Conversor de Markdown a Word — Convierte con soporte completo de formato
• Conversor de Markdown a PDF — Genera PDFs listos para imprimir
• Conversor de Markdown a HTML — Exporta HTML limpio y semántico
• Guía de sintaxis básica de Markdown — Domina los fundamentos
• Guía de sintaxis extendida de Markdown — Funcionalidades avanzadas y extensiones GFM
• Guía completa de Markdown a Word — Flujo de trabajo completo de conversión