---
name: docx_to_markdown
kind: function
lang: py
domain: core
version: "1.0.0"
purity: impure
signature: "docx_to_markdown(docx_path: str) -> str"
description: "Convierte un documento Word (.docx) a markdown preservando estructura (headings), formato inline (bold, italic, underline) y tablas en su posicion original."
tags: [docx, markdown, word, conversion, document, parsing, text, pendiente-usar]
uses_functions: [format_table_to_markdown_py_core]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [python-docx, lxml]
params:
  - name: docx_path
    desc: "ruta al archivo Word .docx"
output: "string markdown con headings, parrafos formateados y tablas preservadas"
tested: true
tests: ["docx con headings y parrafos", "docx con tablas intercaladas", "docx con formato bold/italic", "docx vacio", "archivo no encontrado lanza FileNotFoundError"]
test_file_path: "python/functions/core/docx_to_markdown_test.py"
file_path: "python/functions/core/docx_to_markdown.py"
---

## Ejemplo

```python
md = docx_to_markdown("informe.docx")
# # Titulo
#
# Primer parrafo.
#
# | Col1 | Col2 |
# | ---- | ---- |
# | a    | b    |
#
# Parrafo despues de la tabla.
```

## Notas

Recorre `doc.element.body` en orden (no `doc.paragraphs` + `doc.tables` por separado) para preservar la posicion original de las tablas. Construye un mapa `{id(tbl_element): Table}` para lookup O(1). El formato inline aplica underline (`<ins>`), italic (`*`) y bold (`**`) en ese orden de mas interno a mas externo. Los headings se detectan por el estilo del parrafo (`Heading 1`, `Heading 2`, etc.). Requiere `python-docx` instalado en el entorno.
