---
name: extract_pdf_bookmarks
kind: function
lang: py
domain: core
version: "1.0.0"
purity: impure
signature: "def extract_pdf_bookmarks(pdf) -> list[dict]"
description: "Extrae la estructura de bookmarks/outlines de un PDF abierto con pdfplumber. Retorna lista de dicts con level (1-6), title y page_num."
tags: [pdf, bookmarks, outlines, parsing, pdfplumber]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [pdfplumber]
params:
  - name: pdf
    desc: "objeto pdfplumber.PDF abierto"
output: "lista de dicts con campos level (1-6), title y page_num para cada bookmark"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/core/extract_pdf_bookmarks.py"
---

## Ejemplo

```python
import pdfplumber
from extract_pdf_bookmarks import extract_pdf_bookmarks

with pdfplumber.open("document.pdf") as pdf:
    bookmarks = extract_pdf_bookmarks(pdf)
    for bm in bookmarks:
        print(f"{'#' * bm['level']} {bm['title']} (page {bm['page_num']})")
```

## Notas

Recibe un objeto `pdfplumber.PDF` ya abierto (no un path). Construye un mapping interno `objid -> page_number` desde `pdf.pages` para resolver los destinos de outline. El nivel se limita al rango [1, 6] para compatibilidad markdown. Retorna lista vacia si el PDF no tiene outlines o si `get_outlines()` falla. Impure porque accede al estado interno de un objeto PDF ya abierto.
