Obsidian para documentar proyectos en Markdown

Autor:

ciberkaos

– Tema:

Documentación técnica para perfiles IT

– Publicado:

septiembre 9, 2026

– Actualizado:

septiembre 9, 2026

1. Introducción

En este tema aprenderás a utilizar Obsidian para crear y organizar documentación en formato Markdown. Los documentos se guardarán en una carpeta local y, posteriormente, podrán incorporarse a un repositorio de GitHub.

El objetivo no es utilizar Obsidian como una nube ni como sustituto de GitHub. Obsidian será el editor de documentación y GitHub será el lugar donde se almacenen y entreguen los proyectos.

2. ¿Qué es Obsidian?

Obsidian es una aplicación para escribir y organizar notas mediante archivos Markdown. Cada nota es un archivo de texto con extensión .md y puede abrirse también con Visual Studio Code, cualquier editor de texto o directamente desde GitHub.

Una de sus características principales es que los archivos se guardan en una carpeta normal del ordenador. Obsidian denomina bóveda o vault a esa carpeta.

Con Obsidian podemos:

Crear archivos Markdown sin memorizar inicialmente toda la sintaxis.
Organizar documentos mediante carpetas.
Insertar imágenes, enlaces, listas, tablas y bloques de código.
Relacionar documentos entre sí.
Ver el resultado mientras escribimos.
Buscar rápidamente en toda la documentación.
Mantener una colección de apuntes o proyectos en archivos locales.

Importante: una bóveda no es un formato especial ni un archivo comprimido. Es una carpeta normal que contiene documentos y recursos.

3. Obsidian, Git y GitHub no son lo mismo

Herramienta	Función
Obsidian	Crear, editar y organizar los documentos Markdown.
Git	Registrar el historial de cambios del proyecto.
GitHub	Alojar el repositorio y permitir su entrega o revisión.

El flujo de trabajo que utilizaremos será:

Escribir en Obsidian → Guardar en la carpeta local → Confirmar con Git → Subir a GitHub

4. Descargar Obsidian

La descarga debe realizarse desde la página oficial:

Descargar Obsidian

Obsidian está disponible para Windows, macOS, Linux, Android, iPhone y iPad. En este curso utilizaremos principalmente la versión de escritorio.

5. Instalación en Windows

Accede a la página oficial de descarga.
Localiza el apartado Windows.
Pulsa Universal.
Espera a que termine la descarga.
Abre el archivo de instalación descargado.
Sigue los pasos mostrados por el instalador.
Abre Obsidian desde el menú Inicio.

Si Windows muestra una advertencia, comprueba que el instalador procede del dominio oficial obsidian.md.

6. Instalación en macOS

Accede a la página oficial de descarga.
Localiza el apartado Mac.
Pulsa Universal.
Abre el archivo descargado.
Arrastra el icono de Obsidian hasta la carpeta Aplicaciones.
Abre la carpeta Aplicaciones y ejecuta Obsidian.

La primera vez, macOS puede pedir confirmación para abrir una aplicación descargada de Internet.

7. Instalación en Linux

La web oficial ofrece diferentes formatos: AppImage, Snap y paquete DEB. También aparece una versión Flatpak mantenida por la comunidad.

Opción A: paquete DEB

Esta opción resulta adecuada para Ubuntu, Debian y distribuciones derivadas.

Descarga el paquete Deb desde la web oficial.
Abre una terminal en la carpeta de descargas.
Ejecuta:

sudo apt install ./obsidian_*.deb

Abre Obsidian desde el menú de aplicaciones.

Opción B: AppImage

Descarga el archivo AppImage.
Abre una terminal en la carpeta donde se encuentre.
Concede permiso de ejecución:

chmod u+x Obsidian-*.AppImage

Ejecuta la aplicación:

./Obsidian-*.AppImage

Opción C: Flatpak

Si el sistema ya tiene Flatpak y Flathub configurados:

flatpak install flathub md.obsidian.Obsidian

Para abrirlo desde la terminal:

flatpak run md.obsidian.Obsidian

8. Crear una bóveda local

Al abrir Obsidian por primera vez aparecerá la pantalla de gestión de bóvedas.

Pulsa Create junto a Create new vault.
En Vault name, escribe:

Documentacion-ASIR

Pulsa Browse.
Selecciona una ubicación fácil de encontrar, por ejemplo Documentos.
Pulsa Create.

Obsidian creará una carpeta llamada Documentacion-ASIR. Todos los documentos de la bóveda se guardarán físicamente dentro de ella.

Una ubicación posible en Windows sería:

C:\Users\alumno\Documents\Documentacion-ASIR

En macOS o Linux podría ser:

~/Documentos/Documentacion-ASIR

No crees la bóveda en una carpeta temporal, en Descargas ni dentro de otra bóveda.

9. Crear la estructura inicial

Dentro de la bóveda crea estas carpetas desde el explorador lateral de Obsidian:

Documentacion-ASIR/
├── 00-Plantillas/
├── 01-Actividades/
├── 02-Proyectos/
├── 03-Apuntes/
└── img/

Su finalidad es:

00-Plantillas: modelos reutilizables de documentos.
01-Actividades: actividades breves realizadas durante el curso.
02-Proyectos: proyectos de mayor tamaño.
03-Apuntes: notas personales del alumno.
img: imágenes y capturas utilizadas en la documentación.

10. Crear el primer README

Selecciona la carpeta 01-Actividades.
Crea una carpeta denominada actividad-01-markdown.
Dentro de ella, crea una nota nueva.
Cambia su nombre a README.

Obsidian añadirá automáticamente la extensión y guardará el archivo como:

README.md

Escribe este contenido:

# Actividad 1: introducción a Markdown

## Descripción

Esta es mi primera documentación escrita con **Obsidian**.

## Objetivos

- Aprender a crear un README.
- Organizar una actividad.
- Insertar imágenes.
- Preparar el documento para GitHub.

## Conclusión

En esta actividad he aprendido a crear y visualizar un documento Markdown.

11. Modos de edición y lectura

Obsidian permite trabajar principalmente con dos vistas:

Vista de edición: permite modificar el documento.
Vista de lectura: muestra el documento renderizado.

También dispone de Live Preview, que presenta gran parte del formato mientras se escribe.

Utiliza la vista de lectura antes de entregar una actividad para comprobar:

Que los títulos tienen la jerarquía correcta.
Que las listas aparecen correctamente.
Que las imágenes se muestran.
Que no existen enlaces rotos.
Que los bloques de código son legibles.

12. Configuración recomendada para trabajar con GitHub

Obsidian incorpora funciones propias que no siempre funcionan igual fuera de la aplicación. Para mantener la compatibilidad con GitHub, realiza esta configuración.

12.1 Utilizar enlaces Markdown

Abre Settings.
Entra en Files and links.
Desactiva Use [[Wikilinks]].

Obsidian utilizará enlaces estándar:

[Nombre del documento](otro-documento.md)

En lugar de:

[[otro-documento]]

Los dos formatos funcionan en Obsidian, pero el primero ofrece mejor compatibilidad con otros editores y repositorios.

12.2 Actualizar enlaces automáticamente

En Settings → Files and links, mantén activada la actualización automática de enlaces internos. De esta manera, si renombras un documento desde Obsidian, sus referencias se actualizarán.

12.3 Elegir dónde se guardan las imágenes

Abre Settings.
Entra en Files and links.
Busca Default location for new attachments.
Selecciona In subfolder under current folder.
Escribe:

img

Así, cada actividad podrá conservar sus capturas junto al README:

actividad-01-markdown/
├── README.md
└── img/
    ├── paso-01.png
    └── resultado-final.png

13. Insertar imágenes

Puedes arrastrar una imagen desde el explorador de archivos hasta el documento. Obsidian la copiará a la ubicación configurada y la insertará en la nota.

Para GitHub es recomendable que el resultado utilice esta sintaxis:

![Descripción de la captura](img/paso-01.png)

Buenas prácticas:

Usa nombres descriptivos.
Evita espacios, tildes y caracteres especiales en los nombres.
Recorta las capturas para mostrar solo lo necesario.
Añade una explicación antes o después de cada captura.
No muestres contraseñas, tokens, datos personales ni direcciones privadas sensibles.
Comprueba la imagen tanto en Obsidian como en GitHub.

14. Enlaces internos y externos

Enlace a otro documento

[Consultar instalación](instalacion.md)

Enlace a una sección del mismo documento

[Ir a las conclusiones](#conclusiones)

Enlace externo

[Documentación oficial de Obsidian](https://help.obsidian.md)

Evita depender de enlaces especiales exclusivos de Obsidian si el documento debe visualizarse en GitHub.

15. Bloques de código y comandos

Para escribir un comando dentro de una frase utiliza una comilla invertida:

Ejecuta el comando `git status`.

Para escribir varios comandos utiliza un bloque e indica el lenguaje:

```bash
git add .
git commit -m "Completa la documentación"
git push
```

Ejemplo con Java:

```java
public class Principal {
    public static void main(String[] args) {
        System.out.println("Hola");
    }
}
```

16. Diagramas Mermaid

Obsidian puede representar diagramas Mermaid escritos dentro del propio documento.

```mermaid
flowchart TD
    A[Crear documentación] --> B[Revisar en Obsidian]
    B --> C[Guardar cambios con Git]
    C --> D[Subir a GitHub]
```

Antes de entregar, comprueba que el diagrama también se representa correctamente en GitHub.

17. Plantilla básica para las actividades

Guarda en 00-Plantillas un archivo llamado plantilla-actividad.md:

# Título de la actividad

## Información

- **Alumno:**
- **Asignatura:**
- **Fecha:**

## Descripción

Explicación breve de la actividad.

## Objetivos

- Objetivo 1.
- Objetivo 2.

## Desarrollo

### Paso 1

Explicación del paso.

![Descripción de la captura](img/paso-01.png)

## Problemas encontrados

Describe los problemas y las soluciones aplicadas.

## Resultado

Explica cómo has comprobado el funcionamiento.

## Conclusiones

Resume lo aprendido con tus propias palabras.

## Referencias

- [Documentación consultada](https://ejemplo.com)

18. Llevar una actividad a GitHub

La carpeta que se abra como repositorio debe contener directamente el proyecto y su documentación:

mi-proyecto/
├── README.md
├── img/
├── src/
└── otros-archivos-del-proyecto

Puedes abrir esa misma carpeta como bóveda de Obsidian mediante Open folder as vault. Así editas el README directamente dentro del repositorio y evitas mantener dos copias diferentes.

Cuando termines de documentar:

git status
git add README.md img/
git commit -m "Añade la documentación de la actividad"
git push

Después, abre el repositorio en GitHub y comprueba visualmente el README.

19. ¿Subir la configuración de Obsidian al repositorio?

Obsidian crea una carpeta oculta denominada .obsidian con la configuración de la bóveda.

Para actividades individuales normalmente no es necesario subirla. Puedes añadirla a .gitignore:

.obsidian/

Esto mantiene el repositorio centrado en la documentación y en los archivos del proyecto. Si un equipo necesita compartir una configuración concreta, deberá decidirlo expresamente.

20. Plugins y temas

Obsidian permite instalar temas y plugins, pero no son necesarios para crear buenos README.

Durante las primeras actividades se recomienda:

Utilizar el tema predeterminado.
No instalar plugins comunitarios.
Aprender primero Markdown estándar.
Introducir nuevas funciones únicamente cuando resuelvan una necesidad real.

Los plugins añaden complejidad y algunos generan contenido que no funciona correctamente fuera de Obsidian.

21. Copias de seguridad y sincronización

Que los archivos estén en el ordenador no significa que tengan una copia de seguridad.

Recomendaciones:

Utiliza Git y GitHub para los proyectos del curso.
Realiza commits frecuentes y con mensajes descriptivos.
No confundas sincronización con copia de seguridad.
No guardes contraseñas ni secretos en la bóveda.
Comprueba qué archivos vas a subir mediante git status.

Obsidian ofrece servicios opcionales de sincronización y publicación, pero no son necesarios para seguir este tema ni para entregar las actividades en GitHub.

22. Consejos de organización

Utiliza un solo # para el título principal.
Organiza los apartados con ## y ###.
Mantén nombres coherentes: actividad-01, actividad-02, etc.
Evita nombres como final, final-bueno o final-definitivo-2.
Escribe primero la explicación y añade después la evidencia.
No conviertas el README en una colección de capturas.
Incluye siempre una sección de comprobación o resultado.
Explica los errores relevantes y cómo los resolviste.
Cita las fuentes consultadas.
Revisa el documento en GitHub antes de entregar.

23. Errores frecuentes

La imagen se ve en Obsidian, pero no en GitHub

Comprueba que la imagen se encuentre dentro del repositorio y que la ruta respete exactamente mayúsculas y minúsculas:

![Resultado](img/resultado.png)

El enlace funciona en Obsidian, pero no en GitHub

Es posible que se haya utilizado un Wikilink. Sustitúyelo por un enlace Markdown estándar.

El README aparece como texto sin formato

Comprueba que se llama exactamente README.md y no README.md.txt.

Hay demasiadas imágenes en la raíz

Configura la ubicación de adjuntos y almacénalos en una carpeta img.

Obsidian no muestra una bóveda anterior

Selecciona Open folder as vault y elige la carpeta que contiene los archivos Markdown.

24. Lista de comprobación antes de entregar

El archivo principal se llama README.md.
El README está dentro del repositorio correcto.
Las imágenes están dentro del repositorio.
Las rutas de las imágenes son relativas.
Los enlaces funcionan en GitHub.
Los títulos tienen una jerarquía lógica.
Los comandos están dentro de bloques de código.
No aparecen contraseñas, tokens ni datos sensibles.
La carpeta .obsidian está excluida si no es necesaria.
Se ha realizado un commit antes de la entrega.
Se ha comprobado la presentación final en GitHub.

25. Actividad propuesta

Instala Obsidian.
Crea una bóveda local denominada Documentacion-ASIR.
Crea la estructura de carpetas indicada en este manual.
Configura los enlaces Markdown y la carpeta de imágenes.
Crea un archivo README.md utilizando la plantilla básica.
Inserta una captura en la carpeta img.
Añade una lista, un enlace y un bloque de código.
Revisa el documento en vista de lectura.
Abre la carpeta con Visual Studio Code y comprueba que el archivo continúa siendo editable.
Sube el resultado al repositorio indicado por el profesor.