---
name: create_obsidian_note
kind: function
lang: py
domain: obsidian
version: "1.0.0"
purity: impure
signature: "def create_obsidian_note(vault_dir: str, rel_path: str, body: str = '', frontmatter: dict = None, overwrite: bool = False) -> str"
description: "Crea una nota Markdown nueva en un vault de Obsidian. Anade extension .md si falta, crea directorios padre, serializa frontmatter YAML + body con la funcion pura format_obsidian_note. Falla si la nota existe salvo overwrite=True. No depende de la app GUI de Obsidian: solo escribe un archivo .md plano en disco."
tags: [obsidian, markdown, frontmatter, create, write, notes]
uses_functions: ["format_obsidian_note_py_obsidian"]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["os"]
params:
  - name: vault_dir
    desc: "directorio raiz del vault de Obsidian donde se crea la nota"
  - name: rel_path
    desc: "ruta relativa de la nota dentro del vault; se le anade .md si no lo trae"
  - name: body
    desc: "cuerpo Markdown de la nota sin frontmatter (default cadena vacia)"
  - name: frontmatter
    desc: "dict con el frontmatter YAML a escribir; None se trata como {}"
  - name: overwrite
    desc: "si False (default) y la nota existe lanza FileExistsError; True sobreescribe"
output: "ruta absoluta (str) del archivo .md escrito"
tested: true
tests:
  - "crea nota con frontmatter y body"
  - "anade extension md si falta"
  - "crea directorios padre"
  - "existente sin overwrite lanza fileexistserror"
  - "overwrite true sobreescribe"
  - "destino directorio lanza isadirectoryerror"
test_file_path: "python/functions/obsidian/create_obsidian_note_test.py"
file_path: "python/functions/obsidian/create_obsidian_note.py"
---

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from obsidian import create_obsidian_note

path = create_obsidian_note(
    vault_dir="/home/me/vault",
    rel_path="Inbox/Idea rapida",          # se convierte en Inbox/Idea rapida.md
    body="Primer apunte. Ver [[Proyecto X]].",
    frontmatter={"title": "Idea rapida", "tags": ["inbox", "wip"]},
)
print(path)   # /home/me/vault/Inbox/Idea rapida.md
```

## Cuando usarla

Cuando quieras crear una nota nueva en un vault de Obsidian desde codigo o un agente: capturar una idea en el Inbox, generar notas a partir de datos, o materializar plantillas. Crea automaticamente los directorios padre, asi que sirve para sembrar estructuras de carpetas nuevas.

## Gotchas

- **Escribe en disco** (I/O impuro): crea el archivo y los directorios padre que falten (`os.makedirs(..., exist_ok=True)`).
- **No respeta locks de la app GUI**: si Obsidian esta abierto, el archivo nuevo aparecera en el vault, pero crear una nota cuyo nombre choque con una abierta y sin guardar puede provocar conflictos de version en el editor.
- Por defecto **no sobreescribe**: lanza `FileExistsError` si la nota ya existe. Pasa `overwrite=True` para reemplazar.
- Lanza `IsADirectoryError` si el destino resuelto es un directorio existente.
- El nombre de archivo se respeta tal cual (incluidos espacios); Obsidian admite espacios en nombres de nota.