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.

¿Te suena familiar? La conversión de Markdown a Word y PDF suele fallar de la misma pequeña lista de formas. Esta guía cubre los 15 problemas más frecuentes — cada uno con su causa real y una solución concreta.

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:

<!-- BROKEN: Missing leading pipe -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2

<!-- BROKEN: Separator row doesn't match column count -->
| 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 [Link text](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 → Propiedades de tabla → pestaña Columna → 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:

| Command | Description |
|:--------|:------------|
| `echo "a \| b"` | Pipes output through filter |
| `status: pass\|fail` | Shows pass or fail status |

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:

<!-- NO highlighting — missing language tag -->
```
function hello() {
  console.log("Hello");
}
```

<!-- WITH highlighting — language specified -->
```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, distinguiéndolo visualmente del texto que lo rodea
• Evita backticks anidados en código en línea. Si tu código contiene backticks, usa backticks dobles: `code with `backtick` → usa ``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:

<!-- PREFERRED: Fenced code block -->
```python
def nested():
    if True:
        for i in range(10):
            print(i)
```

<!-- AVOID: Indented code block (4 spaces) -->
    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/photo.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:

<!-- Most reliable: absolute URL -->
![Architecture diagram](https://your-domain.com/images/diagram.png)

<!-- Also reliable: base64 embedding (for small images) -->
![Icon](data:image/png;base64,iVBORw0KGgo...)

Con MarkFlow: Arrastra y suelta tu archivo .md junto con su carpeta de imágenes — MarkFlow resuelve las rutas relativas 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:

<!-- Control image size with HTML -->
<img src="./diagram.png" alt="System architecture" 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 → Tamaño y posición → establece el ancho al porcentaje 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:

<!-- Inline math: single dollar signs -->
The formula $E = mc^2$ describes mass-energy equivalence.

<!-- Block math: double dollar signs -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Luego, usa un conversor que soporte LaTeX:

Errores comunes de LaTeX que causan fallos de renderizado:

<!-- WRONG: Space after opening $ -->
$ E = mc^2 $

<!-- CORRECT: No space after opening $ -->
$E = mc^2$

<!-- WRONG: Missing closing delimiter -->
$$\int_{0}^{1} x^2 dx

<!-- CORRECT: Matching delimiters -->
$$\int_{0}^{1} x^2 dx$$

Para artículos académicos y documentación técnica, MarkFlow renderiza el LaTeX como imágenes de fórmulas reales en la salida Word — así tus ecuaciones se ven correctas incluso en versiones de Word que no soportan editores de ecuaciones.

---

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[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Herramientas que renderizan Mermaid a Word/PDF:

• MarkFlow — Renderiza diagramas Mermaid como imágenes incrustadas en la salida Word. Soporta diagramas de flujo, de secuencia, de Gantt y más
• 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 Mermaid Live Editor 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:

# Document Title (H1 — use exactly once)

## Section Title (H2 — main sections)

### Subsection (H3 — within sections)

#### Detail (H4 — rarely needed)

• 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:

- First level item
    - Second level item
        - Third level item
    - Back to second level
- Back to first level

1. First item
    1. Sub-item one
    2. Sub-item two
2. Second item
    - Mixed bullet under number

Errores comunes:

<!-- BROKEN: Inconsistent indentation (2 spaces then 3) -->
- Item A
  - Sub A (2 spaces)
   - Sub B (3 spaces — parser gets confused)

<!-- FIXED: Consistent 4-space indentation -->
- Item 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:

This claim needs a source[^1]. Another point here[^note].

[^1]: Smith, J. (2025). "Research Paper Title." Journal Name.
[^note]: This is a longer footnote with multiple sentences.
    Indent continuation lines with 4 spaces.

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 ✅, 🚀 o ⚠️ 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, para que se rendericen correctamente tanto en Windows como en macOS

---

Prevención: cómo evitar problemas de conversión antes de que ocurran

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:

# Install markdownlint CLI
npm install -g markdownlint-cli

# Lint your file
markdownlint document.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

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:

Para una comparación detallada de herramientas de conversión, consulta nuestra comparación de conversores de Markdown a PDF.

---

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 Mermaid Live Editor.

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, incluyendo tablas, código y fórmulas
• Conversor de Markdown a PDF — Genera PDFs listos para imprimir desde Markdown
• Conversor de Markdown a HTML — Exporta HTML limpio y semántico
• Cómo escribir en Markdown — Domina la sintaxis para evitar problemas de conversión
• Guía de salida Markdown de ChatGPT — Obtén Markdown bien estructurado de herramientas de IA
• Mejores conversores de Markdown a PDF — Comparación detallada de herramientas