Biblioteca de medios

EmDash incluye una biblioteca de medios para gestionar imágenes, documentos y otros archivos. Esta guía cubre la subida, organización y uso de medios en tu contenido.

Acceder a la biblioteca de medios

Abre la biblioteca de medios desde la barra lateral del admin haciendo clic en Media. La biblioteca muestra todos los archivos subidos con previsualizaciones, nombres de archivo y fechas de subida.

Subir archivos

Desde la biblioteca de medios

1. Haz clic en Media en la barra lateral del admin

2. Haz clic en Upload o arrastra archivos al área de subida

3. Selecciona uno o más archivos de tu computadora

4. Espera a que las subidas se completen

Desde el editor de contenido

1. En el editor de texto enriquecido, haz clic en el botón de imagen

2. Haz clic en Upload en el selector de medios

3. Selecciona un archivo de tu computadora

4. Añade texto alternativo y haz clic en Insertar

Tipos de archivo soportados

EmDash soporta tipos de archivo web comunes:

Backends de almacenamiento

EmDash soporta múltiples backends de almacenamiento. Configura el almacenamiento en tu configuración de Astro:

import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: local({
        directory: "./uploads",
        baseUrl: "/_emdash/api/media/file",
      }),
    }),
  ],
});

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      storage: r2({
        binding: "MEDIA_BUCKET",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

{
	"r2_buckets": [
		{
			"binding": "MEDIA_BUCKET",
			"bucket_name": "my-media-bucket",
		},
	],
}

import { defineConfig } from "astro/config";
import emdash, { s3 } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: s3({
        endpoint: "https://s3.amazonaws.com",
        bucket: "my-media-bucket",
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        region: "us-east-1",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

Cómo funcionan las subidas

EmDash usa URLs firmadas para subidas seguras:

1. El cliente solicita una URL de subida a la API

2. El servidor genera una URL firmada con expiración

3. El cliente sube directamente al almacenamiento usando la URL firmada

4. El servidor registra los metadatos del archivo en la base de datos

Este enfoque mantiene los archivos grandes fuera de tu servidor de aplicación y permite subidas directas al almacenamiento en la nube.

Organizar medios

Carpetas

Crea carpetas para organizar tus medios:

1. Haz clic en New Folder en la biblioteca de medios

2. Introduce un nombre de carpeta

3. Haz clic en Crear

4. Arrastra archivos a carpetas para organizarlos

Búsqueda

Usa el cuadro de búsqueda para encontrar archivos por nombre. La búsqueda coincide con nombres de archivo parciales.

Filtros

Filtra medios por:

• Tipo - Imágenes, Documentos, Video, Audio
• Fecha - Rango de fecha de subida
• Carpeta - Carpeta específica

Usar medios en contenido

En el editor de texto enriquecido

1. Coloca el cursor donde quieras la imagen

2. Haz clic en el botón de imagen en la barra de herramientas

3. Selecciona una imagen de la biblioteca de medios o sube una nueva

4. Introduce texto alternativo

5. Haz clic en Insertar

Como imagen destacada

1. Abre una entrada de contenido en el editor

2. Encuentra el campo Featured Image en la barra lateral

3. Haz clic en Seleccionar imagen

4. Elige de la biblioteca de medios o sube

5. Haz clic en Guardar

En campos personalizados

Para campos configurados como tipos de imagen o archivo, haz clic en el campo para abrir el selector de medios.

Mostrar medios en plantillas

Accede a las URLs de medios desde tus datos de contenido:

---
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <img
    src={post.data.featured_image}
    alt={post.data.featured_image_alt ?? ""}
  />
)}

Imágenes responsivas

Para campos de medios de EmDash, usa el componente Image de emdash/ui:

---
import { Image } from "emdash/ui";
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
    priority
  />
)}

priority es para la imagen principal visible sin desplazamiento. Establece loading="eager" y fetchpriority="high": loading controla si la carga se difiere, y fetchpriority da al navegador una pista de prioridad para la solicitud.

Eliminar medios

1. Selecciona el/los archivo(s) que quieras eliminar

2. Haz clic en Eliminar

3. Confirma la eliminación

API de medios

Accede a los medios programáticamente usando la API de administración.

Subir un archivo

Sube medios como datos de formulario multipart:

POST /_emdash/api/media
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_TOKEN

file=<binary file data>

Una subida exitosa devuelve el elemento de medios almacenado:

{
	"success": true,
	"data": {
		"item": {
			"id": "01ABC123",
			"filename": "hero-image.jpg",
			"mime_type": "image/jpeg",
			"storage_key": "media/abc123/hero-image.jpg",
			"width": 1200,
			"height": 800
		}
	}
}

Listar medios

La siguiente solicitud lista medios bajo un prefijo:

GET /_emdash/api/media?prefix=images/&limit=20
Authorization: Bearer YOUR_API_TOKEN

Eliminar medios

La siguiente solicitud elimina un archivo almacenado:

DELETE /_emdash/api/media/images/hero.jpg
Authorization: Bearer YOUR_API_TOKEN

Proveedores de medios

Además del almacenamiento local, EmDash soporta proveedores de medios externos para alojamiento especializado de imágenes y video. Los proveedores de medios aparecen como pestañas en el selector de medios, permitiendo a los editores elegir entre múltiples fuentes.

Proveedores disponibles

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      // ... configuración de base de datos, almacenamiento
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // Opcional: dominio de entrega personalizado
          deliveryDomain: "images.example.com",
        }),
      ],
    }),
  ],
});

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      // ... configuración de base de datos, almacenamiento
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          // Opcional: configuración del reproductor
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

Usar múltiples proveedores

Puedes configurar múltiples proveedores. Cada uno aparece como pestaña en el selector de medios:

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages, cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      database: d1({ binding: "DB" }),
      storage: r2({ binding: "MEDIA" }),
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
        }),
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
        }),
      ],
    }),
  ],
});

La biblioteca de medios local (pestaña “Library”) siempre está disponible junto con cualquier proveedor configurado.

Renderizar medios del proveedor

Usa el componente Image para renderizar medios:

---
import { Image } from "emdash/ui";
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
  />
)}

El componente automáticamente:

• Detecta el proveedor del valor almacenado
• Renderiza un elemento <img> optimizado
• Aplica optimizaciones específicas del proveedor (ej. transformaciones de Cloudflare Images)

Tipo MediaValue

Los campos de medios almacenan un objeto MediaValue que contiene información del proveedor:

interface MediaValue {
  provider?: string;    // ID del proveedor, por defecto "local"
  id: string;           // ID específico del proveedor
  src?: string;         // URL directa (para medios locales o valores de cadena simple)
  previewUrl?: string;  // URL de previsualización para mostrar en admin (proveedores externos)
  filename?: string;    // Nombre de archivo original
  mimeType?: string;    // Tipo MIME
  width?: number;       // Ancho de imagen/video
  height?: number;      // Alto de imagen/video
  alt?: string;         // Texto alternativo
  meta?: Record<string, unknown>; // Metadatos específicos del proveedor
}

Esto permite a EmDash renderizar medios correctamente independientemente de dónde estén alojados.

Próximos pasos

• Trabajar con contenido - Usar medios en tu contenido
• Crear un blog - Añadir imágenes a publicaciones de blog
• Consultar contenido - Mostrar medios en plantillas