---
name: find_headings
kind: function
lang: py
domain: core
version: "1.0.0"
purity: pure
signature: "def find_headings(content: str) -> list[tuple[int, int, str, int]]"
description: "Encuentra todos los headings markdown (# a ######), excluyendo los que estan dentro de code blocks, HTML comments y bloques indentados. Retorna lista de (start_pos, end_pos, title, level)."
tags: [markdown, headings, parsing, extraction]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [re]
params:
  - name: content
    desc: "string con contenido markdown"
output: "lista de tuplas (start_pos, end_pos, title, level) para cada heading detectado"
tested: true
tests:
  - "headings normales detectados correctamente"
  - "headings dentro de code blocks no detectados"
  - "headings escapados ignorados"
  - "headings en HTML comments ignorados"
test_file_path: "python/functions/core/parse_markdown_test.py"
file_path: "python/functions/core/core.py"
---

## Ejemplo

```python
content = "# Title\n\nSome text\n\n## Section\n\n```\n# Ignored\n```\n"
headings = find_headings(content)
# [(0, 7, "Title", 1), (22, 33, "Section", 2)]
# (positions approximated)
```

## Notas

Funcion pura. Excluye tres tipos de contextos: bloques de codigo triple backtick, comentarios HTML (`<!-- ... -->`), y lineas indentadas con 4 espacios o tabulacion. Tambien filtra headings precedidos por backslash (`\#`). Diferencia clave respecto a `extract_markdown_headers`: esta funcion retorna posiciones de caracter, no numeros de linea, lo que facilita la extraccion de contenido entre headings.
