---
author: Daniel A. Rodriguez
date: 2025-10-12
---

# Agregar imágenes y logo

Esta guía explica cómo incluir imágenes dentro de tu documentación y cómo añadir un logo personalizado en la barra lateral del sitio generado con Sphinx.

---

## 1. Agregar imágenes en Markdown

### Estructura recomendada

Tu proyecto Sphinx podría verse así:

```
docs/
├── source/
│   ├── _static/
│   │   └── logo.png
│   ├── guia/
│   │   ├── uso.md
│   │   └── imagenes/
│   │       └── ejemplo.png
│   ├── index.md
│   └── conf.py
└── Makefile
```

---

### Sintaxis básica de Markdown

```markdown
![Texto alternativo](imagenes/ejemplo.png)
```

> ⚠️ Usa rutas **relativas** al archivo `.md` donde insertás la imagen.

---

### Usar la directiva `{image}` de MyST

Permite controlar el tamaño, alineación y texto alternativo:

````
```{image} imagenes/ejemplo.png
:alt: Ejemplo de imagen
:width: 300px
:align: center
```
````

Opciones útiles:

| Parámetro | Descripción |
|------------|-------------|
| `:alt:` | Texto alternativo |
| `:width:` | Ancho (px o %) |
| `:height:` | Alto |
| `:align:` | `left`, `center`, `right` |
| `:scale:` | Escala porcentual (por ejemplo `50`) |

---

### Usar figuras con pie de imagen

Para mostrar un pie o número de figura, usá `{figure}`:

````
```{figure} imagenes/ejemplo.png
:alt: Ejemplo de figura
:width: 400px
:align: center

**Figura 1.** Ejemplo con pie de imagen.
```
````

---

## 2. Usar `_static` para imágenes globales

Sphinx trata `_static/` como el lugar oficial para recursos (CSS, JS, imágenes globales).

Ejemplo:

```
docs/source/_static/logo.png
```

Luego, en Markdown:

```markdown
![Logo del proyecto](_static/logo.png)
```

O bien:

````
```{image} _static/logo.png
:alt: Logo del proyecto
:width: 150px
:align: right
```
````

---

## 3. Configuración en `conf.py`

Asegurate de tener:

```python
html_static_path = ["_static"]
```

Podés agregar más rutas si querés:

```python
html_static_path = ["_static", "imagenes"]
```

---

## 4. Enlaces a imágenes externas

También podés usar URLs completas:

```markdown
![Logo de Python](https://www.python.org/static/community_logos/python-logo.png)
```

⚠️ No recomendado si querés que la documentación funcione offline.

---

## 5. Agregar un logo al tema HTML (barra lateral)

Podés mostrar tu logo en la barra lateral (por ejemplo, en `sphinx_rtd_theme` o `furo`).

### Paso 1: Guardar el logo

Colocá tu archivo en:

```
docs/source/_static/logo.png
```

---

### Paso 2: Configurar `conf.py`

Editá tu `conf.py` y añadí:

```python
# -- Logo y favicon --
html_logo = "_static/logo.png"     # Logo en la barra lateral
html_favicon = "_static/logo.png"  # Icono del navegador (opcional)
```

Para `sphinx_rtd_theme` (Read the Docs theme), asegurate de que esté instalado:

```bash
pip install sphinx-rtd-theme
```

y configuralo así:

```python
html_theme = "sphinx_rtd_theme"
html_theme_options = {
    "logo_only": True,       # Mostrar solo el logo sin texto
    "display_version": False # Ocultar versión del proyecto (opcional)
}
```

> 💡 Si no ponés `logo_only: True`, Sphinx mostrará el logo junto al título del proyecto.

---

### Paso 3: Reconstruir la documentación

```bash
make html
```

o

```bash
sphinx-build -b html source _build/html
```

Luego abrí `_build/html/index.html` en tu navegador:  
→ el logo aparecerá en la barra lateral.

---

## 6. Solución de problemas

| Problema | Causa probable | Solución |
|-----------|----------------|-----------|
| La imagen no aparece | Ruta incorrecta | Verificá la ruta relativa al archivo `.md` |
| “image not found” | Carpeta fuera de `source/` | Mové la imagen dentro de `source/` o `_static/` |
| Logo no visible | Ruta errónea o `html_logo` mal definido | Revisá `conf.py` |
| Imagen gigante | Faltó `:width:` o CSS personalizado | Usá `:width:` en `{image}` |