---
name: excel_to_markdown
kind: function
lang: py
domain: core
version: "1.0.0"
purity: impure
signature: "excel_to_markdown(path: str, max_rows_per_sheet: int = 1000) -> str"
description: "Convierte un archivo Excel (.xlsx, .xls, .xlsm) a markdown con cada sheet como seccion H2. Soporta tipos de celda: fechas ISO, booleanos, errores Excel, numeros enteros y flotantes. Trunca sheets que superen max_rows_per_sheet."
tags: [excel, markdown, xlsx, xls, conversion, parser, io]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["openpyxl", "xlrd"]
params:
  - name: path
    desc: "ruta al archivo Excel (.xlsx, .xls, .xlsm)"
  - name: max_rows_per_sheet
    desc: "limite maximo de filas a procesar por sheet"
output: "string markdown con cada sheet como seccion H2 y sus datos en tablas"
tested: true
tests:
  - "xlsx con multiples sheets produce una seccion H2 por sheet"
  - "sheet vacio produce nota de sheet vacio"
  - "sheet truncado con nota de filas omitidas"
  - "sheet con formulas data_only muestra valores calculados"
  - "extension no soportada lanza ValueError"
  - "archivo inexistente lanza FileNotFoundError"
  - "dimensiones del sheet en metadata"
  - "tabla markdown con formato correcto"
test_file_path: "python/functions/core/excel_to_markdown_test.py"
file_path: "python/functions/core/excel_to_markdown.py"
---

## Ejemplo

```python
from excel_to_markdown import excel_to_markdown

md = excel_to_markdown("report.xlsx")
print(md)
# ## Sheet: Ventas
#
# **Dimensions:** 101 x 4
#
# | Producto | Precio | Cantidad | Total |
# | --- | --- | --- | --- |
# | Manzana | 1 | 100 | 100 |
# ...

# Con limite de filas
md = excel_to_markdown("big_file.xlsx", max_rows_per_sheet=50)
```

## Notas

- `.xlsx` y `.xlsm`: usa `openpyxl` con `data_only=True` (lee valores calculados, no formulas).
- `.xls` (legacy): usa `xlrd`. Manejo de tipos especiales: EMPTY/BLANK → "", DATE → ISO 8601, BOOLEAN → "TRUE"/"FALSE", ERROR → codigo Excel (#NULL!, #DIV/0!, etc.), NUMBER → entero si no tiene decimales.
- Fechas sin hora se formatean como `YYYY-MM-DD`; con hora como `YYYY-MM-DDTHH:MM:SS`.
- Los pipes `|` dentro de celdas se escapan como `\|`.
- Si `xlwt` no esta disponible, los tests .xls se saltan (xlwt solo se necesita para crear fixtures, no para leer).
- Reimplementacion desde cero, inspirada conceptualmente en OpenViking (AGPL-3.0). Sin codigo copiado.
