---
name: pdf_to_markdown
kind: function
lang: py
domain: core
version: "1.0.0"
purity: impure
signature: "def pdf_to_markdown(pdf_path: str, heading_detection: str = 'auto') -> tuple[str, dict]"
description: "Convierte un PDF a markdown. Extrae texto, tablas e inyecta headings detectados desde bookmarks o analisis de fuentes. Retorna (markdown_content, metadata_dict)."
tags: [pdf, markdown, conversion, headings, tables, pdfplumber, parsing]
uses_functions: [extract_pdf_bookmarks_py_core, detect_headings_by_font_py_core, format_table_to_markdown_py_core]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [pdfplumber, os, sys]
params:
  - name: pdf_path
    desc: "Ruta al archivo PDF a convertir"
  - name: heading_detection
    desc: "Estrategia de detección de headings: 'auto', 'bookmarks', 'font'"
output: "Tupla (markdown_content, metadata_dict) con el PDF convertido a markdown y metadatos"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/core/pdf_to_markdown.py"
---

## Ejemplo

```python
from pdf_to_markdown import pdf_to_markdown

md, meta = pdf_to_markdown("report.pdf")
print(f"Pages: {meta['pages']}, Headings: {meta['headings_found']}, Tables: {meta['tables_found']}")
print(md[:500])

# Con estrategia especifica
md, meta = pdf_to_markdown("report.pdf", heading_detection="font")
print(f"Strategy used: {meta['heading_strategy']}")
```

## Notas

Estrategias de heading_detection:
- `"bookmarks"`: extrae outlines/bookmarks del PDF via pdfplumber. Rapido y preciso cuando el PDF tiene bookmarks bien formados.
- `"font"`: analiza distribucion de font sizes para detectar headings. Util para PDFs sin bookmarks.
- `"auto"`: intenta bookmarks primero; si no hay, usa analisis de font. Estrategia por defecto.

El metadata_dict retornado contiene: `pages` (int), `heading_strategy` (str: "bookmarks"|"font"|"none"), `headings_found` (int), `tables_found` (int).

Tablas se extraen via `page.extract_tables()` de pdfplumber y se formatean como tablas markdown. Requiere `pip install pdfplumber`.
